New Skill Creator

/new-skill-creator

What this skill does

This is a maintainer's authoring loop, and it assumes a skills repo you own. It writes a new skill into your clone, links that clone into your runtimes, and pushes. The linking below is the opposite of what README.md tells you to do when installing this pack — and deliberately so. A symlink means your agent runs whatever the next git pull brings, with no moment where you read the diff; that is the drift THREAT-MODEL.md names, and it is why copying is the default there. Linking here does not make that drift go away — it accepts it, on the same terms README already states: you're maintaining the pack, or you read every pull. Authoring a skill does not pre-review a contributor's later commit to it, or your own work from another machine. Installing skills someone else maintains is a different act — copy those.

Creates a new skill in your skills repo, links it into all three agent runtimes (Claude Code, Codex, and the shared .agents/ dir), commits and pushes to GitHub. Supports two formats:

• Single-doc — one SKILL.md (default for short routers, triggers, mode-setters, reference cards).
• Dual-doc — SKILL.md (human-readable, self-sufficient) + protocol.yon (declarative, mechanically validatable protocol) (default for heavy procedural skills with phases, gates, severity-ranked rules). See section 2b.

Structured execution spec: protocol.yon. Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the @STAMP date.

Steps

1. Gather info

Ask the user (on Claude Code, use AskUserQuestion for structured options; on Codex or other agents without that tool, ask via prose with options as a numbered list):

• What should this skill be called? (kebab-case, becomes /skill-name)
• What does it do — one sentence?
• When should it trigger? Give 2-3 example phrases a user might say.
• Could this skill be confused with an existing skill? If yes, list the ones it's most similar to — we'll add boundary clauses to clarify.
• Should only the user invoke it (not Claude auto-trigger)? Default: yes for workflows with side effects.
• Is this skill runtime-specific? Default: no — skills are available in all three targets (Claude Code, Codex, and the shared .agents/ dir). Only mark runtime-specific if the skill depends on tools or capabilities that are not available in the other runtime(s).
• Dual-doc or single-doc? Apply the criterion below; default to single-doc if uncertain.
• Caller Options participant? If the skill has genuine venue or mode optionality worth surfacing to the caller, add the COP opt-in block — see caller-options/references/OPT-IN-BLOCK.md.
• Next-skills participant? If, after this skill finishes, there are natural successor skills worth recommending to the user, add the NSP opt-in block — see next-skills/SKILL.md and the subsection below.
• Self-improvement participant? If this is a capable procedural skill (phases, gates, judgment) that a run could expose a tunable weakness in, add the SIP opt-in block (self-improvable: true) — see self-improve/SKILL.md and the subsection below. Routers / mode-setters / reference cards omit it.
• Public or private? Decide visibility: — private if the skill couples to personal infrastructure or proprietary IP (vault paths, personal domains, proprietary engines); public if it is generic and reusable.

Dual-doc criterion

Use dual-doc (SKILL.md + protocol.yon) when the skill has any of:

• 3+ ordered phases or steps
• Explicit gates / checks / verification points
• Tabular routing or decision logic (decision tables, lookup maps)
• Severity-ranked rules (MUST/SHOULD/MUST_NOT)
• Projected length > ~150 lines

Use single-doc (SKILL.md only) when the skill is:

• A trigger / router / mode-setter
• A reference card or schema doc
• A short utility wrapper (< ~100 lines)
• Mostly explanatory prose with no enforceable rules

When in doubt, single-doc. You can always migrate later via the section 6 recipe.

2. Create the skill folder and SKILL.md (single-doc default)

Create: <skills-repo>\skills\{skill-name}\SKILL.md

Frontmatter:

• name: {skill-name}
• description: {one sentence + trigger examples, max 250 chars}
• disable-model-invocation: true (if user confirmed yes above — see criterion below)
• runtime: (optional, see below) — list of runtimes this skill supports. Default is all three: [claude, codex, agents]. Omit the field entirely when the default applies.
• visibility: public or private — required (see the "Public or private?" item in Step 1). The canonical value lives in front-matter; if your library keeps a separate public/private index, record it there too.

Description rules:

• One sentence describing what the skill does.
• Followed by 2-3 example trigger phrases the user might say.
• Keep under 250 characters total when possible (some skills exceed this — don't pad, don't truncate at the cost of clarity).
• Sibling-boundary clauses: if this skill could be confused with an existing skill (similar trigger phrases or domain), include in the description a "Not for X — use Y" clause that points to the sibling. Example: obsidian-markdown description ends with "Use obsidian-cli instead when the action needs a running Obsidian". Boundary clauses are how the auto-router disambiguates similar skills — without them, two skills with overlapping trigger phrases will compete and one will silently lose.

disable-model-invocation criterion

See references/CRITERION.md for the full rule, examples, and decided borderline cases. Apply it when writing the front-matter disable-model-invocation: field.

Next-skills (NSP) opt-in

If the skill has natural successor skills, join the Next Skills protocol by adding three synced parts (per-skill front-matter is canonical):

1. Front-matter — a next-skills: list, each entry skill + phrase (activation phrase) + why (one line):

   next-skills:
     - skill: insight-assess
       phrase: "/assess"
       why: "Evaluate the options you just generated and pick one"
   

2. SKILL.md prose pointer — paste as the last section of the body (NSP runs on completion, unlike COP which runs first):

   Next skills. On completion, run the Next Skills protocol (next-skills/SKILL.md): surface the next-skills recommendations from front-matter for the caller to pick. Offer only — never auto-invoke.

3. protocol.yon (dual-doc only) — a closing @STEP rid=step:nsp as the last step. See next-skills/SKILL.md for the exact form.

Self-improvement (SIP) opt-in

If the skill is a capable procedural skill (phases, gates, judgment — i.e. something a run can expose a tunable weakness in), join the Self-Improvement Protocol so the skill proposes its own fixes when a run surfaces a concrete signal. Pure single-doc routers, mode-setters, and reference cards omit it — there's nothing to tune from a run. Dual-doc skills should declare the field either way: a genuinely-exempt dual-doc skill (rare — e.g. a meta-protocol that would detect itself, like self-improve) sets self-improvable: false to record the deliberate decision. Three synced parts (per-skill front-matter is canonical):

1. Front-matter — self-improvable: true.
2. SKILL.md prose pointer — paste as the last section of the body (SIP runs on completion, after NSP where present):

   Self-improvement. On completion, run the Self-Improvement Protocol (self-improve/SKILL.md): if this run surfaced a concrete, blocking-or-recurring weakness in this skill, propose a specific fix for the handler to approve. Conservative — silent otherwise. Never auto-apply.

3. protocol.yon (dual-doc only) — a closing @STEP rid=step:sip as the last step, after step:nsp. See self-improve/SKILL.md for the exact form.

Content: write clear step-by-step instructions based on what the user described.

2b. Create the skill folder and dual-doc files (dual-doc skills)

When the dual-doc criterion applies, scaffold two files:

skills/{skill-name}/
├── SKILL.md          # frontmatter + human overview + self-sufficient body + pointer to protocol.yon
└── protocol.yon      # @DOC kind=skill | profile=exec — rules, steps, checks

SKILL.md shape (dual-doc):

1. Frontmatter (same fields as single-doc).
2. One-paragraph human overview — what the skill does and when it triggers.
3. Self-sufficient summary body — instructions complete enough that a runtime which ignores protocol.yon (Codex today, and other agents reading the shared dir) still produces acceptable behavior. This is non-negotiable because of multi-runtime.
4. Pointer block, exact phrasing: "Structured execution spec: protocol.yon. Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the @STAMP date."
5. Optional: critical examples or trace formats that benefit from prose.

protocol.yon shape:

Use an existing dual-doc skill's protocol.yon in this repo as a template — e.g. cold-review/protocol.yon for a governed, multi-step skill.

Required elements:

• @DOC ver=2.0 | kind=skill | id={skill-name} | title="..." | profile=exec | fmt=min | guide="https://yon.younndai.com/yon-guide.txt"
• @INTENT goal="..." | trigger="..."
• @STAMP ts:ts=YYYY-MM-DDTHH:MM:SSZ | src=human | method=manual
• @SEC blocks for logical grouping
• @RULE rid=... | lvl=MUST|SHOULD|MUST_NOT | when="..." | then="..." for constraints
• @STEP rid=... | n:int=N | op=... | args=[...] | in=[...] | out=[...] for ordered steps
• @CHECK rid=... | assert="..." | fail=WARN|ABORT|SKIP | msg="..." for gates
• @CATCH / @RETRY for error handling where relevant
• @MAP for tabular configs (decision tables, routing tables, lookup tables)
• Closing @STAMP for the YON-author pass

Drafting the protocol.yon:

• Use yon-write to draft the body.
• Reference yon-read for the canonical tag and type registry.
• Validate the result with the public parser before committing: npx @younndai/yon-parser validate protocol.yon --profile exec.

Multi-runtime safety (critical):

The SKILL.md body MUST be execution-sufficient on its own. Runtime discovery and loading behavior varies, and the presence of protocol.yon does not prove that a host reads or enforces it. Treat protocol.yon as an inspectable, mechanically validatable companion that adds precision for readers and tooling; never make operational completeness depend on implicit YON loading.

3. Link into all three runtimes

Authoring your own skills only — see what this skill does. Linking makes your edits live without a re-copy on every save, which is what you want while writing a skill and not what you want while running someone else's.

Your skills repo is the single source of truth. Each runtime reads from its own directory, so we create three parallel direct runtime links, all pointing back to the same repo source. No chaining — every link goes straight to the repo. The links are at the directory level, so any companion files (protocol.yon, references/, personas/, etc.) travel automatically with no extra symlinking needed.

In the commands below, $HOME / %USERPROFILE% / $env:USERPROFILE expand to your home directory on any machine — no edit needed. The repo path shown (<skills-repo>) is your clone of the skills repo; substitute your own clone path if it differs.

On Linux/macOS:

ln -s /path/to/skills-repo/skills/{skill-name} "$HOME/.agents/skills/{skill-name}"
ln -s /path/to/skills-repo/skills/{skill-name} "$HOME/.claude/skills/{skill-name}"
ln -s /path/to/skills-repo/skills/{skill-name} "$HOME/.codex/skills/{skill-name}"

Windows + Git Bash: do not use ln -s even though bash is available. On this setup, ln -s silently creates a real directory copy instead of a symbolic link (no error, no warning) — confirmed by the v2 phase 4 dry-run. Use the Windows mklink /D commands below, prefixing the bash invocation with MSYS_NO_PATHCONV=1 when running via the Bash tool to keep paths intact.

Windows

On Windows 11 with Developer Mode, use either mklink /D (directory symbolic link) or mklink /J (junction). Both are acceptable if each link points directly to the repo source:

cmd.exe /c mklink /D "%USERPROFILE%\.agents\skills\{skill-name}" "<skills-repo>\skills\{skill-name}"
cmd.exe /c mklink /D "%USERPROFILE%\.claude\skills\{skill-name}" "<skills-repo>\skills\{skill-name}"
cmd.exe /c mklink /D "%USERPROFILE%\.codex\skills\{skill-name}" "<skills-repo>\skills\{skill-name}"

:: Junction alternative
cmd.exe /c mklink /J "%USERPROFILE%\.agents\skills\{skill-name}" "<skills-repo>\skills\{skill-name}"
cmd.exe /c mklink /J "%USERPROFILE%\.claude\skills\{skill-name}" "<skills-repo>\skills\{skill-name}"
cmd.exe /c mklink /J "%USERPROFILE%\.codex\skills\{skill-name}" "<skills-repo>\skills\{skill-name}"

Alternatively, in PowerShell with Administrator privileges:

New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.agents\skills\{skill-name}" -Target "<skills-repo>\skills\{skill-name}" -Force
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.claude\skills\{skill-name}" -Target "<skills-repo>\skills\{skill-name}" -Force
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.codex\skills\{skill-name}" -Target "<skills-repo>\skills\{skill-name}" -Force

Note: Despite Developer Mode being enabled, New-Item -ItemType SymbolicLink still requires elevation in some Win 11 builds. mklink /D is preferred when symbolic links are available; mklink /J is an acceptable fallback. If runtime link creation fails, stop and report — do not try to elevate or work around it.

Why three runtime links (not a chain)

• .claude/skills/ is consumed by Claude Code — which reads only its own dir, never .agents/.
• .codex/skills/ is Codex's older user location, still read for backward compatibility ($CODEX_HOME/skills).
• .agents/skills/ is the shared cross-runtime dir — Codex's current user location, and read by Cline, Zed, and Warp. Other tools use dirs of their own (Cursor ~/.cursor/skills, Copilot ~/.copilot/skills), so it is not universal.

Each runtime's directory is read independently. A chain (e.g. .claude/ → .agents/ → repo) would mean a broken .agents/ link silently breaks Claude Code. Three direct links keep every runtime independent and resilient.

Agent-specific skills

If a skill is intentionally Claude-only or Codex-only — because it depends on tools that aren't available in the other runtime — the author MAY skip the runtime links for the unsupported runtimes. In that case the author MUST add a runtime: field to the front-matter listing the supported runtimes. Examples:

runtime: [claude]          # Claude Code only
runtime: [codex]           # Codex only
runtime: [claude, codex]   # both LLM runtimes, skip the shared .agents/ dir

The default (when runtime: is omitted) is all three: [claude, codex, agents]. The runtime: field is documentation today, not enforced — it's how an author signals intent to humans and to future tooling.

4. Commit and push

cd <skills-repo>
git add skills/{skill-name}
git commit -m "skill: add {skill-name}"
git push

5. Confirm

Tell the user:

• Skill created: /{skill-name}
• Format: single-doc or dual-doc (and if dual-doc: protocol.yon companion present)
• Linked into all three runtimes: ~/.claude/skills/, ~/.codex/skills/, ~/.agents/skills/ (or only the subset listed in runtime: if the skill is runtime-specific)
• Pushed to GitHub
• Pickup behavior per runtime:
  • Claude Code usually picks up new skills immediately; if the new skill doesn't show up in your agent's skill list, restart the agent or trigger a skill reload (e.g. Claude Code: restart; Codex: next session start).
  • Codex picks up the skill on next session start.
  • .agents/ pickup depends on the consumer of that mirror.

6. Migrating an existing single-doc skill to dual-doc

When promoting an existing skill from single-doc markdown to dual-doc YON:

1. Snapshot. Create archive/ subfolder and copy current SKILL.md to archive/SKILL-YYYY-MM-DD.md (today's date). The archive/ subfolder is invisible to the skill loader and travels through directory junctions like everything else. Multiple migrations get multiple stamped files.
2. Draft protocol.yon following section 2b. Use yon-write with the snapshot as input. Hand-edit for fidelity.
3. Validate protocol.yon with the public parser before committing: npx @younndai/yon-parser validate protocol.yon --profile exec.
4. Rewrite SKILL.md to the dual-doc shape (section 2b): frontmatter unchanged, one-paragraph overview, self-sufficient summary body, pointer block to protocol.yon. Target: 30–50% of original line count.
5. Smoke test (Claude Code). Trigger via natural-language phrase + slash command. Confirm routing unchanged. Run on a typical task; confirm the model reads protocol.yon (visible in tool-call traces).
6. Smoke test (Codex), if cross-runtime. Trigger from a Codex session. Codex will likely ignore protocol.yon — the SKILL.md must carry the load on its own.
7. Atomic commit per skill. Message format: skill: dual-doc migration for {name}. Push immediately so the symlinks propagate and you get incremental signal.

7. Renaming an existing skill

Renames touch four surfaces: the folder, the front-matter, the OS-level symlinks, and every cross-reference across other skills + indexes. Missing any one of these leaves the library inconsistent. Follow in order — see references/RENAME-CHECKLIST.md for the 30-second card.

1. Rename the folder — mv skills/<old>/ skills/<new>/ (or PowerShell Rename-Item).
2. Update front-matter + heading — in skills/<new>/SKILL.md, change name: <old> to name: <new> and the # /<old> heading to # /<new>.
3. Update protocol.yon (dual-doc only) — change the @DOC id=<old> to @DOC id=<new> and refresh the @STAMP date.
4. Rebuild the three symlinks. Drop the old ones and create new ones, all three runtimes:
   • Windows: cmd /c rmdir "%USERPROFILE%\.claude\skills\<old>" then cmd /c mklink /D "%USERPROFILE%\.claude\skills\<new>" "<skills-repo>\skills\<new>" — repeat for .codex and .agents. (Run via Bash tool: prefix with MSYS_NO_PATHCONV=1 so paths aren't mangled.)
   • POSIX: rm ~/.claude/skills/<old> && ln -s "$REPO/skills/<new>" ~/.claude/skills/<new> — repeat for .codex and .agents.
5. Sweep cross-references. Run grep -rn "<old>" skills/ README.md CONFORMANCE.md and update every hit. The common surfaces:
   • Other skills' next-skills: front-matter skill: values.
   • Sibling-boundary clauses in other skills' description: fields ("Not for X — use <old>").
   • README.md inventory section.
   • skills-help/SKILL.md menu entries (if the rename crosses families, also re-categorize).
   • Any other skill's prose that names the one you renamed.
6. Run the lint. node tools/lint.mjs — expect clean. If a broken link/reference, next-skills-orphan, or name-mismatch fires, fix and re-run.
7. Atomic commit. Message format: skill: rename <old> → <new>. Push.

7a. Renaming verification (dry-run)

Before relying on the procedure for a real rename, exercise it on a throwaway branch:

1. git checkout -b "tmp/rename-dryrun-$(git rev-parse --short HEAD)".
2. Snapshot symlink state — POSIX: ls -la ~/.claude/skills ~/.codex/skills ~/.agents/skills > "$TMPDIR/symlinks-before.txt". Windows PowerShell: Get-ChildItem ~\.claude\skills, ~\.codex\skills, ~\.agents\skills | Out-File "$env:TEMP\symlinks-before.txt".
3. Round-trip rename reflect → reflect-v2 → reflect, running the lint after each direction. Skip step 7 (no commits / push).
4. Diff fresh symlink listing against the snapshot — must be byte-equal.
5. git diff main — expect empty (round-trip reverts cleanly).
6. git checkout main && git branch -D tmp/rename-dryrun-<sha>.

On dry-run failure — manually restore symlinks per the snapshot, then git checkout main && git branch -D tmp/rename-dryrun-<sha>. The OS-level state must be reconciled before re-attempting; git alone won't fix half-renamed symlinks.

Rules

• NEVER overwrite an existing skill without asking first
• Always confirm the skill name and description with the user before writing files
• kebab-case names only
• Keep SKILL.md under 500 lines (longer skills are good candidates for dual-doc — see section 2b)
• Three parallel direct runtime links, never a chain — into a skills repo you author; installing a pack you do not maintain is a copy, not a link
• For dual-doc skills, the SKILL.md body must remain execution-sufficient on its own — protocol.yon adds precision, never replaces the SKILL.md

Human output. This skill's handler-facing output obeys the human-output contract (human-output/SKILL.md).

Next skills. On completion, run the Next Skills protocol (next-skills/SKILL.md): surface the next-skills recommendations from front-matter for the caller to pick. Offer only — never auto-invoke.

Self-improvement. On completion, run the Self-Improvement Protocol (self-improve/SKILL.md): if this run surfaced a concrete, blocking-or-recurring weakness in this skill, propose a specific fix for the handler to approve. Conservative — silent otherwise. Never auto-apply.