skill-craft
A craft checklist for agent skills. Use when the user asks to write, improve, review, test or tighten a skill, a SKILL.md, an agent definition or a reusable brief, or asks why an agent skips, misreads or never triggers a skill. Not for the subject matter of a skill, only how it is written.
- License 许可
- MIT
- 所属仓库
- justnnc/skills
- 最近更新
- 2026-10-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- skill-craft
- license
- MIT
- description
- A craft checklist for agent skills. Use when the user asks to write, improve, review, test or tighten a skill, a SKILL.md, an agent definition or a reusable brief, or asks why an agent skips, misreads or never triggers a skill. Not for the subject matter of a skill, only how it is written.
02 资源文件 4
- 参考文档SHARING.md1.3 KB
- 参考文档SOURCES.md525 B
- 参考文档TESTING.md650 B
- 参考文档WEAKNESSES.md1.1 KB
03 SKILL.md 正文
Skill craft
An agent reads a skill once, mid-task, under pressure to finish: it skims, guesses at gaps, and narrates progress unless told what progress looks like. A review of a skill ends in the report shape under "Reviewing a skill". A project's own rules for skills win over this one.
Before writing: should this be a skill, and what fails without it?
- Not everything belongs in a skill. A skill loads only when the agent chooses to, and agents often do not. Knowledge every task needs belongs in always-loaded instructions (AGENTS.md, CLAUDE.md); a rule a script can check belongs in a validator or hook. Skills suit workflows with a clear trigger, often one the user starts by name.
- Baseline first. Run the task without the skill in a fresh context, write down how the agent fails, and write only enough to fix that. Without an agent to run, list failures you have seen and mark the skill untested.
Done when the observed failures are written down, or none were found and nothing is written.
The techniques
Most valuable first. A new skill should meet every item that applies.
- Observable completion gates. Every phase ends on something checkable, not a feeling: "a command that reproduces the fault exists and has been run", "every requested decision has an answer". State the gate as a rule the agent can test ("no reproduction, no next phase"), and say what to do when caught skipping it.
- An opening contract. The first lines say what the skill produces, what it does not, and where its responsibility ends. A boundary the agent can feel ("produce decisions, not deliverables"; "one ticket per session") stops it sliding into the adjacent job. The pull to do more is a signal to hand off, and the skill should say so.
- Ask only what the person can answer. Point questions at what the user actually knows (who it is for, what they need back, which option they prefer), never at what the agent should find out itself. Bound the interview: how many questions per round, and when enough is known to stop. Recommend an option rather than asking open-ended.
- The description routes; it never summarises the steps. The frontmatter description holds a short noun phrase for what the skill is, then "Use when ..." with the user's own words, symptoms, error messages and synonyms, then "Not for ..." to keep it off neighbouring tasks. Write it in the third person. Never list the procedure there: an agent that reads the steps in the description may follow that summary and skip the body. Until a skill triggers, most runtimes load only its name and description, so the description alone decides whether the body is ever read. Check the runtime's field limits (one common limit: a name of at most 64 lowercase letters, digits and hyphens, a description of at most 1,024 characters).
- Make uncertainty a place, not a guess. Give the agent somewhere to put what it does not know: an open-questions section, a "to verify" marker, a "not yet specified" area, a stated assumption it proceeds on. Distinguish a sharp question that is merely unanswered from one that cannot yet be phrased; only the first becomes a task.
- Evidence the agent did not produce. Tie each claim to a primary source, a command's output, or an expected value derived independently of the work being checked. Mark what was read against what was inferred. Say what to do when a source is missing or two sources conflict, since that is where an agent invents.
- Progressive disclosure, one level deep. Inline what every path through the skill needs; move what only some paths need into a file beside it, linked at the point of the branch ("for a UI prototype, read UI.md"). Link every such file from SKILL.md itself, never from another linked file, since an agent may only preview a nested file. Give any file over about 100 lines a short contents list at the top.
- Concrete output shapes. A template with placeholders, one worked example, or a checklist the agent copies and ticks off beats an adjective like "thorough" or "clear". A required element gets a required slot in the template. Keep templates beside the skill and tell the agent to keep their structure.
- Match the form of the instruction to the failure.
- A rule the agent skips under pressure: a short prohibition, plus a list of the excuses it uses and the answer to each, a list of the thoughts that come before breaking it, and the line that breaking the letter of the rule breaks its spirit.
- Output in the wrong shape: a positive recipe for the right shape. Prohibitions here tend to make the shape worse.
- A missing element: a required slot in the template.
- Behaviour that depends on a situation: a rule keyed to a condition the agent can observe. Give the common wrong move a name and its symptom, then the exact move to make instead; a bare "don't" leaves a gap the agent fills with something else.
- Explicit handoffs. Name the next skill or artifact and what it is for, and say when it is required rather than optional. Point at existing material instead of copying it, so there is one version of each rule. Order matters: "explore the project, then use the skill" keeps project context that "you must use the skill" can lose.
Also worth doing
- Scripts for steps that must not vary; say whether to run or read each, call it through its interpreter, and have it print errors the agent can act on.
- Cost and time stated before any expensive step, with an expected finish.
- One idea per bullet and per question, one word per concept. A compound item gets half followed.
- No dated instructions ("the new API"); they rot.
- Link, do not force-load: no
@fileimports that load a file on every use. - A length budget. About 800 words for a single-purpose skill, 1,200 for a multi-phase gated workflow, and under 500 lines at most. Move branch-only detail into files beside SKILL.md rather than cutting gates. (Measured 2026-10-20: three well-known public collections had medians of about 550, 1,050 and 1,250 words; the common 500-word advice's own source runs about 3,800.)
Testing a skill
Once a draft exists, read TESTING.md.
Preparing a skill to share
Before publishing, go down SHARING.md.
Done when a search of the folder for paths, names and model names finds nothing, and the frontmatter parses.
Reviewing a skill
Read it once as the agent would, then go down the techniques, the list above and WEAKNESSES.md. Report in this shape, gaps worst first:
Verdict: <ready | small fixes | needs work>
1. "<quoted line>"
Agent would likely: <what it does>
Replace with: <text in the skill's voice>
Before reporting, reread the skill against each gap: drop any the skill already handles, such as a fallback for the case or a rule elsewhere in the file.
Done when every slot is filled, an empty one (including a review with no gaps) written as "none", and each gap survived that reread.
Sources: SOURCES.md (not needed to apply the skill).
04 同仓库更多 Skills
codex-worker
The OpenAI Codex CLI as a worker under Claude. Use when the user names Codex ("have Codex review this", "ask Codex", "run this on Codex", "hand this to Codex"), wants work done on Codex's quota instead of Claude tokens, or wants a review from another model family. Not for tasks that need this conversation's context, the user's running application, or tools only Claude has.
claude-worker
A headless Claude Code run started in another repository, so the work loads that repository's own instructions instead of the current session's. Use when work belongs to a different repository than the one this session is in ("do this in the other repo", "work on the docs repo from here"), when a subagent would carry the wrong project's rules, or when a run needs its own tool set or settings. Not for work in the current repository (use an ordinary subagent), anything that needs a conversation mid-run, or tasks that need this session's context.
spec-audit
A read-only audit of a project's specs against the work that just landed. Use when a batch, feature or set of changes has been merged or is about to be pushed, when the user asks whether a spec is up to date, accurate or drifted from the code, or before a design discussion leans on a spec's text. Not for writing a new spec or design document, reviewing a design document, reviewing code for bugs, or planning work that is not built yet.
prove-by-running
Execution proof that a script or tool works. Use when about to trust a new or changed script, hook, migration or release tool, and always for anything that rewrites git history, publishes or pushes, deletes, or transforms data; also when the user asks "does this actually work", "test this script", "prove it" or "try it on a copy first". Not for reviewing code by reading it, for writing unit tests of a library, or for fixing the faults found.
parallel-refactor
A fan-out of one large mechanical code change across parallel subagents. Use when a refactor, rename, migration or API move touches hundreds of call sites across many files, when the user asks to split a change per file or component or hand it to several agents at once, or asks how big a change is and whether it is mechanical. Not for edits inside one file, a redesign whose target shape is not yet decided, or a change small enough to make serially.
how-it-works
A cited, read-only explanation of how a mechanism in a codebase works. Use when the user asks "how does X work in this code", "where is Y computed", "walk me through Z", or wants a reference implementation read to compare with their own, in a large or unfamiliar codebase. Not for a file or function already known (just read it), bug hunting or debugging, reviewing a diff, or changing code.