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](../../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](../../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](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](../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](../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](../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 (\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](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):

```yaml next-skills:

• skill: insight-assess

phrase: "/assess" why: "Evaluate the options you just generated and pick one" ```

1. 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.

1. protocol.yon (dual-doc only) — a closing @STEP rid=step:nsp as the last step. See [next-skills/SKILL.md](../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.

1. protocol.yon (dual-doc only) — a closing @STEP rid=step:sip as the last step, after step:nsp. See [self-improve/SKILL.md](../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](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](../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](../yon-write) to draft the body.
• Reference [yon-read](../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](#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 (``) 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\{skill-name}"
cmd.exe /c mklink /D "%USERPROFILE%\.claude\skills\{skill-name}" "\skills\{skill-name}"
cmd.exe /c mklink /D "%USERPROFILE%\.codex\skills\{skill-name}" "\skills\{skill-name}"

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

Alternatively, in PowerShell with Administrator privileges:

New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.agents\skills\{skill-name}" -Target "\skills\{skill-name}" -Force
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.claude\skills\{skill-name}" -Target "\skills\{skill-name}" -Force
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.codex\skills\{skill-name}" -Target "\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 
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 trigg

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: allemaar
• Source: allemaar/open-skills
• License: Apache-2.0
• Homepage: https://allemaar.com

Install and usage instructions live in the source repository linked above.