creating-skills · diff
v0.1.0 to v0.2.0
81 added, 32 removed. Audit A to A.
---
name: creating-skills
- description: Generates new, spec-conformant agent skills on request, applying the Agent Skills open standard and the 19 skill best-practices through a scaffold-fill-validate-fix loop. Use when the user wants to create, author, scaffold, or write a new skill ("make a skill", "new skill", "create a skill", "написать скилл", "сделать скилл"), or when an existing skill folder must be checked against the standard. Works on any agent that reads the open-standard SKILL.md format.
+ description: Use when the user wants to create, author, scaffold, write, or improve an agent skill ("make a skill", "new skill", "create a skill", "improve this skill", "написать скилл", "сделать скилл", "улучшить скилл"), or when an existing skill folder must be checked against the standard. Generates spec-conformant skills by grounding in real expertise, then a scaffold → fill → validate → eval → refine loop, applying the Agent Skills open standard and the agentskills.io skill-creation best practices. Works on any agent that reads the open-standard SKILL.md format.
license: MIT
metadata:
- version: "0.1.0"
+ version: "0.2.0"
---
# creating-skills
- Create new skills that conform to the Agent Skills open standard and follow the 19
- best-practices. The method is a feedback loop: scaffold a folder, fill it in from
- templates, run the validator, and fix findings until it reports `PASS`.
+ Create skills that conform to the [Agent Skills open standard](https://agentskills.io/specification)
+ and follow the agentskills.io skill-creation best practices. The method is a
+ feedback loop: ground the skill in real expertise, scaffold a folder, fill it in
+ with calibrated instructions, run the validator, evaluate against a baseline,
+ and refine from real execution until it holds up.
The scripts use the Python standard library only — no install, no network.
## Workflow
Copy this checklist and tick each item as you complete it:
```
Skill creation:
- - [ ] Step 1: Intake — settle name, description, and whether scripts are needed
+ - [ ] Step 1: Ground — settle name + description, and gather the real expertise
- [ ] Step 2: Scaffold — run new_skill.py
- - [ ] Step 3: Fill — write SKILL.md and references from the templates
- - [ ] Step 4: Validate — run validate_skill.py
- - [ ] Step 5: Fix — resolve every ERROR, then re-validate until PASS
- - [ ] Step 6: Evals — add at least three eval scenarios
+ - [ ] Step 3: Fill — write calibrated instructions + a Gotchas section
+ - [ ] Step 4: Validate — run validate_skill.py, fix every ERROR, re-run until PASS
+ - [ ] Step 5: Evaluate — evals with a with-skill / without-skill baseline
+ - [ ] Step 6: Refine — tune the description, refine from real execution traces
```
- **Step 1 — Intake.** Ask only what the request leaves open: a name (prefer gerund
- form, e.g. `processing-pdfs`), a one-to-two sentence description covering *what* and
- *when*, and whether the skill needs utility scripts. Keep it short.
+ **Step 1 — Ground.** Two things must be settled before writing anything.
+ - *Identity.* A `name` (prefer gerund form, e.g. `processing-pdfs`) and a
+ description covering **what** and **when**.
+ - *Expertise.* The most common failure is generating a skill from the model's
+ general knowledge alone — the result is vague filler. Ground it in real
+ material: either **extract from a hands-on task** the author just did with the
+ agent (the steps that worked, corrections made, input/output formats,
+ project-specific context) or **synthesize from artifacts** (runbooks, API
+ specs, schemas, past fixes/incidents). If the author has neither, that is the
+ first thing to get. Ask only what the request leaves open; keep it short.
+
+ Also decide **scope** (one coherent unit of work — not so narrow that several
+ skills must co-load, not so broad it won't trigger precisely) and whether the
+ skill needs **utility scripts**. If the agent already does the whole task well
+ unaided, say so — the skill may not be worth building.
+
**Step 2 — Scaffold.** Create the folder with a valid stub:
```bash
python3 scripts/new_skill.py <name> [--desc "..."] [--with-scripts] [--dest DIR]
```
The name is validated up front; an invalid or reserved name exits non-zero.
- **Step 3 — Fill.** Write the real `SKILL.md` and any reference files using
+ **Step 3 — Fill.** Write the real `SKILL.md` and references using
[references/templates.md](references/templates.md). Keep the body small and push
- deep material into `references/`.
+ deep material into `references/`, each with a stated "load this when…" trigger.
+ Three things distinguish a good fill from a mediocre one:
+ - **Spend context on what the agent lacks.** For each line ask "would the agent
+ get this wrong without it?" — if no, cut it. Skip explaining what a PDF or HTTP
+ is. Aim for moderate detail with one working example, not exhaustive coverage.
+ - **Calibrate control to fragility.** Give freedom (and explain *why*) where
+ many approaches work; be prescriptive ("run exactly this, don't add flags")
+ where the operation is fragile. Provide a default, not a menu of equal
+ options. Teach *how to approach* the problem class, not the answer to one
+ instance.
+ - **Write a Gotchas section in `SKILL.md`.** Environment-specific facts that
+ defy assumptions (soft-deletes, ID field renames, a lying `/health` endpoint)
+ are often the highest-value content. Keep them in the body — the agent can't
+ open a reference about a trap it doesn't know exists.
+
+ When the skill bundles scripts, design them for agentic use — load
+ [references/scripts.md](references/scripts.md).
+
**Step 4 — Validate.** Check conformance:
```bash
python3 scripts/validate_skill.py <dir>
```
- It prints one line per finding and a `PASS`/`FAIL` summary. ERROR findings mean the
- skill is non-conformant; WARN findings are advisory.
+ It prints one line per finding plus a `PASS`/`FAIL` summary. Resolve every ERROR
+ and re-run until it passes. WARN findings are advisory. Do not ship on a `FAIL`.
- **Step 5 — Fix.** Resolve every ERROR and re-run the validator until it passes. This
- loop is the point — do not ship on a `FAIL`.
+ **Step 5 — Evaluate.** Add at least three eval scenarios (a positive trigger, an
+ output-conformance check, and a negative near-miss) using the templates in
+ [references/templates.md](references/templates.md). Evals are most useful built
+ *before* extensive docs: run the task without the skill first to find the gaps.
+ For output quality, run each case **with the skill and without it** — the
+ baseline is what tells you the skill added value. When you want the full method
+ (assertions, evidence-based grading, iteration), load
+ [references/evaluating.md](references/evaluating.md).
- **Step 6 — Evals.** Add at least three eval scenarios (positive trigger, output
- conformance, negative near-miss). See the eval template in
- [references/templates.md](references/templates.md).
+ **Step 6 — Refine.** The description carries the entire triggering burden; tune
+ it with should-trigger / should-not-trigger queries — load
+ [references/descriptions.md](references/descriptions.md). Then refine the skill
+ from **real execution traces**, not just final outputs: wasted steps usually
+ mean instructions are too vague, don't apply, or offer too many options. Every
+ time you have to correct the agent, add the correction to Gotchas.
## Gotchas
- - The `name` must equal the folder name, be lowercase `[a-z0-9-]`, and must not
- contain the reserved words `anthropic` or `claude`.
- - The `description` cap is 1024 characters and applies to that field alone; write it
- in the third person.
- - The `SKILL.md` body budget is under 500 lines and under ~5000 tokens (the token
- count is an approximation). Split content into references before it grows past that.
+ - The `name` must equal the folder name, be lowercase `[a-z0-9-]` (no
+ leading/trailing hyphen, no `--`), and must not contain the reserved words
+ `anthropic` or `claude`.
+ - The `description` cap is 1024 characters and applies to that field alone.
+ Prefer imperative "Use when…" phrasing addressed to the agent; describe the
+ *user's* intent in the third person; never "I can help you…".
+ - The `SKILL.md` body budget is under 500 lines and under ~5000 tokens (the
+ token count is an approximation). Split into references before it grows past.
- Keep references one level deep; a reference file over 100 lines needs a
`## Contents` table of contents.
## References
- - [references/best-practices.md](references/best-practices.md) — the 19 practices in
- full; load it when deciding how to structure a skill or what a rule means.
+ - [references/best-practices.md](references/best-practices.md) — the full set of
+ practices; load it when deciding how to structure a skill or what a rule means.
+ - [references/descriptions.md](references/descriptions.md) — the trigger-eval
+ method for tuning a description; load it in Step 6.
+ - [references/evaluating.md](references/evaluating.md) — baseline, assertions,
+ and grading for output quality; load it in Step 5 for more than a smoke test.
+ - [references/scripts.md](references/scripts.md) — designing bundled scripts for
+ agentic use; load it in Step 3 when the skill ships scripts.
- [references/checklist.md](references/checklist.md) — the pre-ship checklist of
judgment-only items; run through it before shipping.
- - [references/templates.md](references/templates.md) — SKILL.md and eval skeletons;
- load it during Step 3.
+ - [references/templates.md](references/templates.md) — SKILL.md and eval
+ skeletons; load it during Step 3.