writing-skills
Skill1 starsChanged 3 months agoMITView on GitHub
Writes and edits the skills in this library: the SKILL.md format, descriptions, Gotchas, support files, and the proof that a skill changes what an agent does. Use when adding a skill, changing or fixing one, or when a skill is not triggering. Skip using a skill.
191 other projects use a version of this.
Adopted by
Most recently taken up by
- dragoshont/architravetheir own version, first seen Nov 16, 2026
- rundesk-ai/skillstheir own version, first seen Nov 15, 2026
- draekien/skillstheir own version, first seen Nov 15, 2026
- mintunitish/tandemtheir own version, first seen Nov 15, 2026
- alexuraxin/retainertheir own version, first seen Nov 15, 2026
- crbnos/carbontheir own version, first seen Nov 15, 2026
Used with
Projects with it also use chinese-code-review, chinese-commit-conventions and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
Leodorareluctant259Skillchinese-code-review
中文代码审查规范——在保持专业严谨的同时,用符合国内团队文化的方式给出有效反馈
Also in 8 projects that use this
Leodorareluctant259Skillchinese-commit-conventions
中文 Git 提交规范 — 适配国内团队的 commit message 规范和 changelog 自动化
Also in 8 projects that use this
obraSkilldiagnosing-superpowers
Use when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.
Also in 20 projects that use this
kntismSkillcondition-based-waiting
Use when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior - replaces arbitrary timeouts with condition polling to wait for actual state changes, eliminating flaky tests from timing guesses
Also in 3 projects that use this
aaddrickSkillwriting-agents
Use when creating new agents, editing existing agents, or defining specialized subagent roles for the Task tool
Also in 3 projects that use this
frankxaiSkilldefense-in-depth
Use when invalid data causes failures deep in execution, requiring validation at multiple system layers - validates at every layer data passes through to make bugs structurally impossible
Also in 3 projects that use this
- +3 more from Leodorareluctant259
Other versions191 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 191
- obra/superpowers★ 314ksame name
- PostHog/posthog★ 41ksame name
- jnMetaCode/superpowers-zh★ 8.5ksame name
- openai/plugins★ 7.8ksame name
- farm-fe/farm★ 5.6ksame name
- compozy/compozy★ 2.9ksame name
- crbnos/carbon★ 2.8ksame name
- lingyired/status-trio★ 1.8ksame name
- GanyuanRan/Aegis★ 1.4ksame name
- pcvelz/superpowers★ 1.3ksame name
181 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository49 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- working-from-a-ticketSkill
- writing-specsSkill
- clarifying-intentSkill
- dispatching-parallel-agentsSkill
- handoffSkill
- mapping-the-codebaseSkill
- prototypingSkill
- using-git-worktreesSkill
- using-sdlc-skillsSkill
- viewing-artifactsSkill
- yagniSkill
- finishing-a-branchSkill
- release-readinessSkill
- architecture-decisionsSkill
- coding-standardsSkill
- data-modelSkill
- migration-strategySkill
- reviewing-plansSkill
- system-architectureSkill
- ui-ux-designSkill
- writing-plansSkill
- adding-observabilitySkill
- changing-a-live-schemaSkill
- executing-plansSkill
- rollout-controlsSkill
- subagent-driven-developmentSkill
- test-driven-developmentSkill
- complexity-auditSkill
- containing-an-incidentSkill
- debuggingSkill
- deprecating-an-apiSkill
- diagnosing-a-sessionSkill
- eliminating-correctionsSkill
- large-scale-changesSkill
- post-mortemSkill
- refactor-architectureSkill
- brainstormingSkill
- define-goalsSkill
- feasibility-checkSkill
- scopingSkill
- receiving-code-reviewSkill
- requesting-code-reviewSkill
- reviewing-a-prSkill
- security-auditsSkill
- verification-before-completionSkill
- verification-strategySkill
- visual-ui-verificationSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. 0 are common, 8 are distinctive, and 8 are very specific to this project.
0
Common
Most of the 181 edited versions we read keep these.
8
Distinctive
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Write the minimum guidance that changes behavior.
- Distinctive: line 14
Skip: when you're *using* a skill — this is only for authoring.
- Very specific: line 18
Read references/reference.md when unsure how much detail a form needs:
- Distinctive: line 50
Use everyday words wherever they carry the same meaning.
- Very specific: line 73
Put each outcome on its own line as a sentence, "If X, do Y".
- Very specific: line 77
Put the exact text of a question to the user, and the right-versus-wrong shape of an output, in a fenced block.
- Distinctive: line 87
Every retry names its owner, observable progress, finite attempt/resource boundary, and unresolved outcome.
- Very specific: line 92
Cut by judgement, not word caps: Ask of every section: "would the agent get this wrong without this?" If no, cut it.
- Very specific: line 102
Gotchas over rules: Every body carries ## Gotchas: facts the agent gets wrong when untold, each naming the failure it prevents and citing …
- Distinctive: line 127
Start from real expertise: extract the procedure from a task done by hand, or synthesize it from project artifacts — runbooks, review …
- Distinctive: line 129
Before editing a heavily used skill, run it on three real tasks, read the transcripts, and cut or clarify the steps agents wasted first.
- Distinctive: line 131
If the sequence is exact and fragile, write a tested script, not prose.
- Very specific: line 140
Write description as a trigger.
- Very specific: line 142
Write the body: When to use (incl.
- Very specific: line 146
Verify the shape (below). Then prove the behavior at the failure surface: trigger, artifact or side effect, or pressured discipline.
- Distinctive: line 166
Run the skill check, fix what it reports, and run it again.
“Common” is measured: kept by at least 6 in 10 of the 181 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Writing Skills
Write the minimum guidance that changes behavior. Reuse a current body already in context and load supporting material only when needed.
When to use
- Creating or editing a skill under
skills/<phase>/<name>/. - Skip when you're using a skill — this is only for authoring.
Skill types
Read references/reference.md when unsure how much detail a form needs:
- Instruction — a prose procedure. Most skills.
- Template — ships a
{{placeholder}}file the agent copies when it produces that document. - Script — bundles a tested, deterministic script when prose would be error-prone.
- Reference — a doc loaded on demand for lookup; large is fine, it isn't always-loaded.
The format (non-negotiable)
- Frontmatter:
name(kebab-case, matches the directory) anddescription. The Agent Skills specification lists every field. The description says what the skill does and when to use it, in the user's words, with the keywords an agent matches a task on — 1 to 1,024 characters, no word cap, noFires onlist, no summary of the steps. Quote it. A description that still carries aFires onlist predates this rule; rewrite it to this shape when you edit that skill. House limits: at most 500 body lines, under 5000 estimated tokens, and under 19,000 bytes. A harness may cut a body it re-attaches after it summarizes the conversation, and the steps after the cut are lost; 19,000 bytes keeps a body under the smallest cut observed, about 20,000 characters. Most capability skills land near 80–120 lines; a body past ~200 should justify itself. Intent and procedure only; cut marketing ("why this matters"). A worked example in the body earns its place only where it shows a judgment the rules alone do not: three to six lines, generic, with no real project names.
Aim under the target by removing content, never by compressing prose. Dropping articles and verbs until a sentence reads as a noun stack —
Bind exact source/contracts/external inputs and a stable-ID surface— buys line count and costs comprehension. If a body needs 140 clear lines, take them.Use everyday words wherever they carry the same meaning. Keep a term this library defines only where its distinction matters, and then define it in the sentence that uses it;
using-sdlc-skills'control-vocabulary.mdmaps the older terms candidate, gate, receipt, and disposition to their plain forms, so read it when a body you edit uses one. Use "your human partner" sparingly, at most two or three times in a body and often never; prefer a sentence that needs to name no one.- Progressive disclosure, split by what the agent does with the file. A file
it fills in and emits — a document template — goes to
assets/. A file it reads to decide or check — a rubric, a checklist, a reviewer brief, a worked example that rule 2 keeps out of the body, a lookup table — goes toreferences/. Bundled executable code goes toscripts/. A body invokes a bundled script asbash scripts/{{name}}.sh; the bare path appears only in## Available scriptslistings. Keep short questions or response examples inline when their exact shape matters at that step. Read references/template-format.md before writing or editing a file under assets/. - Scope and scale-down up top. State applicability and any skip conditions. A mandatory check, or a skill that is one, may have no skip; define its smallest useful check instead.
- Lint-clean markdown. Fill-in placeholders use
{{double-curly}}—<angle>brackets render as HTML and trip linters. Fence code blocks with a language. Blank lines around lists. Instructions, not facts. An agent can obey an instruction; it cannot obey a fact. Use
## Step N:sections with numbered actions and readable conditions. Put each outcome on its own line as a sentence, "If X, do Y". Mark every handoff with a boldREQUIRED SUB-SKILL:naming the skill to invoke, at the step where the flow reaches it, and say what this skill never does itself.Put the exact text of a question to the user, and the right-versus-wrong shape of an output, in a fenced block; put a command in a
bashblock only where running it is the act. The body says to ask and end the turn;using-sdlc-skillssays how to ask through a choice tool, and the fenced block prints when no choice tool exists or the tool cannot offer every entry. A block asking for typed text says to print it. Any other step that needs a tool or capability says what to do when it is missing and when it is present but refused or limited; an "if missing" line alone leaves a refusal unhandled.Every retry names its owner, observable progress, finite attempt/resource boundary, and unresolved outcome. Before retrying, apply an evidence-supported correction or obtain new discriminating evidence; naming a possible fix is not applying it. Preserve history across revisions and return to a pending caller instead of invoking it recursively.
- Cut by judgement, not word caps. Ask of every section:
"would the agent get this wrong without this?" If no, cut it. If unsure, run
a throwaway probe; read
references/testing.mdbefore writing it up. Never cut a hard stop or a destructive-action guard. Reword a hard stop, a guard, or a rationalization or red-flag row only so that the new words cover everything the old ones did, and nothing more. - Prescribe exactly only where the operation is fragile — git mutations, dispatch, binding evidence to a state, destructive actions. Everywhere else state the goal and its reason in one sentence. Give one default and one escape hatch; keep a menu only for a decision that belongs to the user.
- Gotchas over rules. Every body carries
## Gotchas: facts the agent gets wrong when untold, each naming the failure it prevents and citing only the probe or scenario that reproduces it. Name every support file with its load condition, as inRead references/{{file}} when {{condition}}, and keep the body understandable without it.
Discipline skills are the exception
A few skills exist to hold an agent to a discipline it is tempted to skip under pressure—for example routing, TDD, YAGNI, verifying completion, systematic debugging, and receiving review. For these only:
- Keep the rationalization table (each tempting excuse and its rebuttal) and red-flag list in the body, never a sibling — a tempted agent won't choose to load a sibling file, and the counter must be in context when the temptation hits. Keep only the rows an agent actually falls for.
- They run longer than a capability skill, and that is expected. Each extra line still has to earn its place by passing a pressure test; read
references/testing.mdbefore claiming one passed. - Everything else (capability, template, reference, meta) has no temptation to counter — keep it lean.
containing-an-incidentis this library's exemplar of the form: read its body when writing or editing one. Hard stops, a rationalization table, and## Gotchasall sit in the always-loaded body, inside the limits above.
Step 1: Decide it is a skill
- Identify the recurring task and the observed failure, contract gap, or reusable reference it addresses. If plain prompt text would do, or the task is a one-off, do not write a skill. Passing samples limit a behavior claim; they do not erase reported failures.
- Start from real expertise: extract the procedure from a task done by hand, or synthesize it from project artifacts — runbooks, review comments, fixes. Before editing a heavily used skill, run it on three real tasks, read the transcripts, and cut or clarify the steps agents wasted first.
- If the sequence is exact and fragile, write a tested script, not prose.
- Split activities only when each is independently invokable. Otherwise one cohesive skill.
Step 2: Write it
- Choose the phase folder (
planning…maintenance) orcommon/. Createskills/<phase>/<name>/, copying the fenced block ofassets/skill-template.mdwhen you start the file. - Write
descriptionas a trigger. Test it: does it say when, not how? If it lists steps, rewrite it. - Write the body: When to use (incl. Skip),
## Step N:sections of actions (format rule 6),## Gotchas(format rule 9), and Common mistakes for the mistakes the steps do not already forbid. - Move anything heavy to a sibling (format rule 3).
- Verify the shape (below). Then prove the behavior at the failure surface:
trigger, artifact or side effect, or pressured discipline. Read
references/testing.mdbefore choosing the proof. An agent explaining the rule is not evidence that it follows it.
Available scripts
scripts/check-skill.sh— checks a skill directory with the library's format and policy profile: required fields, names, sizes, selected paths, presentation, bundled script help, and the policy checks (## Gotchas, load conditions, description YAML, frontmatter fields, compatibility length, arrows in prose) — warnings by default, failures with--strict. Its field extraction is not a complete YAML parser and does not validate all optional metadata. It executes the checked skill's scripts with--help; inspect untrusted scripts or isolate them first.
Verify before done
Run the skill check, fix what it reports, and run it again. After three runs that still fail, stop and report the remaining failures as unresolved:
bash scripts/check-skill.sh --strict path/to/skillExit 0 passes this checker's profile; exit 1 lists failures. Review any format or metadata the checker does not cover before claiming standard conformance.
- Markdown lints clean · description states triggers, not a summary.
- A skill library will usually add house rules on top — no external references, no vendor model names, manifest registration. Run its gate too; conforming to the standard is necessary, not sufficient.
- The targeted before/after proof observes behavior, reports every run, and does not turn unchanged skills into a costly coverage exercise.
Gotchas
- An unquoted
descriptioncontaining:, or starting with a YAML indicator such as*,&,[,{, or#, is invalid YAML, and a strict parser drops the skill without an error. Quote it;check-skill.shreportsdescription-yaml. - A support file named without a load condition gets loaded on every run or on
none;
check-skill.shreportsreference-load-condition. - A support file that names another support file gets read partially, so the
third file is missed;
check-skill.shwarnsreference-depth.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

