alias
/alias
Use when creating shortcut aliases for existing larch skills with preset flags. Routes plugin-source aliases to skills/ unless --private forces .claude/skills/.
- Author
- character-ai ↗
- Repository
- larch ↗
- Licence
- MIT
- Last repository change
- 08.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 4
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 08.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- SKILL.md zawiera komentarze HTML (4). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
Use when creating shortcut aliases for existing larch skills with preset flags. Routes plugin-source aliases to skills/ unless --private forces .claude/skills/.
Arguments
/alias [--merge] [--private] <alias-name> <target-skill> [preset-flags...]
Original author description
Use when creating shortcut aliases for existing larch skills with preset flags. Routes plugin-source aliases to skills/ unless --private forces .claude/skills/.
How it works
- NEVER
SKILL.md preview
---
# larch-run-lifecycle: shared-v1 skill=alias
name: alias
description: "Use when creating shortcut aliases for existing larch skills with preset flags. Routes plugin-source aliases to skills/ unless --private forces .claude/skills/."
argument-hint: "[--merge] [--private] <alias-name> <target-skill> [preset-flags...]"
allowed-tools: Bash, Skill
---
**MANDATORY: Follow the complete shared lifecycle contract in `${CLAUDE_PLUGIN_ROOT}/skills/shared/run-lifecycle.md` with declared skill `alias`.**
# Alias Skill
**MANDATORY: READ ENTIRE FILE before composing user-facing prose: `${CLAUDE_PLUGIN_ROOT}/skills/shared/readability-style.md`.**
This skill follows the Process pattern: numbered steps, checkpointed delegation, fail-closed verification.
Create an alias skill that forwards to an existing larch skill with preset flags. Delegates to `/implement` for the full pipeline (implementation, code review, PR), then verifies the artifact landed on disk.
**Target directory** is resolved automatically:
- A **git repository is required**: the helper (`"${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" alias resolve-target`) anchors all paths at the typed repository worktree and fail-closes outside a git working tree. Run `git init` first if you want to use `/alias` in a fresh project.
- Inside a Claude plugin source repo (detected via the two-file predicate `.claude-plugin/plugin.json` AND `skills/implement/SKILL.md` at the git repo root, matching `validate-args.sh`), the alias is generated under `skills/<alias-name>/SKILL.md` (exported plugin skill, ships with the plugin).
- In any other git repository (consumer repos with their own larch installation), the alias is generated under `.claude/skills/<alias-name>/SKILL.md` (dev-only repo-private skill).
- `--private` forces `.claude/skills/<alias-name>/` even inside a plugin repo (escape hatch when the operator wants a private alias in plugin source). In non-plugin repos `--private` is a no-op.
Example (in a plugin source repo): `/alias i implement --merge` creates `<repo-root>/skills/i/SKILL.md` so that `/i <feature>` is equivalent to `/implement --merge <feature>`.
Example (in a consumer repo, OR with `--private` in a plugin repo): `/alias i implement --merge` creates `<repo-root>/.claude/skills/i/SKILL.md` (dev-only).
Example with merge: `/alias --merge i implement --merge` creates the alias AND merges the PR after CI passes.
## NEVER
1. **NEVER create an alias that targets `/alias`**: no alias-to-alias recursion. **Why:** would multiply indirection and break the flat forwarding contract. Enforced by Step 2 check #5.
2. **NEVER let an alias name shadow an existing larch skill**: neither in `skills/` (public) nor `.claude/skills/` (dev-only). **Why:** shadowing silently reroutes `/<name>` invocations. Enforced by Step 2 check #2 via dynamic probe.
3. **NEVER auto-remediate when `VERIFIED=false` in Step 4**: do NOT retry `/implement`, roll back, or delete the PR. **Why:** under `--merge` the PR may already be merged; retry would create a divergent PR. Human judgment required.
4. **NEVER assume success on `VERIFIED=false` just because `/implement` returned.** **Why:** `/implement` can return cleanly while writing the file to the wrong path, skipping the generator, or failing silently: the sentinel-file gate is the only authoritative signal.
5. **NEVER parse `--merge` or `--private` tokens after the first positional argument as flags for `/alias`.** **Why:** both flags have a dual role (consumed by `/alias` when before the first positional; passed through to the alias's preset flags otherwise); conflating the two is a silent footgun.
6. **NEVER hardcode `.claude/skills/<alias-name>` or `skills/<alias-name>` paths anywhere in Steps 2/3/4: always thread `$TARGET_DIR`.** **Why:** the resolved target directory is the single source of truth (computed once at Step 2 by `alias resolve-target`); a partial edit that re-introduces a hardcoded path in one site (e.g., the `/implement` recipe) but not another (e.g., the verify sentinel) creates a silent path split where `/implement` writes one tree and Step 4 verifies a different tree. Enforced by `make test-alias-structure` (CI).
7. **NEVER use `eval "$("${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" alias resolve-target ...)"` to consume the helper's stdout.** **Why:** `eval` of a path that contains shell metacharacters (spaces, `$(...)`, backticks) creates shell-injection risk if the command's stdout contract ever drifts. Use the non-eval allowlist parser shown in Step 2's bash block.
**Anti-halt continuation reminder.** After every child `Skill` tool call (e.g., `/implement`) returns, IMMEDIATELY continue with this skill's NEXT numbered step: do NOT end the turn on the child's cleanup output, and do NOT write a summary, handoff, status recap, or "returning to parent" message: those are halts in disguise. The rule is strictly subordinate to any explicit non-sequential control-flow directive in THIS file (e.g., `bail`, `skip to Step N`). A normal sequential `proceed to Step N+1` instruction is the default continuation this rule reinforces, NOT an exception. Every `scripts/larch.sh checks run-relevant` invocation anywhere in this file is covered by this rule. → shared/subskill-invocation.md#anti-halt; do not load for routine invocations: load only when debugging or adding a child-Skill invocation.
<!-- step:1: Parse Arguments -->
Parse flags from the start of `$ARGUMENTS` before treating the remainder as positional arguments.
- `--merge`: Set `alias_merge=true`. Default: `alias_merge=false`. When true, `--merge` is forwarded to the `/implement` invocation so the resulting PR is also merged.
- `--private`: Set `alias_private=true`. Default: `alias_private=false`. When true, the new alias is forced under `.claude/skills/<alias-name>/` regardless of plugin-repo detection (escape hatch for creating a private alias inside a plugin source repo). When absent: target is `skills/<alias-name>/` if running in a plugin source repo, else `.claude/skills/<alias-name>/`. In non-plugin repos `--private` is a no-op (the default is already `.claude/skills/`). The flag is consumed by `/alias` only: it does NOT appear in the generated alias's preset flags.
- `--run-id <ID>`: Flag semantics are in `${CLAUDE_PLUGIN_ROOT}/skills/shared/run-id-flag.md`.
| Position | Meaning |
|----------|---------|
| After first positional token | Pass-through to the generated alias's preset flags |
After flag stripping, parse the remaining positional arguments:
- First token = **alias name**
- Second token = **target skill name** (without `/` prefix)
- Remainder = **preset flags** (may be empty: a pure rename shortcut is valid)
<!-- step:2: Validate -->
All validation uses Bash since `${CLAUDE_PLUGIN_ROOT}` is a shell variable not resolvable in Read/Glob.
### Plugin-repo detection + target-dir resolution
Before running the validation table below, resolve the target directory (`$TARGET_DIR`) once via the helper script. The script's stdout is the single source of truth for `(plugin-detect, --private) → TARGET_DIR`; thread the resolved value through Check 6, Step 3 (`/implement` recipe + announce line), and Step 4 (verify sentinel). Distinct from `${CLAUDE_PLUGIN_ROOT}` (the plugin install path used by Check 2): `$REPO_ROOT` is the git working tree where the alias is materialized; the two can diverge in practice and Check 2's shadow probe is orthogonal to where the new alias is written.
```bash
# Build the optional --private flag dynamically.
PRIVATE_FLAG=()
if [[ "$alias_private" == "true" ]]; then
PRIVATE_FLAG=(--private)
fi
# Non-eval line-by-line parse with explicit allowlist (per NEVER #7).
# Do NOT use `eval "$("${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" alias resolve-target ...)"`: paths containing spaces / $(...) /
# backticks would be re-interpreted by the shell.
REPO_ROOT=""; PLUGIN_REPO=""; TARGET_DIR=""
while IFS='=' read -r key val; do
case "$key" in
REPO_ROOT|PLUGIN_REPO|TARGET_DIR) declare "$key=$val" ;;
esac
done < <("${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" alias resolve-target \
--alias-name "<alias-name>" "${PRIVATE_FLAG[@]}")
# Fail-closed if the helper exited with empty values (e.g., not in a git repo).
# `alias resolve-target` writes its diagnostic to stderr; surface a usable error to the operator.
if [[ -z "$TARGET_DIR" || -z "$REPO_ROOT" || -z "$PLUGIN_REPO" ]]; then
echo "**ERROR: alias resolve-target failed (likely not in a git repository, or repository access failed). Cannot determine target directory for alias '<alias-name>'.**"
exit 1
fi
```
The helper's stdout schema and the two-file plugin-detect predicate (`.claude-plugin/plugin.json` AND `skills/implement/SKILL.md`) live in `crates/larch-cli/src/developer_tooling_commands.rs`. Operators wanting a private alias inside a plugin repo use `--private`.
### Validation table
| # | Check | Rule | On fail |
|---|-------|------|---------|
| 1 | Alias name format | Must match `^[a-z][a-z0-9-]*$` (lowercase, alphanumeric + hyphens, must start with a letter) | `E_ALIAS_NAME` |
| 2 | Reserved name (dynamic probe) | `${CLAUDE_PLUGIN_ROOT}` must be set; alias name must not collide with any directory under `${CLAUDE_PLUGIN_ROOT}/skills/<alias-name>` OR `${CLAUDE_PLUGIN_ROOT}/.claude/skills/<alias-name>`. See `### Check 2` block below. | `E_PLUGIN_ROOT_UNSET` or `E_SHADOW` |
| 3 | Target name format | Must match `^[a-z][a-z0-9-]*$` (same format as alias names) | `E_TARGET_NAME` |
| 4 | Target skill exists | `test -f "${CLAUDE_PLUGIN_ROOT}/skills/<target>/SKILL.md"`; if missing, also run `ls "${CLAUDE_PLUGIN_ROOT}/skills/"` for discoverability | `E_TARGET_MISSING` |
| 5 | Target is not `alias` | Forbid alias-to-alias recursion | `E_RECURSION` |
| 6 | Collision check | `test -e "$TARGET_DIR"` must be false (uses `-e` not `-d` so a regular file at that path is also caught) | `E_COLLISION` |
### Check 2: reserved-name dynamic probe
Fail-closed on unset `${CLAUDE_PLUGIN_ROOT}`, then probe both plugin-tree roots for a directory collision:
```bash
if [[ -z "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
echo "**ERROR: CLAUDE_PLUGIN_ROOT is unset: cannot probe larch skill tree for reserved-name collision.**"
exit 1
fi
# probe BOTH roots: skills/ (public) and .claude/skills/ (dev-only: release)
if test -d "${CLAUDE_PLUGIN_ROOT}/skills/<alias-name>" \
|| test -d "${CLAUDE_PLUGIN_ROOT}/.claude/skills/<alias-name>"; then
echo "**ERROR: alias name '<alias-name>' shadows an existing larch skill.**"
exit 1
fi
```
One conceptual rule: "alias cannot shadow any larch skill": replacing the prior static enumeration that was drifting as new skills shipped.
### Error strings (reference)
| ID | Printed string |
|----|----------------|
| `E_ALIAS_NAME` | `**ERROR: Alias name '<name>' is invalid. Must start with a lowercase letter and contain only lowercase letters, digits, and hyphens.**` |
| `E_PLUGIN_ROOT_UNSET` | `**ERROR: CLAUDE_PLUGIN_ROOT is unset: cannot probe larch skill tree for reserved-name collision.**` |
| `E_SHADOW` | `**ERROR: alias name '<alias-name>' shadows an existing larch skill.**` |
| `E_TARGET_NAME` | `**ERROR: Target name '<target>' is invalid. Must contain only lowercase letters, digits, and hyphens.**` |
| `E_TARGET_MISSING` | `**ERROR: Target skill '<target>' does not exist.**` (then run `ls "${CLAUDE_PLUGIN_ROOT}/skills/"` and abort) |
| `E_RECURSION` | `**ERROR: Cannot create an alias that targets /alias (no alias-to-alias recursion).**` |
| `E_COLLISION` | `**ERROR: '$TARGET_DIR/' already exists. Remove it first or choose a different name.**` (interpolate the resolved `$TARGET_DIR` so the operator sees the actual path) |
<!-- step:3: Delegate to /implement -->
### Before delegating, ask
- **What does `/implement` need to build this deterministically?** `/implement` has no codebase context about `/alias`: it will research and guess unless the feature description cites the generator script path, its required flags, the version source, and the write target. The explicit recipe below supplies all four.
- **What could make the Step 4 verification silently pass when it shouldn't?** Nothing: the `verify skill-called --sentinel-file` gate reads a child-produced artifact at `$TARGET_DIR/SKILL.md` (resolved at Step 2 from the `alias resolve-target` helper) that the outer orchestrator cannot synthesize. A parent-writable gate would not be load-bearing.
- **Why no retry on `VERIFIED=false`?** Under `--merge` the PR may already be merged by the time control returns; any automated retry would create a divergent PR. Step 4 surfaces branch-specific diagnostic messages instead, leaving recovery to human judgment.
Construct an explicit feature description for `/implement`. The description MUST cite the generator script path, its required flags, the version source, and the write target so `/implement` has a complete, deterministic build recipe: no codebase research required. The write target uses the `$TARGET_DIR` resolved at the top of Step 2 (NOT a hardcoded `.claude/skills/<alias-name>` path: see NEVER #6):
```
Add /<alias-name> alias for /<target-skill> <preset-flags>.
Generate the alias skill by running:
mkdir -p "$TARGET_DIR"
"${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" alias generate \
--name "<alias-name>" \
--target "<target-skill>" \
--target-dir "$TARGET_DIR" \
--flags "<preset-flags>" \
--version "$(jq -r .version "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json")" \
> "$TARGET_DIR/SKILL.md"
If jq fails or plugin.json is malformed, proceed with an empty --version value (the generator handles this: the footer simply omits the vX.Y.Z suffix).
```
When constructing the feature description string, substitute the actual `$TARGET_DIR` value resolved at Step 2 into the recipe so `/implement`'s child run sees a fully-expanded literal path (rather than depending on `$TARGET_DIR` being set in `/implement`'s child environment, which it would not be).
Omit the `<preset-flags>` segment from the leading sentence when empty (pure rename shortcut).
Print: `**Alias /<alias-name> -> /<target-skill> <preset-flags>: target: $TARGET_DIR: delegating to /implement [--merge]**` (interpolate the resolved `$TARGET_DIR` so the operator sees at a glance which target was selected; omit `<preset-flags>` if empty; omit `--merge` if `alias_merge=false`).
Invoke the Skill tool:
- Try skill: `"implement"` first (bare name). If no skill matches, try skill: `"larch:implement"` (fully-qualified plugin name).
- args: --lifecycle-parent-context "$CONTEXT_FILE" [--merge] `<feature-description>`
Only include `--merge` in the args if `alias_merge=true`.
> **Continue after child returns.** When `/implement` returns, execute Step 4: do NOT end the turn, and do NOT write a summary, handoff, or "returning to parent" message. → shared/subskill-invocation.md#anti-halt; do not load for routine returns: load only when adding a child-Skill invocation or debugging.
<!-- step:4: Verify -->
After `/implement` returns, verify the alias SKILL.md actually landed on disk. The sentinel path uses the `$TARGET_DIR` resolved at Step 2 (no separate `git rev-parse` here: the resolved value is the single source of truth, fail-closed at Step 2 if git failed):
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/larch.sh" verify skill-called \
--sentinel-file "$TARGET_DIR/SKILL.md"
```
Parse stdout for `VERIFIED=true|false` and `REASON=<token>`.
- **If `VERIFIED=true`**: exit 0.
- **If `VERIFIED=false`**: print a fail-closed error and exit 1. Branch the message on `alias_merge`:
- **If `alias_merge=false`** (PR created but not merged):
```
**ERROR: /implement returned but $TARGET_DIR/SKILL.md was not written (REASON=<token>). DO NOT merge the PR. Inspect the PR/branch manually: /implement may have written the file elsewhere, skipped the generator, or failed silently.**
```
- **If `alias_merge=true`** (PR may already be merged):
```
**ERROR: /implement returned but $TARGET_DIR/SKILL.md was not written (REASON=<token>). The PR may have already been merged: do not assume success. Inspect the PR/branch/merged-main manually; a revert or follow-up PR may be required.**
```
Do not attempt auto-remediation: `/implement` has already created (and possibly merged) the PR, so any recovery requires human judgment.
### Authoritative exit states
| State | Condition | Printed string (summary) |
|-------|-----------|--------------------------|
| Success | `VERIFIED=true` | Created `$TARGET_DIR/SKILL.md` |
| Validation fail | Any Step 2 check fails | one of the `E_*` strings from the Step 2 `Error strings (reference)` table |
| Verify fail (unmerged) | `VERIFIED=false` AND `alias_merge=false` | `**ERROR: /implement returned but $TARGET_DIR/SKILL.md was not written (REASON=<token>). DO NOT merge the PR. ...**` (full string above) |
| Verify fail (merged) | `VERIFIED=false` AND `alias_merge=true` | `**ERROR: /implement returned but $TARGET_DIR/SKILL.md was not written (REASON=<token>). The PR may have already been merged ...**` (full string above) |
Versions
The database has no other skills named alias.
Database snapshot: 13.11.2026 · package version 9f85a3406e91 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95glab-alias
Create, list, and delete GitLab CLI command aliases and shortcuts. Use when creating custom glab commands, managing CLI shortcuts, or viewing existing aliases. Triggers on alias, shortcut, custom command, CLI alias. - 96status
Use when checking larch plugin health: reports the current larch version and checks availability of external vendor tools (Codex and Cursor) using the same probe machinery as /implement. - 100skills-eval
Evaluate Claude skill quality through auditing. Use when reviewing or auditing skills. - 95writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment - 100upgrade-larch
Use when upgrading larch to the latest stable plugin and matching verified executable. - 95writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment