agentleFS
abhaylaabhayla/claude-best-practices/.claude/skills/writing-skills/SKILL.md

writing-skills

Skill9 starsChanged 7 months agoMITView on GitHub

Author new Claude Code skills or update existing ones. Covers YAML frontmatter, step structure, trigger design, quality validation, testing, hub promotion, and a full template library. Use when creating, updating, or refining skills for the .claude/skills/ directory.

191 other projects use a version of this.

Adopted by

Most recently taken up by

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.
  • Leodorareluctant259Skill

    chinese-code-review

    中文代码审查规范——在保持专业严谨的同时,用符合国内团队文化的方式给出有效反馈

    Also in 8 projects that use this

  • Leodorareluctant259Skill

    chinese-commit-conventions

    中文 Git 提交规范 — 适配国内团队的 commit message 规范和 changelog 自动化

    Also in 8 projects that use this

  • obraSkill

    diagnosing-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

  • kntismSkill

    condition-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

  • aaddrickSkill

    writing-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

  • pedronauckSkill

    lesson-learned

    Analyze recent code changes via git history and extract software engineering lessons. Use when the user asks 'what is the lesson here?', 'what can I learn from this?', 'engineering takeaway', 'what did I just learn?', 'reflect on this code', or wants to extract principles from recent work.

    Also in 3 projects that use this

  • +3 more from Leodorareluctant259

The file

Show its rules and text

We split this skill into the rules it gives an agent

88 rules. 0 are common, 66 are distinctive, and 22 are very specific to this project.

  • 0

    Common

    Most of the 181 edited versions we read keep these.

  • 66

    Distinctive

    This author's own choices. Worth a look.

  • 22

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Auto-detect Update mode: When $ARGUMENTS names an existing skill (directory exists in .claude/skills/ or core/.claude/skills/), switch to …

    line 57
  2. Distinctive:

    Before authoring, verify the skill adds value over the agent's baseline:

    line 61
  3. Distinctive:

    Before authoring, formalize the gaps from 1.1 into 3 eval scenarios.

    line 77
  4. Distinctive:

    When the target skill already exists, follow this workflow instead of creating from scratch.

    line 93
  5. Distinctive:

    Write only what's needed to pass the eval scenarios from Step 1.2 — you'll iterate in Step 6.

    line 118
  6. Distinctive:

    Before writing steps and constraints, identify the 3 most likely failure modes for the skill's domain.

    line 136
  7. Distinctive:

    Every skill MUST make its runtime needs explicit and verify them BEFORE execution starts (owner mandate 2026-07-26).

    line 154
  8. Distinctive:

    Gate: If anything is missing: report ALL missing items in ONE consolidated list (never one at a time), ask the user to supply or fix them …

    line 178
  9. Distinctive:

    MUST NOT begin execution with a known-missing prerequisite

    line 183
  10. Distinctive:

    MUST NOT pause mid-run to request an input that STEP 0 could have collected

    line 184
  11. Very specific:

    MUST NOT improvise an undeclared fallback when something is missing — fallback ladders are allowed only when declared in the SKILL.md and …

    line 185
  12. Distinctive:

    If the prompt or workflow being authored covers a full end-to-end pipeline with 4+ distinct phases (input → processing → validation → …

    line 190
  13. Distinctive:

    Quick decision: If the workflow has ≤3 tightly coupled steps, keep it as one skill.

    line 194
  14. Distinctive:

    Use XML tags to separate content types within a step when the step mixes instructions, context, data, and constraints.

    line 239
  15. Very specific:

    When NOT to use: Do not replace the skill's top-level markdown structure (YAML frontmatter, ## STEP N: headings, ## MUST DO sections) with …

    line 243
  16. Very specific:

    Use consistent tag names throughout all steps in one skill — do not mix <constraints> and <rules> for the same purpose

    line 278
  17. Distinctive:

    No canonical "magic" tag names exist — Claude treats all XML tag names equally (per Anthropic docs)

    line 280
  18. Distinctive:

    Every constraint must have a reason — no rules without purpose.

    line 285
  19. Distinctive:

    MUST NOT items always state what to do instead

    line 286
  20. Distinctive:

    Do not repeat what the steps already say — these are for edge cases and guardrails

    line 287
  21. Very specific:

    Every skill that uses references/ MUST include a Reference Completeness Check as its final substantive step.

    line 298
  22. Distinctive:

    Before writing the skill file, run through the quality checklist in Step 5.

    line 337
  23. Distinctive:

    Warning: Do NOT generate a skill from LLM general knowledge alone — the result is vague procedures ("handle errors appropriately").

    line 357
  24. Distinctive:

    Not already covered by an existing skill

    line 377
  25. Distinctive:

    Only 2 steps, or appeared only once but is clearly reusable

    line 380
  26. Distinctive:

    Wait for user approval before creating the skill.

    line 398
  27. Distinctive:

    Before saving the skill, validate every item.

    line 456
  28. Distinctive:

    If overlap is found:

    line 505
  29. Distinctive:

    If the skill will be used across model tiers, test with the smallest target model.

    line 533
  30. Distinctive:

    Before formal eval: Run the skill informally against one real task.

    line 549
  31. Distinctive:

    When skill-evaluator returns FIX or FAIL, apply the mapped fix:

    line 567
  32. Distinctive:

    If FIX/FAIL: apply next fix (each iteration MUST try a different fix)

    line 585
  33. Distinctive:

    If PASS: proceed to 6.4

    line 586
  34. Distinctive:

    Max 5 iterations: After 5 without PASS: STOP, present full iteration history, user decides.

    line 588
  35. Distinctive:

    Before promoting, produce a failure prevention map that documents every guardrail in the skill.

    line 598
  36. Distinctive:

    When the authored pattern is an agent or orchestration-related skill, validate it against domain-specific reference patterns — not just …

    line 619
  37. Distinctive:

    MUST DO sections? Domain review checks *substance* — does the orchestrator follow the 8 principles?

    line 648
  38. Distinctive:

    If the skill is valuable enough to share across projects via the hub.

    line 658
  39. Very specific:

    After placing the skill in core/.claude/skills/<name>/SKILL.md, update the registry:

    line 680
  40. Very specific:

    Add an entry to registry/patterns.json with: name, type, category, version, hash, dependencies

    line 682
  41. Very specific:

    Run: python scripts/generate_docs.py to update the dashboard

    line 683
  42. Very specific:

    Verify the skill appears in docs/DASHBOARD.md

    line 684
  43. Distinctive:

    If contributing from a downstream project:

    line 688
  44. Very specific:

    After every authoring/update run, compare what happened against this skill's own procedure and record process lessons in …

    line 728
  45. Very specific:

    Always read AUTHOR-LEARNINGS.md before authoring (Step 1.0) and capture process lessons after (Step 10) — Why: without the loop, the same …

    line 758
  46. Distinctive:

    Always read at least 2 existing skills before authoring a new one — pattern-match from working examples

    line 759
  47. Distinctive:

    Always validate with the quality checklist (Step 5) before saving

    line 760
  48. Distinctive:

    Always check for trigger overlap with existing skills

    line 761
  49. Distinctive:

    Always include MUST DO and MUST NOT DO sections in every skill

    line 762
  50. Distinctive:

    Always include a verification step in skills that modify state

    line 763
  51. Distinctive:

    Always use concrete, actionable language in steps — verbs, not adjectives

    line 764
  52. Distinctive:

    Always present the draft to the user for review before saving

    line 765
  53. Distinctive:

    Always test the skill with 5 scenarios from Step 6 (3 happy-path + 2 edge-case)

    line 766
  54. Distinctive:

    Always complete failure mode analysis (Step 2.3) before writing constraints — prevention beats diagnosis

    line 767
  55. Very specific:

    Always include a — Why: justification on every MUST DO / MUST NOT DO item

    line 769
  56. Distinctive:

    Always lock the output format with a code block template for skills that produce structured output — Why: ambiguous output formats cause …

    line 770
  57. Distinctive:

    Always produce a failure prevention map (Step 6.5) before hub promotion — Why: makes guardrails visible and auditable during review

    line 771
  58. Distinctive:

    Always evaluate multi-phase decomposition (Step 2.4) when a prompt covers a full end-to-end workflow — Why: monolithic skills exceeding 400 …

    line 772
  59. Distinctive:

    Always run domain pattern review (Step 6.6) for agents and orchestration patterns before hub promotion — Why: structural gates pass …

    line 773
  60. Very specific:

    Always invoke /skill-evaluator via Agent tool for evaluation — do not evaluate inline

    line 774
  61. Distinctive:

    Always apply auto-fix routing for FIX/FAIL verdicts — do not ask user what to fix

    line 775
  62. Distinctive:

    Always present final skill + eval report for user approval before hub promotion

    line 776
  63. Distinctive:

    Always use gerund or action-oriented naming for skill names — Why: consistent naming improves discoverability and professionalism across …

    line 777
  64. Very specific:

    Always keep reference files one level deep from SKILL.md — Why: Claude partially reads deeply nested files, resulting in incomplete …

    line 778
  65. Very specific:

    Always copy references/self-update-protocol.md into every authored skill that has a references/ directory — Why: the protocol is the single …

    line 779
  66. Very specific:

    Always embed a Reference Completeness Check step pointing to the protocol in skills with references/ — Why: skills that don't self-update …

    line 780
  67. Very specific:

    Always create an empty references/CHANGELOG.jsonl alongside the protocol file — Why: the audit sidecar enables rollback, mode detection, …

    line 781
  68. Distinctive:

    Always require user approval before writing reference updates — Why: unreviewed auto-updates can introduce incorrect or low-quality content …

    line 782
  69. Distinctive:

    Always verify the protocol file's admission gate filters generic knowledge — Why: without filtering, references accumulate noise that …

    line 783
  70. Very specific:

    MUST NOT create a skill for something that should be a rule — if it has no steps, use .claude/rules/

    line 787
  71. Distinctive:

    MUST NOT author a skill that requests user input mid-run for something knowable at invocation — collect every declared input in STEP 0 …

    line 788
  72. Distinctive:

    MUST NOT use vague step language ("consider", "think about", "ensure quality") — use specific actions instead

    line 789
  73. Distinctive:

    MUST NOT create skills with >10 steps — split into sub-skills or use delegation

    line 790
  74. Very specific:

    MUST NOT add tools to allowed-tools that the skill does not use

    line 791
  75. Distinctive:

    MUST NOT create skills with overlapping triggers — check existing skills first

    line 792
  76. Distinctive:

    MUST NOT save a skill without running the quality checklist

    line 793
  77. Distinctive:

    MUST NOT create skills that duplicate existing ones — extend or consolidate instead

    line 794
  78. Distinctive:

    MUST NOT skip the MUST DO / MUST NOT DO sections — they are mandatory guardrails

    line 795
  79. Very specific:

    MUST NOT ask user to manually invoke /skill-evaluator — invoke it autonomously via Agent tool

    line 796
  80. Distinctive:

    MUST NOT proceed to Step 7 without user approval of the final skill + eval report

    line 797
  81. Distinctive:

    MUST NOT write descriptions in first or second person ("I analyze...", "You can use...") — always third person ("Analyzes...") because …

    line 798
  82. Very specific:

    MUST NOT chain reference files (SKILL.md → ref1.md → ref2.md) — keep one level deep from SKILL.md

    line 799
  83. Distinctive:

    MUST NOT include time-sensitive content ("before August 2025") — use collapsible "Old patterns" section instead

    line 800
  84. Distinctive:

    MUST NOT be the sole reviewer of your own skill for hub promotion — Why: separation of duties prevents blind spots and catches adversarial …

    line 801
  85. Distinctive:

    MUST NOT auto-update references without user approval — present findings and wait for confirmation before writing — Why: unreviewed writes …

    line 802
  86. Distinctive:

    MUST NOT add generic programming knowledge to references — only domain-specific patterns, edge cases, and gotchas per the admission gate in …

    line 803
  87. Very specific:

    MUST NOT skip the Reference Completeness Check for skills with references/ — the step is what makes skills self-improving rather than …

    line 804
  88. Distinctive:

    MUST NOT write reference entries with confidence below 0.70 — the admission gate rejects insufficient evidence — Why: low-confidence …

    line 805

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Writing Skills — The Skill Authoring Guide

Author new Claude Code skills or update existing ones — from scratch, from observed patterns, or from session analysis.

Request: $ARGUMENTS


Aligned with Anthropic's Skill Authoring Best Practices and Skills for Enterprise as of 2026-04.

STEP 1: Determine Authoring Mode

1.0 Read Author Learnings (self-learning loop, entry gate)

Read AUTHOR-LEARNINGS.md in this skill's directory before authoring. It records process lessons from past authoring runs — mistakes made while WRITING skills (not domain knowledge of authored skills; that lives in each skill's own references/). Apply every ACTIVE lesson to this run. If the file does not exist yet, create it from the entry format in STEP 10 and continue. This is distinct from Step 2.6 (reference self-update), which improves the authored skill — this loop improves the authoring process itself.

Parse $ARGUMENTS to choose the path:

InputModeStarting Point
from-sessionFrom Session (recommended)Start at Step 3 — best skills come from real tasks
A skill name or descriptionFrom Scratch or UpdateCheck if skill exists → Update (Step 1.3) or create (Step 2)
A URL or file path to existing workflowFrom ReferenceStart at Step 2, pre-fill from reference
Empty / vagueInteractiveAsk: "What repeated task do you want to automate?"

Auto-detect Update mode: When $ARGUMENTS names an existing skill (directory exists in .claude/skills/ or core/.claude/skills/), switch to Update mode (Step 1.3). Do not treat updates as new skill creation.

1.1 Skill Necessity Check

Before authoring, verify the skill adds value over the agent's baseline:

  1. Auto-generate 3 representative tasks from $ARGUMENTS — realistic prompts a user would type within the skill's intended scope
  2. Run each task WITHOUT a skill in a subagent (clean context)
  3. Evaluate results:
ResultAction
Agent handles all 3 wellSTOP — report "skill not needed"
Agent struggles on 1-2Capture gaps — these define the skill's value. Proceed
Agent fails on all 3Strong signal — use failure patterns to drive Step 2.3

The gaps captured here feed directly into the skill's instructions.

1.2 Design Initial Evaluations

Before authoring, formalize the gaps from 1.1 into 3 eval scenarios. These become the acceptance criteria that drive Step 2.

  1. Convert each gap into a test case: realistic user prompt + expected behavior
  2. Establish baseline: the without-skill results from 1.1 ARE the baseline
  3. Store scenarios for use in Step 6 (formal evaluation)
Gap IdentifiedEval ScenarioExpected Behavior
{from 1.1}{realistic prompt}{what success looks like}

These scenarios drive what to include in Step 2 — write ONLY what's needed to pass them. Resist comprehensive documentation until evals confirm value.

1.3 Update Mode — Modify an Existing Skill

When the target skill already exists, follow this workflow instead of creating from scratch.

  1. Read the existing skill — load the full SKILL.md and any references
  2. Identify what needs to change — based on user request, conversation context, or known gaps
  3. Classify the change scope for SemVer bump:
Change TypeVersion BumpExamples
Breaking: output format change, removed steps, renamed argumentsMAJORChanging JSON output schema, removing a step
Additive: new optional steps, new modes, expanded examplesMINORAdding an update mode, new decision table
Fix: typo, wording, formatting, bug fixPATCHFixing a code block, clarifying a step
  1. Apply changes — edit the existing SKILL.md using the Edit tool (not rewrite)
  2. Bump the version in frontmatter per the classification above
  3. Skip Steps 1.1–1.2 and Steps 2–3 — the skill's value is already proven
  4. Run Steps 4–5 — validate naming, organization, and quality checklist
  5. Run Step 6 with --baseline flag — evaluates the update against the previous version

STEP 2: Skill Authoring — From Scratch

<role>Act as a Claude skill architect who designs prompts with built-in failure prevention from the start.</role>

Build a minimal skill that addresses the gaps identified in Step 1.1. Write only what's needed to pass the eval scenarios from Step 1.2 — you'll iterate in Step 6. Focus on failure prevention from the start.

2.0 Understand the Runtime Model

Read: references/runtime-model.md — how Claude loads and navigates skills at runtime. This shapes every structural decision in Step 2.

2.1–2.2 Frontmatter, Naming, Content Standards

Read: references/skill-authoring-from-scratch.md for the complete authoring reference: YAML frontmatter fields, naming conventions (gerund form, 64-char limit), context budget (500-line target), content quality (consistent terminology, no time-sensitive info, MCP qualified names), and reference structure (one level deep, TOC for >100 lines).

2.3 Failure Mode Analysis

Before writing steps and constraints, identify the 3 most likely failure modes for the skill's domain. This drives what guardrails to build — prevention beats diagnosis.

  1. List 3 failure modes — What goes wrong when this type of task is done carelessly? (e.g., "reads stale cache instead of live data", "overwrites user changes without confirmation", "proceeds with partial input")
  2. Map each to a prevention — Each failure mode becomes a specific MUST DO or MUST NOT DO rule with a concrete guardrail (a validation step, a confirmation prompt, or a precondition check)
  3. Embed preventions into steps — Place the guardrail in the earliest step where the failure could occur, not as an afterthought at the end
Failure ModePrevention TypeWhere to Place
Wrong/stale inputValidation stepStep 1 or earliest data-reading step
Destructive action without confirmationUser approval gateStep before the destructive action
Partial execution leaving broken stateRollback or atomic commitStep that modifies state
Missing prerequisitesSTEP 0 preflight gate (mandatory — see 2.3b)STEP 0, before all other steps
Ambiguous output formatLocked output templateOutput-producing step + MUST DO

Output format MUST be locked. Every skill that produces structured output (JSON, reports, tables) MUST define the exact output format in a code block template within the output-producing step. Ambiguity in output format is the #1 cause of inconsistent skill behavior — lock it down with a concrete template, not prose descriptions.

2.3b Prerequisites & Preflight Gate (STEP 0) — mandatory in every authored skill

Every skill MUST make its runtime needs explicit and verify them BEFORE execution starts (owner mandate 2026-07-26). The defect class this eliminates: a skill that stalls mid-run asking for something — or silently improvises an alternative path — after the user has walked away.

Declare. The SKILL.md carries a ## Prerequisites section (directly after the title block) listing EVERYTHING the skill needs to complete its work:

Prerequisite classExamples
Tools / CLIsgh, jq, a test runner, a language runtime (with version if it matters)
Credentials / envAPI keys, tokens, env vars, logged-in CLIs
Files / pathsconfig files, input artifacts, expected directories
Services / connectivityreachable APIs, MCP servers, DB connections
User inputs & decisionsEVERY answer, choice, or approval the skill will need during its run

A skill with no needs states Prerequisites: none explicitly — an absent section is a defect, not a default.

Verify (STEP 0). The skill's FIRST executable step is ## STEP 0: Preflight — it probes each declared item with a cheap side-effect-free check (--version, file-exists, env-var set, read-only ping) and collects ALL declared user inputs/decisions up front, while the user is still present at invocation.

Gate. If anything is missing: report ALL missing items in ONE consolidated list (never one at a time), ask the user to supply or fix them NOW, and proceed only when every item is green. If unresolvable → HARD-STOP with the complete list and what to do about each item.

Gate rules:

  • MUST NOT begin execution with a known-missing prerequisite
  • MUST NOT pause mid-run to request an input that STEP 0 could have collected
  • MUST NOT improvise an undeclared fallback when something is missing — fallback ladders are allowed only when declared in the SKILL.md and requiring no mid-run user input

2.4 Multi-Skill Decomposition (When One Prompt → Multiple Skills)

If the prompt or workflow being authored covers a full end-to-end pipeline with 4+ distinct phases (input → processing → validation → output), decompose it into connected phase skills instead of building one monolithic skill.

Read: references/multi-skill-decomposition.md for the full decomposition workflow: phase mapping, handoff contracts with XML-tagged schemas, checkpoint patterns, and end-to-end testing protocol.

Quick decision: If the workflow has ≤3 tightly coupled steps, keep it as one skill. If it has 4+ independent phases or exceeds ~400 lines, decompose.

2.5 Structure the Steps

Steps are the core of every skill. Each step must be actionable — a verb phrase, not a vague noun.

Step Writing Rules

RuleGood ExampleBad Example
Start with a verb"Run the test suite""Test execution"
Be specific"Search src/ for files matching *Service.ts""Look at the code"
Include the command or action"Run: pytest tests/ -v""Execute the tests"
State the expected outcome"All tests should pass with 0 failures""Verify it works"
Handle failure"If tests fail, proceed to Step 5"(nothing)

Step Anatomy

Each step follows this structure:

## STEP N: Action Verb + Object

Brief explanation of WHY this step exists (1-2 sentences max).


**Read:** `references/step-n-action-verb-object.md` for detailed step n: action verb + object reference material.

## MUST DO

- Always complete Step 1 before proceeding — skipping it causes cascading errors
- Always verify output before reporting completion
- Always clean up temporary files created during execution
- Run the dedup check if skill will be promoted to the hub

## MUST NOT DO

- MUST NOT skip the verification step — unverified output is unreliable
- MUST NOT modify files outside the specified scope
- MUST NOT proceed if prerequisites are not met — ask the user instead
- MUST NOT output partial results as final — either complete the task or report what is missing

XML Tags Within Steps (Optional)

Use XML tags to separate content types within a step when the step mixes instructions, context, data, and constraints. This improves Claude's parsing accuracy — per Anthropic's prompt engineering guide, XML tags reduce misinterpretation in multi-part prompts.

When to use: Steps that mix 3+ content types (instructions + context + constraints + data). Skip for simple steps with only instructions.

When NOT to use: Do not replace the skill's top-level markdown structure (YAML frontmatter, ## STEP N: headings, ## MUST DO sections) with XML. XML tags are for within-step content separation only.

Recommended tags (names are flexible — pick what's semantically clear):

TagPurposeExample
<context>Background info the step needs<context>Read the user's $ARGUMENTS and classify input type.</context>
<constraints>Guardrails for this specific step<constraints>MUST NOT proceed if input is empty.</constraints>
<input>Variable data being processed<input>$ARGUMENTS</input>
<output>Expected output format for this step<output>JSON with {result, summary, failures} fields</output>
<examples>Few-shot examples within a stepWrap 2-3 input/output pairs

Example of a step using XML tags:

## STEP 2: Classify the Input

Determine the input type to route to the correct processing path.

<context>
The user provides either a file path, a URL, or a natural language description.
Each type requires different validation and processing.
</context>

<constraints>
- MUST detect input type before processing — wrong classification causes silent failures
- MUST reject inputs that match none of the 3 types with a clear error message
</constraints>

<output>
One of: `file_path`, `url`, or `description` — stored for use in Step 3.
</output>

Key rules for XML tag usage:

  • Use consistent tag names throughout all steps in one skill — do not mix <constraints> and <rules> for the same purpose
  • Reference tags by name when pointing to them: "Using the context in <context> tags..." not "the context above"
  • No canonical "magic" tag names exist — Claude treats all XML tag names equally (per Anthropic docs)

Rules for writing MUST DO / MUST NOT DO:

  • 4-8 items per section (fewer is better — only include non-obvious rules)
  • Each item MUST have a — Why: suffix explaining the consequence of violation (e.g., "Always validate input before processing — Why: unvalidated input caused silent data corruption in downstream steps")
  • Every constraint must have a reason — no rules without purpose. If you cannot articulate why a rule exists, do not include it
  • MUST NOT items always state what to do instead
  • Do not repeat what the steps already say — these are for edge cases and guardrails
  • Constraints from the failure mode analysis (Step 2.3) MUST appear here with their mapped preventions

Instruction Writing Patterns

Eleven patterns improve instruction quality within steps.

Read: references/instruction-writing-patterns.md for calibrating control, gotchas sections, validation loops, plan-validate-execute, defaults over menus, procedures over declarations, script design for agentic use, checklists, input/output examples, conditional workflow routing, and install-then-use patterns.

2.6 Embed Reference Self-Update Mechanism

Every skill that uses references/ MUST include a Reference Completeness Check as its final substantive step. This makes skills iteratively self-improving — each invocation can grow the skill's knowledge base.

How It Works

The protocol file references/self-update-protocol.md defines the complete workflow: runtime mode detection (FULL vs STANDALONE), structured entry format, admission gate, independent scoring, consolidation triggers, and version bump.

During skill authoring:

  1. Copy references/self-update-protocol.md from this skill's references into the new skill's references/ directory
  2. Add this step to the new skill (as the last step before any commit/output step):
## STEP N: Reference Completeness Check

Check whether this invocation surfaced knowledge not yet in references.

**Read:** `references/self-update-protocol.md` for the full detection,
scoring, gating, and consolidation workflow.
  1. Create an empty references/CHANGELOG.jsonl in the new skill's references

When to Skip

  • Skills with no references/ directory (simple skills under 200 lines)
  • Skills that are read-only / analysis-only with no domain knowledge accumulation
  • Skills that already persist knowledge through another mechanism (e.g., learnings.json)

Entry Format Summary

Each knowledge entry uses a structured 13-field format with type taxonomy (gotcha, pattern, fix, pitfall, decision, preference), state lifecycle (CANDIDATE → ACTIVE → CONSOLIDATED → DEPRECATED), numeric confidence (0.70–1.00), scope globs, and supersession pointers. Full schema is in the protocol file.

2.7 Validate Before Saving

Before writing the skill file, run through the quality checklist in Step 5.


STEP 3: Session Log Analysis

Extract skill candidates from the current conversation by identifying repeated workflows.

3.1 Scan for Repeated Patterns

Review conversation history for multi-step sequences performed 2+ times:

  1. Steps that worked — action sequence that led to success
  2. Corrections you made — where you steered the agent's approach
  3. Input/output formats — data shape going in and out
  4. Context you provided — project-specific facts the agent didn't know
  5. Repeated tool call sequences — same 3+ calls in same order
  6. Repeated file access patterns — same files across tasks

3.1b Synthesize from Project Artifacts

Warning: Do NOT generate a skill from LLM general knowledge alone — the result is vague procedures ("handle errors appropriately"). Always ground in project-specific material:

  • Internal documentation, runbooks, and style guides
  • API specifications, schemas, and configuration files
  • Code review comments and issue trackers
  • Version control history, especially patches and fixes
  • Real-world failure cases and their resolutions

3.2 Classify Candidates

For each detected pattern, classify it:

PatternTimes SeenStepsParameterizable?Skill Candidate?
{description}{N}{count}Yes/NoStrong/Weak/No

A strong candidate has:

  • 3+ steps in a consistent order
  • Appeared 2+ times in the session
  • Variable parts that can be parameterized (file names, feature names, etc.)
  • Not already covered by an existing skill

A weak candidate has:

  • Only 2 steps, or appeared only once but is clearly reusable
  • Investigate further before creating a skill

3.3 Present Findings to User

Present findings conversationally:

I noticed you performed this workflow 3 times this session:

  1. Search for files matching a pattern in src/
  2. Read each file and extract the interface definition
  3. Generate a mock implementation
  4. Write the mock to tests/mocks/

Want me to create a /generate-mock skill for this?

Wait for user approval before creating the skill. If approved, proceed to Step 2 with the extracted pattern as the starting point, parameterizing the variable parts (file pattern, source directory, output directory).


STEP 4: Naming and Organization

4.1 Directory Naming Convention

Skills live in core/.claude/skills/<name>/SKILL.md (or .claude/skills/<name>/SKILL.md for project-local skills).

TypeNaming RuleExample
Universal skillDescriptive kebab-casesystematic-debugging, writing-plans
Stack-specific skillStack prefix + descriptive namefastapi-db-migrate, android-run-tests
Compound skillPrimary-action + objectfix-loop, request-code-review

Stack Prefixes

StackPrefix
FastAPI + Pythonfastapi-
Android + Composeandroid-
React + Next.jsreact-
Flutterflutter-
Firebasefirebase-
AI / Geminiai-gemini-
Vue / Nuxtvue- or nuxt-
Expoexpo-

4.2 When to Create a New Skill vs. Extend an Existing One

SituationAction
New workflow that does not overlap with any existing skillCreate new skill
Existing skill covers 80%+ of the workflowExtend the existing skill with a new mode or step
Two skills share 50%+ of their stepsConsolidate into one skill with modes
Skills scoped too narrowly for one taskBroaden — multiple narrow skills loading risks overhead and conflicting instructions
Workflow is a single rule (no steps)Use .claude/rules/ instead — skills are for multi-step workflows
Workflow is a one-liner commandUse a hook instead — skills are overkill for single commands

4.3 When to Use Rules Instead of Skills

Skills and rules serve different purposes:

AspectSkillRule
ActivationOn-demand (slash command or natural language)Automatic (always loaded or glob-matched)
StructureMulti-step workflowDeclarative constraints
Length100-600 lines5-30 lines
Context costZero when unused (loaded on-demand)Always consumes context when matched
Use for"Do this workflow""Always/never do X"

If your "skill" has no steps and is just a list of rules, make it a rule file instead.


STEP 5: Quality Checklist

Before saving the skill, validate every item. Do NOT skip this step.

5.1 Structure Validation

CheckPass Criteria
YAML frontmatter is validAll required fields present, YAML parses without error
name matches directory namename: foo-bar lives in skills/foo-bar/SKILL.md
description starts with a verb"Debug...", "Generate...", "Analyze..."
type is declaredworkflow or reference — determines required body structure
version is valid SemVerFormat: "1.0.0" — required for version tracking
triggers has 3-6 entriesMix of slash commands and natural language
allowed-tools is minimalNo unused tools listed. Read-only skills MUST NOT include Write, Edit, or Bash
No high-risk indicators without justificationScripts, MCP refs, network access, or broad file access are documented and necessary (see references/security-review.md risk tiers)
argument-hint uses <> and [] correctlyRequired in angle brackets, optional in square brackets
No placeholder markersNo TODO/FIXME/PLACEHOLDER HTML comment markers in the body
Prerequisites contract presentA ## Prerequisites section exists (or an explicit Prerequisites: none line); when any prerequisite is declared, the first executable step is ## STEP 0: Preflight verifying every declared item and collecting all user inputs before STEP 1 (see 2.3b)
Reference self-update mechanism presentSkills with references/ include: (1) references/self-update-protocol.md copied from this skill, (2) a Reference Completeness Check step pointing to it, (3) an empty references/CHANGELOG.jsonl

5.2 Content Validation

CheckPass Criteria
Steps are numbered sequentiallySTEP 1, STEP 2, STEP 3...
Each step starts with a verb"Analyze", "Run", "Create" — not "Analysis", "Running", "Creation"
Steps have concrete actionsCommands, file paths, or specific instructions — not "consider" or "think about"
Conditional logic uses tablesNo nested if/else bullet points
Output format is templatedExpected outputs shown in code blocks
MUST DO section has 4-8 itemsEach explains the consequence of skipping
MUST NOT DO section has 4-8 itemsEach states what to do instead
No vague languageNo "consider", "maybe", "try to", "think about"
No Windows-style pathsAll file paths use forward slashes (/), even on Windows
Install-then-use for depsPackage usage shows install command before import

5.3 Overlap Check

Scan existing skills for trigger and purpose overlap:

# Check for trigger overlap
grep -r "triggers:" core/.claude/skills/*/SKILL.md -A 8

# Check for name similarity
ls core/.claude/skills/

# Check for description overlap
grep -r "description:" core/.claude/skills/*/SKILL.md -A 3

If overlap is found:

  • Same triggers, different purpose — Rename triggers to be more specific
  • Different triggers, same purpose — Consolidate into one skill
  • Partial overlap — Consider whether extending the existing skill is better than creating a new one

5.4 Length Validation

LengthAssessment
<50 linesSuspiciously short — verify it's not a stub. May belong as a rule instead of a skill.
50-200 linesAcceptable for simple, focused skills
200-500 linesIdeal range for standard skills
500-1000 linesWarning zone — consider splitting reference material into references/ subdirectory
>1000 linesToo long — MUST split into smaller skills or extract reference material into skill-name/references/*.md

For skills with extensive reference material, use this directory structure:

skill-name/
  SKILL.md           # Core workflow (under 500 lines)
  references/        # Supplementary knowledge (loaded on-demand)
    setup-guide.md
    api-reference.md
  templates/         # Reusable templates
    config.yaml

5.5 Model Compatibility

If the skill will be used across model tiers, test with the smallest target model. What works for Opus may need more guidance for Haiku:

  • Haiku: Does the skill provide enough guidance for the task?
  • Sonnet: Is the skill clear and efficient?
  • Opus: Does the skill avoid over-explaining?

STEP 6: Evaluate and Iterate with /skill-evaluator

Invoke /skill-evaluator via the Agent tool. The entire evaluate-fix-re-evaluate loop runs autonomously with one human approval at the end.

Read: references/iterative-development.md for the full Claude A/B development methodology — how to test with fresh instances, diagnose issues from observation, and gather team feedback.

Before formal eval: Run the skill informally against one real task. Read the execution trace (not just output). Fix obvious issues first.

6.1 Invoke Evaluation

For new skills:

Agent(subagent_type="general-purpose",
  prompt="/skill-evaluator full <skill-path>")

For updated skills:

Agent(subagent_type="general-purpose",
  prompt="/skill-evaluator full <skill-path> --baseline")

6.2 Auto-Fix Routing

When skill-evaluator returns FIX or FAIL, apply the mapped fix:

Eval Failure TypeAutomated Fix
Should-trigger failing (<80%)Broaden description: add user-intent phrases, expand scope
Should-not-trigger firing (>20%)Narrow description: add boundary ("do NOT use when...")
Cross-skill conflictMake triggers more specific, add distinguishing context
Trigger regression (--baseline)Restore key phrases from old description
Scenario assertion failuresAdd/clarify the step that produces the failing output
Stress test CRITICALAdd guardrail to MUST DO, embed prevention in earliest step
Stress test MAJORAdd edge case handling to relevant step's decision table
Stress score <90% overallRe-run failure mode analysis (Step 2.3), add preventions
Skill adds no value over baselineSTOP — report to user: "skill not needed"

6.3 Iterate Until PASS

  1. Apply fix from routing table
  2. Re-invoke /skill-evaluator full <skill-path>
  3. If FIX/FAIL: apply next fix (each iteration MUST try a different fix)
  4. If PASS: proceed to 6.4

Max 5 iterations. After 5 without PASS: STOP, present full iteration history, user decides.

6.4 Present for Approval

Present to user: final skill draft, eval report, iteration history, skill necessity delta.

Wait for user approval before proceeding to Step 7. This is the single human touchpoint.

6.5 Failure Prevention Map

Before promoting, produce a failure prevention map that documents every guardrail in the skill. This is the "proof of failure resistance" artifact.

## Failure Prevention Map: <skill-name>

| # | Failure Mode | Prevention | Step Where Embedded | Constraint (MUST DO/MUST NOT DO) |
|---|---|---|---|---|
| 1 | <from Step 2.3> | <validation/gate/check> | Step N | "Always X — Why: Y" |
| 2 | <from Step 2.3> | <validation/gate/check> | Step N | "MUST NOT X — do Y instead" |
| 3 | <from Step 2.3> | <validation/gate/check> | Step N | "Always X — Why: Y" |

Output format locked: <YES with template / NO — flag for fix>
Stress test score: <N%> (from Step 6.3)

Present this map to the user alongside the skill draft. The map makes failure prevention layers visible and auditable — without it, guardrails are buried in the skill body and easy to miss during review.


6.6 Domain Pattern Review

When the authored pattern is an agent or orchestration-related skill, validate it against domain-specific reference patterns — not just structural quality gates.

When to Trigger

Authored Pattern TypeDomain References to Check
Agent (any agents/*.md)agent-orchestration.md rule (tier model, responsibilities, state)
Orchestration agent or skillanthropic-agent-orchestration-guide (5 workflow patterns, decision framework)
Multi-agent system patternanthropic-multi-agent-research-system-skill (8 principles, evaluation, production)
Non-orchestration skill or ruleSKIP — domain review is not applicable

How to Review

  1. Identify the authored pattern type from the table above
  2. Read the matched reference pattern(s) — these are the audit baseline
  3. Spawn anthropic-multi-agent-reviewer-agent with the authored pattern and matched references:
    Agent(subagent_type="anthropic-multi-agent-reviewer-agent",
          prompt="Review this pattern against the 8 principles: <pattern content>")
  4. Evaluate the gap report:
    • Grade A-B → PASS — proceed to Step 7
    • Grade C → WARN — present gaps to user, fix if user agrees, then proceed
    • Grade D-F → FAIL — must fix before hub promotion

Why This Step Exists

Structural quality gates (Step 5) check shape — does the pattern have frontmatter, steps, MUST DO sections? Domain review checks substance — does the orchestrator follow the 8 principles? Does it scale effort appropriately? Does it have evaluation infrastructure?

A pattern can pass every structural gate while violating every orchestration best practice. This step closes that gap.


STEP 7: Hub Promotion Workflow

If the skill is valuable enough to share across projects via the hub.

7.1 Pre-Promotion Checklist

CheckAction
Quality checklist passes (Step 5)All items green
Tested with 5 scenarios (Step 6.1)All pass
Stress tested with 10 adversarial inputs (Step 6.3)Score >= 90%
Not a duplicateRun: PYTHONPATH=. python scripts/dedup_check.py
Follows naming conventions (Step 4)Directory and name match, correct prefix if stack-specific
version field presentSemVer format in frontmatter
type field presentworkflow or reference declared
allowed-tools is least-privilegeRead-only skills don't include Write/Edit/Bash
No project-specific hardcoded pathsReplace with $ARGUMENTS or documented placeholders
Team feedback gathered (if applicable)At least one teammate has used the skill on a real task
No placeholder markersNo TODO/FIXME HTML comment markers or stub content
Under size limitSKILL.md under 1000 lines; use references/ for supplementary material
No secrets or credentialsScan for API keys, tokens, passwords

7.2 Add to Registry

After placing the skill in core/.claude/skills/<name>/SKILL.md, update the registry:

  1. Add an entry to registry/patterns.json with: name, type, category, version, hash, dependencies
  2. Run: python scripts/generate_docs.py to update the dashboard
  3. Verify the skill appears in docs/DASHBOARD.md

7.3 Submit via Contribution Flow

If contributing from a downstream project:

  1. Invoke /contribute-practice to validate and package the skill
  2. The contribution flow handles PR creation, dedup verification, and registry updates

STEP 8: Post-Promotion Lifecycle

What happens after a skill ships: security vetting, deployment governance, monitoring, version management, deprecation, and scaling considerations.

Read: references/post-promotion-lifecycle.md for the full lifecycle covering security review gates (8.1), deployment governance with registry requirements (8.2), monitoring and drift detection (8.3), version management with rollback plans (8.4), deprecation lifecycle (8.5), and scaling considerations including recall limits and consolidation triggers (8.6).

Also read: references/security-review.md for the detailed risk tier assessment and 8-step review checklist referenced by Step 8.1.


STEP 9: Template Library

Pre-built starting skeletons for common skill types. Copy the appropriate template and fill in the placeholders.

Reference: See references/skill-templates.md for the full template library (Templates A-G: Workflow, Analysis, Generation, Testing, Deployment, Migration, Reference).


Anti-Patterns

Reference: See references/anti-patterns.md for 9 common skill anti-patterns to avoid.


STEP 10: Capture Authoring Lesson (self-learning loop, exit gate — MANDATORY)

After every authoring/update run, compare what happened against this skill's own procedure and record process lessons in AUTHOR-LEARNINGS.md:

Event this runAction
A step was wrong, missing, or misleading for this caseAppend a dated lesson naming the step and the correction
The evaluator (Step 6) caught something this skill's checklist should have caught firstAppend it — checklist gap
A workaround was improvised that future runs will needAppend it as CANDIDATE
Same lesson reaches 2+ occurrencesPromote: edit THIS SKILL.md, bump minor version, mark the entry APPLIED
Clean run, nothing newAppend nothing — no ritual entries

Entry format (append to AUTHOR-LEARNINGS.md):

## YYYY-MM-DD — <one-line summary>
- Skill authored/updated: <name>
- What went wrong / what was learned: <specific, with the step number>
- Status: CANDIDATE | CONFIRMED (2+ runs) | APPLIED (SKILL.md edited vN)

Why this exists: Step 2.6 makes AUTHORED skills self-improving; nothing made the AUTHORING PROCESS self-improving. Without this loop, the same authoring mistake (e.g., forgetting the prerequisites contract existed before 2026-07) repeats until a human notices.


MUST DO

  • Always read AUTHOR-LEARNINGS.md before authoring (Step 1.0) and capture process lessons after (Step 10) — Why: without the loop, the same authoring mistake repeats across runs until a human notices
  • Always read at least 2 existing skills before authoring a new one — pattern-match from working examples
  • Always validate with the quality checklist (Step 5) before saving
  • Always check for trigger overlap with existing skills
  • Always include MUST DO and MUST NOT DO sections in every skill
  • Always include a verification step in skills that modify state
  • Always use concrete, actionable language in steps — verbs, not adjectives
  • Always present the draft to the user for review before saving
  • Always test the skill with 5 scenarios from Step 6 (3 happy-path + 2 edge-case)
  • Always complete failure mode analysis (Step 2.3) before writing constraints — prevention beats diagnosis
  • Always author the prerequisites contract (Step 2.3b): a ## Prerequisites declaration plus a ## STEP 0: Preflight that verifies every item and collects all user inputs before STEP 1 — Why: a skill that discovers a missing tool, credential, or input mid-run stalls when the user is away or improvises an unacceptable alternative
  • Always include a — Why: justification on every MUST DO / MUST NOT DO item
  • Always lock the output format with a code block template for skills that produce structured output — Why: ambiguous output formats cause inconsistent behavior across invocations
  • Always produce a failure prevention map (Step 6.5) before hub promotion — Why: makes guardrails visible and auditable during review
  • Always evaluate multi-phase decomposition (Step 2.4) when a prompt covers a full end-to-end workflow — Why: monolithic skills exceeding 400 lines become hard to test, reuse, and maintain
  • Always run domain pattern review (Step 6.6) for agents and orchestration patterns before hub promotion — Why: structural gates pass patterns that violate orchestration best practices; domain review catches substance violations
  • Always invoke /skill-evaluator via Agent tool for evaluation — do not evaluate inline
  • Always apply auto-fix routing for FIX/FAIL verdicts — do not ask user what to fix
  • Always present final skill + eval report for user approval before hub promotion
  • Always use gerund or action-oriented naming for skill names — Why: consistent naming improves discoverability and professionalism across the skill library
  • Always keep reference files one level deep from SKILL.md — Why: Claude partially reads deeply nested files, resulting in incomplete information
  • Always copy references/self-update-protocol.md into every authored skill that has a references/ directory — Why: the protocol is the single source of truth for the self-update mechanism; without it, the Reference Completeness Check step has no instructions to follow
  • Always embed a Reference Completeness Check step pointing to the protocol in skills with references/ — Why: skills that don't self-update become stale as their domain evolves; each invocation is an opportunity to capture new knowledge
  • Always create an empty references/CHANGELOG.jsonl alongside the protocol file — Why: the audit sidecar enables rollback, mode detection, and mode upgrade (STANDALONE → FULL) when learn-n-improve is later installed
  • Always require user approval before writing reference updates — Why: unreviewed auto-updates can introduce incorrect or low-quality content into the knowledge base
  • Always verify the protocol file's admission gate filters generic knowledge — Why: without filtering, references accumulate noise that degrades rather than improves future invocations

MUST NOT DO

  • MUST NOT create a skill for something that should be a rule — if it has no steps, use .claude/rules/
  • MUST NOT author a skill that requests user input mid-run for something knowable at invocation — collect every declared input in STEP 0 Preflight instead (Step 2.3b) — Why: mid-run prompts dead-end unattended runs and force the skill to stop or improvise
  • MUST NOT use vague step language ("consider", "think about", "ensure quality") — use specific actions instead
  • MUST NOT create skills with >10 steps — split into sub-skills or use delegation
  • MUST NOT add tools to allowed-tools that the skill does not use
  • MUST NOT create skills with overlapping triggers — check existing skills first
  • MUST NOT save a skill without running the quality checklist
  • MUST NOT create skills that duplicate existing ones — extend or consolidate instead
  • MUST NOT skip the MUST DO / MUST NOT DO sections — they are mandatory guardrails
  • MUST NOT ask user to manually invoke /skill-evaluator — invoke it autonomously via Agent tool
  • MUST NOT proceed to Step 7 without user approval of the final skill + eval report
  • MUST NOT write descriptions in first or second person ("I analyze...", "You can use...") — always third person ("Analyzes...") because descriptions are injected into the system prompt and inconsistent POV causes discovery problems
  • MUST NOT chain reference files (SKILL.md → ref1.md → ref2.md) — keep one level deep from SKILL.md
  • MUST NOT include time-sensitive content ("before August 2025") — use collapsible "Old patterns" section instead
  • MUST NOT be the sole reviewer of your own skill for hub promotion — Why: separation of duties prevents blind spots and catches adversarial patterns the author may overlook (see Step 8.1)
  • MUST NOT auto-update references without user approval — present findings and wait for confirmation before writing — Why: unreviewed writes can introduce incorrect knowledge that persists across all future invocations
  • MUST NOT add generic programming knowledge to references — only domain-specific patterns, edge cases, and gotchas per the admission gate in the protocol — Why: generic entries (use try/catch, validate inputs) add noise without value
  • MUST NOT skip the Reference Completeness Check for skills with references/ — the step is what makes skills self-improving rather than static — Why: each skipped invocation is lost domain knowledge that could have improved future runs
  • MUST NOT write reference entries with confidence below 0.70 — the admission gate rejects insufficient evidence — Why: low-confidence entries degrade trust in the reference base and require costly cleanup later

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.