Skill Creator

Skill Creator

A skill for designing, writing, testing, and iterating on skills. The job here is craft — a skill is a small piece of evergreen instruction that will run thousands of times across thousands of conversations, so it has to be lean, well-aimed, and not surprising.

This skill is written to be agent-agnostic. It assumes only the minimum that any LLM agent has: the ability to read text, write text, and converse with a user. Everything else (subagents, file system, browser, bundled scripts, CLI tools) is treated as optional capability that may or may not be present. Each stage describes what to do at the methodology level, then notes how to accelerate it if specific capabilities are available.

The mental model in one paragraph

A skill is metadata plus a body. The metadata (name + description) is a router — it decides whether the skill enters context at all. The body is a working agreement with the model that fires once routed. Bundled resources (scripts/, references/, assets/) are deferred load: they cost nothing until the skill explicitly reaches for them. Your job as skill author is to put the minimum into the always-loaded layers and push everything else down. Most bad skills fail because they violate that — they leak operational detail into the body, or stuff trigger logic into prose instead of the description.

---

Capability profile

Before starting, take stock of what your runtime offers. Each stage uses the strongest available capability and falls back gracefully.

| Capability | If present | If absent | |---|---|---| | File system | Save artifacts (SKILL.md, evals, results) to disk | Hold drafts in conversation; ask the user to copy out | | Subagents / parallel tasks | Run with-skill and baseline tests in parallel | Run them in series, one at a time | | Browser / display | Open eval viewer for the user to review | Present test outputs inline in the conversation | | Bundled scripts (Python) | Use them as accelerators where mentioned | Do the equivalent work directly: write small ad-hoc scripts, or do it manually | | claude CLI / programmatic agent invocation | Run automated description-optimization loops | Optimize description by hand using a small set of manual trials | | Packaging tooling (present_files, .skill archive) | Hand the user a single file | Hand the user the directory path; they can zip it themselves |

Skills produced by this process must themselves obey the same rule: a created skill should work in any agent that has at least file-read and text-output. If it depends on a specific tool, the description must say so and the body must degrade gracefully.

---

Stage 1 — Capture intent

Two flavors of intent show up. Identify which one you're in before drafting.

1a. Capturing an existing workflow (most common)

The user already does this thing. They want to teach you to do it the same way. The conversation history (or the file they uploaded) is the source of truth, not your imagination.

Extract from history first: what tools were used, in what order, where the user corrected you, what input/output shapes they accepted without comment, what edge cases triggered manual intervention. Then ask only about the gaps. "You handled malformed CSVs by skipping rows last time — should the skill do that or fail loudly?" is a real question. "What's the input format?" when the input format is right there in the transcript is friction the user will resent.

1b. New skill from scratch

The user has an idea but no worked example. Interview narrowly — five questions:

1. What should this skill enable the agent to do, in one sentence?
2. When should it trigger? List 3-5 phrasings the user would actually type.
3. What does success look like in concrete terms — a file, a message, a code change?
4. What should it refuse to do, and what should the user fall back to?
5. Is this a one-shot, or part of a multi-step process? (Drives Stage 2.)

If the user says "vibe with me" and rejects test cases, don't force it. Subjective skills (writing style, art) genuinely don't benefit from assertion-based evals. Note that decision and move on.

---

Stage 2 — Choose skill topology

Before writing a single line, decide the shape. Three options:

Leaf skill — does one thing, end-to-end, in one body. Most skills should be this. Body is self-contained instruction; references hold dialect-specific or rarely-needed material.

Router / orchestrator — routes to other skills or sub-modules based on state. Use when the workflow has clear phases with different decision logic per phase. Routers stay short — they should not contain the actual work, only the routing rules.

Composite with reference modules — single SKILL.md, but body delegates to references/.md based on a selector. Use when there's one workflow but multiple substitutable backends (cloud providers, SQL dialects, tool versions). The body holds workflow + selector; references hold per-variant bodies.

Choosing wrong is the most expensive mistake in skill design. A monolithic leaf skill that should have been a router becomes a 1500-line wall that triggers everywhere and follows none of its rules.

Heuristic: if the workflow has more than one branch where the next instruction depends on the result of the previous one, you're probably in router territory.

---

Stage 3 — Survey the ecosystem before writing

Skills don't live alone. In any non-trivial setup the user has dozens to hundreds of skills already installed. Before writing a new one, survey:

• Direct duplicates: skills whose descriptions overlap yours by >70%. If found, extend instead of forking.
• Adjacent skills: skills that share concepts. Decide explicit boundaries — your description should later say "NOT for X, use ``".
• Plugin coverage: if an installed plugin (e.g., a marketing or support pack) covers the domain, place the new skill inside that plugin's namespace and naming convention.

How to do this depends on capability:

• If a skill registry is exposed in your context, list it and grep.
• If it isn't, ask the user to paste the names+descriptions of skills they suspect overlap.

Surface the result before drafting: "I see you already have ``. The skill you're describing overlaps with it on ~60% of intents. Options: (a) extend that one, (b) write a narrower companion that delegates to it, (c) write a separate skill with a clear boundary clause. Which?"

This single step prevents most over-triggering pain at registry scale.

---

Stage 4 — Write the description (first, as a first-class artifact)

The description is the only thing the model sees when deciding whether to consult the skill. It's not a marketing blurb — it's a routing rule.

A good description has four parts:

1. What it does — one clean sentence, action-first.
2. Concrete trigger surface — phrases or task shapes that should fire it. Aim for variety: formal/casual, explicit/implicit.
3. Boundary clauses — what it is NOT for, and which adjacent skill to use instead.
4. Optional context cues — file types, situations, domains.

Example for a hypothetical incident-postmortem skill:

> Generate post-incident reviews from incident timelines, Slack threads, and PagerDuty exports. Use when the user says "write a postmortem", "blameless review", "RCA writeup", "what happened with the outage", uploads incident-related transcripts, or asks for a 5-whys / contributing-factors document. NOT for forward-looking risk assessment (use risk-assessment) or for customer-facing status updates (use response-drafting).

The pushy-vs-precise trade-off

A description tuned for high recall ("use this whenever the user mentions X, even if they don't explicitly ask") catches more cases but also poaches from neighbors. A description tuned for high precision ("use this only when X and Y") under-fires.

Default position: be moderately pushy on intent variety, but precise on boundary clauses. Recall comes from listing many phrasings of the same intent. Precision comes from explicit "NOT for" carve-outs. If the registry is dense, lean precise. If sparse, lean pushy.

Why this comes before the body

The description determines whether the body ever runs. Writing the body first and the description retroactively almost always produces a description that under-describes the actual capability — by the time you write it, you've forgotten the half of cases the body handles implicitly.

---

Stage 5 — Write the body

Anatomy

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown body
└── (optional)
    ├── scripts/    — deterministic / repetitive code
    ├── references/ — docs loaded on demand
    └── assets/     — templates, fonts, images used in output

scripts/ and references/ are optional and capability-dependent. A skill that bundles scripts must still be usable by an agent that can't execute them — the body should describe what the script does in enough detail that the agent can do it manually.

Progressive disclosure

Three loading layers:

1. Metadata — always in context, ~100 words.
2. SKILL.md body — in context when the skill triggers. Target ≤400 lines, hard ceiling ~500.
3. Bundled resources — only loaded when the body explicitly reaches for them.

Enforcement rule: if the body crosses 400 lines, stop and ask whether the next chunk belongs in references/. Operational detail (CLI commands, JSON schemas, viewer mechanics, troubleshooting) does not need to be in the body — it needs to be reachable from it.

For multi-variant skills, use composite topology:

cloud-deploy/
├── SKILL.md          — workflow + selector
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

The body says "if AWS, read references/aws.md". The model loads only what it needs.

Writing patterns

Imperative form. "Read the file, extract the first column" beats "you should read the file and then you can extract".

Explain why, not just what. Today's models have good theory of mind. A rule with a reason ("we strip trailing whitespace because downstream parsers treat tabs as field separators") sticks; a bare rule gets ignored under pressure.

Use ALWAYS / NEVER sparingly and with reason. Caps-lock is a signal that the author couldn't articulate why. If you find yourself reaching for it, try once to write the reason instead. Reserve absolutes for things that are genuinely categorical (security, data integrity, irreversible actions).

Show, don't enumerate. Two worked examples of input → output beats a 12-bullet specification of the format.

Prefer flat structure. Deep nested headings signal the body is doing too much. Flatten or extract.

Capability awareness. If the body needs a tool that may be absent, say so explicitly: "If `` is available, use it. Otherwise, do this equivalent manually." Do not write instructions that silently break in restricted environments.

What goes where

| In body | In references/ | In scripts/ | |---|---|---| | Workflow steps | Domain-specific cheat sheets | Repeatable transformations | | Decision rules | JSON schemas, API specs | File generation (docx, pptx, pdf) | | Anti-patterns / pitfalls | Long lookup tables | Validation / parsing helpers | | When to read which reference | Edge-case troubleshooting | Bulk operations |

If the model would write the same helper script across three different invocations, that script belongs in scripts/ — and the body must still describe what it does well enough to be reproducible by an agent that can't run Python.

---

Stage 6 — Anti-patterns (and how to diagnose them)

Read each draft against this list before showing it to the user.

1. Monolith. SKILL.md > 500 lines doing four loosely related things. Diagnostic: you can't summarize the skill in one sentence. Fix: split into a router + leaves, or extract domains to references/.

2. Over-MUSTed. Body is a wall of ALWAYS / NEVER / MUST / CRITICAL with no rationale. Diagnostic: count caps-lock absolutes. If >5 in 100 lines, you're overconstraining. Fix: for each absolute, write the underlying reason. Many will dissolve into "prefer X because Y".

3. Overfit-to-tests. Skill works perfectly on the 3 test prompts and degrades elsewhere. Diagnostic: skill mentions specific filenames, column names, or user phrasings from the test set. Fix: generalize. Replace concrete references with patterns; add at least one test case from a different domain.

4. Leaky description. Description is short and vague; body has all the trigger logic in prose. Diagnostic: the body contains phrases like "use this skill when…" or "this skill should fire if…". Fix: move that content up into the description. The body should assume routing already happened.

5. Cargo-cult inheritance. Skill copies structure from another skill (sections, naming, scripts) without need. Diagnostic: sections that don't change behavior if you delete them. Fix: delete them.

6. Surprise. Skill does something the description doesn't promise. Diagnostic: a user reading only the description would be surprised by a side effect. Fix: either remove the side effect, or surface it in the description.

7. Hidden capability assumption. Skill silently assumes subagents, a browser, a CLI, or specific scripts. Diagnostic: the skill stops working in a stripped-down agent without an obvious reason. Fix: declare assumptions in the description; degrade gracefully in the body.

---

Stage 7 — Test

Two modes. Pick based on user appetite and available capability.

Vibe mode

User says "just make it, I'll try it". You write the skill, you stop. Optional: walk through one realistic test prompt mentally or out loud and show the output inline. No benchmarks, no viewer.

This is the right default for subjective or low-stakes skills. Don't force a pipeline on a writing-style skill.

Full mode (methodology)

Three to five realistic test prompts. For each prompt, produce two outputs:

• with-skill: the skill is loaded and the prompt is run.
• baseline: for new skills, run with no skill at all; for skills you're improving, run the previous version.

Compare the pairs. The comparison can be qualitative (read both, judge) or quantitative (assertions per test case, computed pass rate, time, tokens).

How to actually run the pairs depends on capability

• If subagents are available: spawn all with-skill and all baseline runs in the same turn so they finish together. Save outputs to a workspace directory organized by iteration and test ID.
• If subagents are not available: run sequentially, one prompt at a time, in the same conversation. You'll be running the skill yourself rather than handing it to an isolated agent — note that this is a weaker test (you have full context the skill is supposed to convey on its own), but it still catches the obvious failures.

How to present results for human review

• If a browser and a viewer tool are available: open the viewer with both qualitative outputs and the benchmark, ask the user to walk through and leave feedback per test case.
• If they aren't: present each test case inline in the conversation — prompt, output, and a one-line diff vs baseline. Ask the user "anything you'd change?" after each.

Two things that should not be skipped regardless of mode

1. Pair the runs. A with-skill output without a baseline output tells you nothing about whether the skill helped.
2. Get raw outputs in front of the human before forming your own opinion. Your judgment is contaminated by having written the skill. Theirs isn't.

If the runtime ships bundled scripts to accelerate this (an aggregator, a viewer generator, a grader subagent prompt), use them — they exist precisely to remove busywork. If it doesn't, the methodology above is the same; you just do the busyw

…

Source & license

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

• Author: dzhokhov
• Source: dzhokhov/markdown-agent-vault-ru
• License: MIT

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