Skip to content
Skills Library
AI & agents · Building & coding

create-skill

/create-skill

Scaffolds, diagnoses, and prunes agent skills. Modes: `scaffold` (default — runs the job once without a skill on a real input, records every correction, then writes a skill made of only those corrections), `diagnose` (retrospective failure analysis that emits a confidence-gated unified diff against any skill declaring a diagnostic surface), `prune` (deletes unused skills and trims or deletes those whose with/without-skill eval shows no lift over a same-length dummy). Triggers on "create a skill", "scaffold a skill", "new SKILL.md", "diagnose this skill", "why did the skill miss this", "prune m

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
23
Scripts
1
HTML comments
2
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

Scripts: scripts/validate-skill.mjs

What it does and when to use it

Scaffolds, diagnoses, and prunes agent skills. Modes: `scaffold` (default — runs the job once without a skill on a real input, records every correction, then writes a skill made of only those corrections), `diagnose` (retrospective failure analysis that emits a confidence-gated unified diff against any skill declaring a diagnostic surface), `prune` (deletes unused skills and trims or deletes those whose with/without-skill eval shows no lift over a same-length dummy). Triggers on "create a skill", "scaffold a skill", "new SKILL.md", "diagnose this skill", "why did the skill miss this", "prune m

Triggers from the description

create a skillscaffold a skillnew SKILL.mddiagnose this skillwhy did the skill miss this

Arguments

/create-skill [scaffold|diagnose|prune] [<skill-name>|<path>...]
Original author description

Scaffolds, diagnoses, and prunes agent skills. Modes: `scaffold` (default — runs the job once without a skill on a real input, records every correction, then writes a skill made of only those corrections), `diagnose` (retrospective failure analysis that emits a confidence-gated unified diff against any skill declaring a diagnostic surface), `prune` (deletes unused skills and trims or deletes those whose with/without-skill eval shows no lift over a same-length dummy). Triggers on "create a skill", "scaffold a skill", "new SKILL.md", "diagnose this skill", "why did the skill miss this", "prune m

How it works

  1. Mode Detection
  2. Scaffold Workflow (default)
  3. Diagnose Workflow
  4. Prune Workflow
  5. Required Reading by Phase
  6. Core Principles
  7. Definition of Done
Original SKILL.md headings · 243 lines, 1,935 words
SKILL.md preview
---
name: create-skill
description: >
  Scaffolds, diagnoses, and prunes agent skills.
  Modes: `scaffold` (default — runs the job once without a skill on a
  real input, records every correction, then writes a skill made of
  only those corrections), `diagnose` (retrospective failure analysis
  that emits a confidence-gated unified diff against any skill declaring
  a diagnostic surface), `prune` (deletes unused skills and trims or
  deletes those whose with/without-skill eval shows no lift over a
  same-length dummy). Triggers on "create a skill", "scaffold a skill",
  "new SKILL.md", "diagnose this skill", "why did the skill miss this",
  "prune my skills", "clean up my skills", "/create-skill".
disable-model-invocation: true
argument-hint: '[scaffold|diagnose|prune] [<skill-name>|<path>...]'
license: MIT
metadata:
  author: mthines
  version: '2.0.0'
  workflow_type: scaffolder-and-diagnoser
  tags:
    - skill-authoring
    - scaffolding
    - meta
    - diagnose
    - self-improvement
    - lift-check
    - run-first
---

# Create Skill

Write a skill from what a real run of the job got wrong, harden an existing skill after it failed, and delete skills that do not earn their context.
Detailed rules live in `rules/*.md` and templates in `templates/*.md`; load them on demand.

---

## Mode Detection

Parse `$ARGUMENTS` (first token) and detect the mode:

| Mode       | Default | Trigger                                                                  |
| ---------- | ------- | ------------------------------------------------------------------------ |
| `scaffold` | **yes** | Default. "create", "scaffold", "new skill", or no mode argument.         |
| `diagnose` |         | "diagnose", "why did <skill> miss this", or `$0 == "diagnose"`.          |
| `prune`    |         | "prune", "clean up my skills", "which skills are useless", or `$0 == "prune"`. |

If the user typed a path or skill name as `$ARGUMENTS`, treat it as the
target for `diagnose`/`prune`; for `scaffold` it is the proposed
skill name.

State the detected mode and target in one line before continuing. Example:

```text
Mode: scaffold
Target: skills/<category>/<proposed-name>/
```

---

## Scaffold Workflow (default)

Run the job first, write the skill second.
Phases 0–2 do the job with no skill loaded and record every correction it needed; Phases 3–5 write a skill made of those corrections only and prove it closes them.
The full procedure for Phases 0–2 is [`rules/run-first.md`](./rules/run-first.md); why it beats designing the skill up front is [`references/run-first-rationale.md`](./references/run-first-rationale.md).

**No one to ask.** When the user said not to ask questions, or the session is headless, answer each question below yourself from the request and the run, record the answers in the ledger, and continue.

| Phase | Name    | Gate |
| ----- | ------- | ---- |
| 0     | Brief   | Task, real input, guardrails, and a definition of done that can fail |
| 1     | Run     | The job ran on the real input with no skill and passes its definition of done, and every correction is in the ledger — or the run was waived with a recorded reason |
| 2     | Distill | Every ledger row routed; no-skill exit evaluated; name, description, and invocation settled |
| 3     | Write   | Every skill line traces to a ledger row, a guardrail, or the definition of done |
| 4     | Check   | `scripts/validate-skill.mjs` is PASS; wiring done when inside this repo |
| 5     | Verify  | A fresh run with the skill needed none of the ledger's corrections |

### Phase 0 — Brief

Ask the user, in **one** message, for the four brief fields in `rules/run-first.md` § Step 1: task, a real input, guardrails, and a definition of done.
Do not ask for the skill's name, description, or structure yet.

### Phase 1 — Run

Do the job on the real input, in this session, without the skill, following `rules/run-first.md` § Step 2.
Show the output with its definition-of-done result, take the user's corrections, and repeat until they accept it.
Write each correction to the ledger at `.agent/{branch}/skill-run-<task-slug>.md` as it happens.

```text
✗ Wrong — writing the skill from the user's description of the process
User: create a skill for our weekly client report
Agent: Here is skills/…/weekly-client-report/SKILL.md with 9 steps …

✓ Right — doing the report first
User: create a skill for our weekly client report
Agent: Give me this week's export, what I must not touch, and what "done" means.
       I'll produce the report without a skill, you correct me, and the skill
       will be made of those corrections.
```

### Phase 2 — Distill

1. Route every ledger row (`rules/run-first.md` § Step 4) and apply the no-skill exit (§ Step 5).
   On a zero count, stop here and say no skill is needed — unless the run was waived, which skips the exit.
2. Propose these three, derived from the run, and confirm them with the user in **one** message:
   1. **Name** — kebab-case, ≤ 64 chars, no `anthropic` or `claude`.
   2. **Description** — third person, what it does and when to use it, with 3–8 trigger phrases including how the user asked in Phase 0 ([`rules/description-writing.md`](./rules/description-writing.md)).
   3. **Invocation** — model-invokable (default) or slash-only (`disable-model-invocation: true`) ([`rules/invocation-control.md`](./rules/invocation-control.md)).
3. Add `argument-hint` only when the run took an argument, `allowed-tools` only when the run needed repeated permission prompts, and the `portable` profile only when the user asks for it ([`rules/frontmatter.md`](./rules/frontmatter.md) § Portability profile).

### Phase 3 — Write

Write the skill from the ledger, not from the process:

| Ledger route | Becomes |
| --- | --- |
| `skill gotcha` | one line or one short block under `## Gotchas` |
| `check script` | `scripts/check-<name>.mjs` (zero dependencies, `${CLAUDE_SKILL_DIR}`-anchored; [`rules/scripts-and-assets.md`](./rules/scripts-and-assets.md)) plus one line to run it before reporting done |
| `subagent step` | one instruction to run that step in a sub-agent and return only its result |
| `hook`, `workspace fact` | its routed destination, never the skill |

Never add a step the agent did correctly in the run, a heading with no ledger row under it, or frontmatter the run did not need.
Start from [`templates/SKILL.minimal.md`](./templates/SKILL.minimal.md); split into `rules/` only when the body passes 200 lines ([`rules/structure-decision.md`](./rules/structure-decision.md)).

```markdown
<!-- ✗ Wrong — a manual for the process, plus ceremony -->
## Overview / ## Steps (1. Read the export. 2. Compute totals. …) / ## Best practices / ## Troubleshooting

<!-- ✓ Right — only what the run got wrong, and how done is checked -->
## Gotchas
- Refund rows carry positive amounts; subtract them.
- JPY has no minor unit; never divide its amount by 100.

Before reporting done, run `node ${CLAUDE_SKILL_DIR}/scripts/check-report.mjs report.md` and show its last line.
```

### Phase 4 — Check

Run `node ${CLAUDE_SKILL_DIR}/scripts/validate-skill.mjs <dir> [--portable]`, fix every `FAIL`, and report its `Self-check:` line verbatim.

```text
FAIL FM05 SKILL.md:3 — description must be non-empty and <= 1024 chars, got 1180
Self-check: FAIL — 1 failing
```

Inside this repo (it has `scripts/sync-symlinks.sh`), place the skill at `skills/<category>/<name>/`, run `bash scripts/sync-symlinks.sh`, and add the inventory hook to `CLAUDE.md` and the row to `README.md` ([`rules/repository-conventions.md`](./rules/repository-conventions.md)).
Anywhere else, skip wiring and state where the skill was written.

### Phase 5 — Verify

Re-run the Phase 0 brief in a sub-agent with the skill installed, on a fresh input (another real input, or the same one with the previous output deleted), and check that no ledger correction recurs.
A recurring correction means the line meant to prevent it is wrong or missing: fix that line and re-run once.
Report `Verify: PASS — fresh run, 0 of <n> corrections recurred`.

The lift check ([`rules/lift-check.md`](./rules/lift-check.md)) is not part of a scaffold: run it when the user asks, or before the skill is shipped to other people.

---

## Diagnose Workflow

For `diagnose` mode, do not scaffold or review.
Analyse a session in which **another skill** executed and produced an
unsatisfactory result, identify which of that skill's gates should have
caught it, and emit a confidence-gated unified diff that hardens the target
skill against the same failure class.

The full procedure (seven steps, including the mandatory
`confidence(analysis) ≥ 90 %` gate before `--apply`), the report format,
and the hard rules live in [`rules/diagnose-mode.md`](./rules/diagnose-mode.md).

**Invocation:**

```text
/create-skill diagnose <target-skill-name> [--symptom "..."] [--scope <phase|companion>] [--apply] [--pr] [--no-write]
```

**The target declares its own diagnostic surface** in
`skills/<target>/rules/diagnostic-surface.md` (skills) or
`agents/<target>/rules/diagnostic-surface.md` (agents) — phase model,
failure taxonomy, existing-guards table, source root, hard invariants.
Step 1 of Diagnose Mode disambiguates by checking both locations.
The contract spec is in [`rules/diagnostic-surface.md`](./rules/diagnostic-surface.md);
the scaffolding template a target drops into its own `rules/` is
[`templates/diagnostic-surface.template.md`](./templates/diagnostic-surface.template.md).

If the target has not declared a surface, Diagnose Mode falls back to
inferring phases from the target body's H2 sections (`SKILL.md` for skills,
`agents/<name>.md` for agents) and warns the user once that fidelity is reduced.

Diagnose Mode never modifies user product code.
It only proposes changes to the target's own source.

**Self-improving skills.** An orchestrator skill can close the loop further with
a two-tier self-improvement loop: a fast episodic-lessons tier
(LoreKit `memory.*` tools) feeding the slow `diagnose` tier via a recurrence gate.
The reusable recipe — including when NOT to add one — is in
[`rules/self-improvement-loop-pattern.md`](./rules/self-improvement-loop-pattern.md).
When a target declares a `## Lessons scope`, Diagnose Mode reads it as evidence
(Step 2).

---

## Prune Workflow

For `prune` mode, clean up an installed skill set; follow [`rules/prune-mode.md`](./rules/prune-mode.md):

1. Inventory each skill's context cost and usage with `claude -p "/skill-doctor"`.
2. Delete candidates: skills never invoked.
3. Lift-check every used skill ([`rules/lift-check.md`](./rules/lift-check.md)), highest cost first; no lift over the dummy makes it a trim or delete candidate.
4. Find and migrate callers, then get the user's explicit yes per skill before deleting or trimming anything.

Why: [`references/lift-and-prune-rationale.md`](./references/lift-and-prune-rationale.md).

---

## Required Reading by Phase

Load these on demand — do not preload them all.

| Phase    | Files |
| -------- | ----- |
| 0–2      | `rules/run-first.md`, `rules/description-writing.md`, `rules/invocation-control.md` |
| 3        | `rules/scripts-and-assets.md`, `rules/structure-decision.md` (only past 200 lines), `templates/SKILL.minimal.md` |
| 4        | `rules/repository-conventions.md` (inside this repo only) |
| prune    | `rules/prune-mode.md`, `rules/lift-check.md` |
| diagnose | `rules/diagnose-mode.md`, `rules/diagnostic-surface.md`, plus the target's `rules/diagnostic-surface.md` |
| loop     | `rules/self-improvement-loop-pattern.md` (adding a self-improvement loop to an orchestrator skill) |
| lens     | `rules/review-lens-contract.md` + `templates/lens.md` (making an existing skill lens-eligible for `pr-reviewer`) |

---

## Core Principles

1. **A skill is the list of what the agent got wrong.** Do the job once without it and write only the corrections; a run that needed none means no skill ([`rules/run-first.md`](./rules/run-first.md)).
2. **Every line is a recurring cost.** Write nothing the model already does; a loaded skill stays in context, and compaction re-attaches up to 5,000 tokens of it.
3. **The description is the discovery surface.** Third person, what and when, trigger phrases first.
4. **Guarantees are hooks and scripts, not capitals.** What must never happen becomes a hook; a done condition that can be checked becomes a script the skill runs.

---

## Definition of Done

A **scaffold** run is done when:

- [ ] The job ran once without the skill on a real input (or the waiver is recorded), and the ledger at `.agent/{branch}/skill-run-<task-slug>.md` routes every correction.
- [ ] Every `SKILL.md` line traces to a ledger row, a guardrail, or the definition of done.
- [ ] `validate-skill.mjs` reports `PASS`.
- [ ] Inside this repo: symlinks resolve and the `CLAUDE.md` and `README.md` rows exist.
- [ ] Phase 5 verify passed, or the user waived it.
- [ ] One sentence to the user: where the skill is and how to invoke it.

A **prune** run is done when:

- [ ] Every skill in scope has a cost, a usage class, and (if used) a lift verdict or an `unchecked` mark.
- [ ] No skill was deleted or trimmed without the user's explicit per-skill confirmation.
- [ ] Every deleted skill's callers were repointed or removed in the same change.
- [ ] The report states the context saved per turn.

A **diagnose** run is done when:

- [ ] Target skill name resolved and source root verified writable.
- [ ] Diagnostic surface loaded (or fallback warning printed).
- [ ] Failure classified against the target's taxonomy (or `F-novel` plus a
      proposed new row).
- [ ] Phase-attribution table walks every phase in the target's surface.
- [ ] Exactly one improvement proposal constructed (one diff per report).
- [ ] `confidence(analysis)` score recorded; `--apply` honored only at
      ≥ 90 % (final score, after Step 6.5's two-iteration refinement loop
      if the initial score was below the gate).
- [ ] Report written to `.agent/{branch}/diagnose-{target}.md` (or
      stdout with `--no-write`).
- [ ] If `--apply` ran, user explicitly confirmed before `git apply`.
Files in this package (23)
  • SKILL.md 14 KB
  • references/lift-and-prune-rationale.md 2 KB
  • references/run-first-rationale.md 3 KB
  • rules/description-writing.md 7 KB
  • rules/diagnose-mode.md 28 KB
  • rules/diagnostic-surface.md 10 KB
  • rules/frontmatter.md 11 KB
  • rules/invocation-control.md 9 KB
  • rules/lift-check.md 5 KB
  • rules/prune-mode.md 4 KB
  • rules/repository-conventions.md 7 KB
  • rules/review-lens-contract.md 7 KB
  • rules/run-first.md 7 KB
  • rules/scripts-and-assets.md 4 KB
  • rules/self-improvement-loop-pattern.md 9 KB
  • rules/structure-decision.md 5 KB
  • scripts/validate-skill.mjs 45 KB
  • templates/SKILL.minimal.md 1 KB
  • templates/SKILL.multi-file.md 3 KB
  • templates/SKILL.portable.md 2 KB
  • templates/diagnostic-surface.template.md 3 KB
  • templates/lens.md 1 KB
  • templates/rule.md 1 KB

Versions

RepositoryScoreLicence
This page · mthines/agent-skills100MIT
mgiovani/cc-arsenal100MIT
zylos-ai/zylos-core100MIT
jongio/skills100MIT
fairladyz625/harness-anything100AGPL-3.0
coco-research/coco100MIT
builderio/agent-native100MIT
BrandeisPatrick/silo-harness100MIT
vanducng/skills100MIT

Database snapshot: 13.11.2026 · package version 8207f6b96b91 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95skill-creator
    Guide for creating NEW skills from scratch. This skill should be used when users want to create a new skill or scaffold a skill directory. Triggers on "create a skill", "new skill", or "scaffold skill". Do NOT use for updating existing skills - use claude-code-expert instead.
  • 100skill-creator
    Create new Agent Skills interactively or from templates. Use when user wants to create, generate, scaffold, or build a new skill, or mentions creating skills, writing skills, skill templates, skill development.
  • 95creating-agent-skills
    Create and refine Claude Code Skills. Use when authoring SKILL.md files, building new skills, or improving existing skill structure and best practices.
  • 90make-skill
    Create, review, or fix Agent Skills for GitHub Copilot. Use when asked to create, scaffold, improve, or repair a SKILL.md and its paired harness evaluation.
  • 100skill-management
    Create, edit, and delete custom managed skills in the user's workspace. Use whenever the user wants to author a new skill from a description, scaffold a SKILL.md, or remove a skill they no longer need.
  • 100skill-writer
    Create and improve agent skills following the Agent Skills specification. Use when asked to create, write, or update skills.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.