# New Skill Creator

> Scaffold a new Agent Skill end-to-end into a skills repo you maintain (folder, SKILL.md, optional protocol.yon for dual-doc skills, tri-runtime links for Claude Code + Codex + the shared .agents/ dir, commit and push). The maintainer's authoring loop — it links your own clone into your runtimes because you write the changes those links carry. Trigger when the user runs /new-skill-creator or says…

- **Type:** Skill
- **Install:** `agentstack add skill-allemaar-open-skills-new-skill-creator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [allemaar](https://agentstack.voostack.com/s/allemaar)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [allemaar](https://github.com/allemaar)
- **Source:** https://github.com/allemaar/open-skills/tree/main/skills/new-skill-creator
- **Website:** https://allemaar.com

## Install

```sh
agentstack add skill-allemaar-open-skills-new-skill-creator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /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"
   ```
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`](../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`](../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
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:

```powershell
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:

```yaml
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](https://github.com/allemaar)
- **Source:** [allemaar/open-skills](https://github.com/allemaar/open-skills)
- **License:** Apache-2.0
- **Homepage:** https://allemaar.com

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-allemaar-open-skills-new-skill-creator
- Seller: https://agentstack.voostack.com/s/allemaar
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.