▋
agent/skill-maker/SKILL.md

name: skill-maker description: >- Create a new local agent skill using the user's symlink convention. Use when the user wants to make, scaffold, register, or symlink a reusable skill across Claude, Codex, agent, and optionally OpenCode skill roots.

skill-maker

Create local skills with a versioned source of truth, then symlink that skill into the runtime roots that should see it.

Runtime roots are link destinations, not source directories:

  • ~/.agents/skills/<name>
  • ~/.claude/skills/<name>
  • ~/.codex/skills/<name> (skip with --no-codex)
  • ~/.config/opencode/skills/<name> when that root exists and is wanted

Versioned source roots — user-level runtime roots link only to skills we author:

  • Personal skills live in this repo (~/volpestyle/skills), grouped into category folders — review/, agent/, app-dev/, creative/, platform/. The source root is auto-detected from where create-skill.sh lives (overridable via SKILLS_REPO_ROOT), so the clone path doesn't matter. Pass --category <cat> to drop the new skill in the right folder; the runtime name is always the folder basename, independent of category.
  • Team (RCS Studio) skills live flat in ~/vibes/repos/rcsstudio/claude-code-skills/skills/<name>: run the script with SKILLS_REPO_ROOT set to that skills/ dir and no --category (its category nudge doesn't apply there).
  • A repo's own auxiliary skills live under <repo>/.agents/skills/<skill-name> and are exposed only through that repo's .claude/skills/ and .codex/skills/ links — never linked into a user-level root.

Third-party tool skills (e.g. herdr) are not linked to an upstream clone: a clone only updates when pulled, and its default branch runs ahead of the installed release, so the skill drifts from the tool either way. Load the copy the tool's own updater keeps current instead — when the tool prints its skill (herdr --skill), add a stub here that keeps the upstream name and description and whose body runs that command (see agent/herdr).

When to use this

Use this when the user asks to create a skill, scaffold a skill, or make a skill available across agents with symlinks.

Do not use this for one-off prompt writing unless the user wants a reusable skill installed on this machine.

Command

~/.claude/skills/skill-maker/create-skill.sh --category <cat> <skill-name> [description]

$REPO below is the auto-detected source root (the repo the script lives in, overridable via SKILLS_REPO_ROOT). With --category app-dev (for example), this creates:

  • Source directory: $REPO/app-dev/<skill-name>
  • Source file: $REPO/app-dev/<skill-name>/SKILL.md
  • Symlink: ~/.agents/skills/<skill-name> -> $REPO/app-dev/<skill-name>
  • Symlink: ~/.claude/skills/<skill-name> -> $REPO/app-dev/<skill-name>
  • Symlink: ~/.codex/skills/<skill-name> -> $REPO/app-dev/<skill-name>

The runtime skill name is always the folder basename, independent of category. Omitting --category drops the skill at the repo root ($REPO/<skill-name>) and prints a nudge — prefer a best-fit category so the layout stays consistent.

If ~/.config/opencode/skills exists, the script also links the skill there. Use --no-codex or --no-opencode to skip those links:

~/.claude/skills/skill-maker/create-skill.sh --category agent --no-opencode <skill-name> [description]

Safety Rules

  • Treat the auto-detected skills repo ($REPO/<category>/<name>) as the default versioned source of truth — never a path inside a runtime root.
  • Keep ~/.agents/skills and ~/.claude/skills as symlink forests. Do not put a new plain skill directory there.
  • If an existing plain directory is found under ~/.agents/skills/<name>, move it to $REPO/<category>/<name> and symlink back instead of editing it in place.
  • Never copy or link a third-party tool's skill from a source clone; stub it over the tool's own print command as described above.
  • Never overwrite an existing non-empty skill directory.
  • Never replace an existing non-symlink destination.
  • If a destination symlink already points to the source, leave it alone.
  • If a destination symlink points somewhere else, stop and report it.
  • Keep the generated SKILL.md minimal so it is easy to hand-edit.

Content guidelines — what belongs in a SKILL.md

Write down what was expensive to learn, not what was fun to make. Include:

  1. Gotchas — environment quirks and failure modes that cost real failed attempts to discover (platform differences, strict argument order, missing tools).
  2. Incantations — exact syntax for tools whose commands are arcane and fail non-obviously; hard-won, keep verbatim.
  3. Transferable process wisdom — workflow lessons that apply across sessions ("curate from a contact sheet before laying out", "expect 2-3 render-look-fix iterations").
  4. Facts about external systems — pagination schemes, URL formats, API quirks. Specific is fine here; these are facts, not taste. One carve-out: never state a capability absence as fact ("there is no X tool", "you can't do Y via API"). Absences rot silently when the surface grows, and they're self-sealing — a reader who believes them never re-checks. Encode the discovery procedure instead ("probe for X; if missing, fall back to Z"); positive facts are fine because they fail loudly at use time.

Do NOT bake in creative output: exact coordinates, color palettes, layout parameters, or anything that was a judgment call for one particular result. Frame those as one-line idea seeds at most. A skill that encodes judgment becomes a stencil — every future use converges on one past session's taste instead of designing fresh to the material at hand.

Match specificity to fragility. Exact commands and a fixed order belong only where exactly one sequence is safe (destructive git, auth, a script's argument order); for judgment work — placement, grouping, wording, review — state the outcome, the constraints, and how to verify, and let the session plan. A numbered script for a judgment task replays one author's plan on every run. Give each prohibition its reason, or restate it as the behavior wanted.

The frontmatter description is routing text: name the categories of intent that should trigger the skill and what it is not for, rather than a list of phrasings — one synonym per missed trigger is how descriptions bloat and generalize worse.

Reference a skill's own scripts and files through the runtime root — ~/.claude/skills/<name>/… — which resolves in every harness via the symlink. Never ~/skills/… or the category path inside the source repo; those paths are dead everywhere but the author's mental model.

Authoring hazard: the harness substitutes $0/$1-style tokens in a skill body with the invocation args at load time. Never put literal positional variables in embedded code (awk, shell scripts) — rewrite around them (e.g. grep '^U' instead of awk '$1 ~ /^U/').

Test for any line: "would a fresh session waste real cycles rediscovering this?" If yes, keep. If it merely records what was made last time, cut.

Workflow

  1. Run the script with a kebab-case skill name and short description, plus a best-fit --category.
  2. Edit the generated SKILL.md: trigger conditions in the description; outcome, constraints, gotchas, and any fragile-op commands in the body.
  3. If the skill needs helper scripts, place them in the versioned source directory under $REPO/<category>/<skill-name>.
  4. Report the created source path and symlink destinations to the user.

Migration Policy

For previously unversioned skills that live as plain directories in ~/.agents/skills (or ~/.claude/skills), move the whole directory into $REPO/<category>/<name> and replace the original path with a symlink back to the skills repo source. Existing ~/.claude/skills/<name> links should also point to the same source; keep or recreate runtime entries as links, not copies.

For diverged duplicate skills, choose a single owner: the personal or team skills repo for skills we author, and the tool's installed copy (via a stub, as with herdr) for a third-party tool's skill.