菜单
Use when writing a new skill or modifying/verifying an existing skill. Confirms the skill works under pressure scenarios before distribution.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Update the per-session intent ledger for every user input and provide current intent as semantic context consumed by gates, skill-evolution, and jailbreak-detector. Keep intent summaries without storing raw prompts.
Use when the user asks about skill upgrades, update recommendations, or an evolution backlog; analyze io-trace and conduct_feedback to produce report-only evolution candidates. No automatic edits.
Use when an implementation plan already exists. Execute it in a separate session with review checkpoints.
Use when implementing a known feature, bug fix, or refactor with a resolved behavior contract. Requires a failing test before production code; use discovery first when the target or premise is unknown.
Use at the start of every coding or development conversation. Defines how to find and invoke coding-convention family skills. Requires relevant skills before any response, including clarification questions.
Runs after session-intent-analyzer and jailbreak-detector/downstream gate as their consumer. Decomposes the request and routes output, verification, lifecycle, and boundary skills without owning intake, raw intent inference, or tool permission.
| name | writing-skills |
| description | Use when writing a new skill or modifying/verifying an existing skill. Confirms the skill works under pressure scenarios before distribution. |
| compatibility | ["Python 3.11+ standard library"] |
Writing a skill applies TDD (test-driven development) to process documentation. Write the test cases first (pressure scenarios), observe the failure (the baseline), write the skill document (the implementation), and confirm success again (verification). Finally, close the loopholes (refactoring).
Core principle: if you have not directly seen an agent fail without the skill, you cannot know whether the skill teaches the right thing.
Required background: you must first understand coding-convention:test-driven-development. That skill defines the foundation of the RED-GREEN-REFACTOR cycle.
A skill is a reference guide to a proven technique, pattern, or tool. It helps future Claude instances find and apply an effective approach.
A skill is a reusable technique, pattern, and tool. It is not a narrative of one time you solved a problem.
| TDD concept | Writing skills |
|---|---|
| Test case | A pressure scenario including subagents |
| Production code | The skill document (SKILL.md) |
| RED failure | The agent violates the rule without the skill |
| GREEN success | The agent complies when the skill is present |
| REFACTOR | Maintain compliance while closing loopholes |
The entire skill-writing process follows RED-GREEN-REFACTOR.
description, examples, references, and calls directly prevent the failure revealed in RED.Write a skill when:
Do not write a skill when:
Technique: a concrete method with steps to follow (for example, condition-based waiting, root-cause tracing).
Pattern: a way of thinking about a problem (for example, flattening with flags, invariant testing).
Reference: API documentation, syntax guides, tool manuals.
skills/
skill-name/
SKILL.md # required
supporting-file.* # only when needed
Flat namespace. Every skill is searchable.
Split out:
Keep inline:
Frontmatter (YAML):
name, description.name: lowercase, digits, and hyphens only (no special characters).description: third person, start with "Use when...", trigger conditions only (no process description).Body structure:
Making sure future Claude can find the skill is important.
The description must do only two things:
Test result: when the description summarizes the workflow, Claude follows the description without reading the body. A description like "proceeds between code reviews" makes Claude do only one review, even though two are actually needed.
When you change the description to "use when executing an implementation plan as an independent task", Claude reads the body and correctly follows the two reviews.
Good examples:
Bad examples:
Use the words Claude would search for:
A frequently loaded skill is included in every conversation. Tokens are precious.
Target word counts:
Techniques: move detail into tool help, reference other skills, compress examples, remove duplication.
Required prerequisite: you must understand coding-convention:test-driven-development
Do not use @ links. They load the file immediately and waste context.
No writing a skill without a failing test
This applies both to new skills and to modifying existing skills.
Wrote the skill first and tested after? Delete it. Start over. Modified the skill but did not test it? Same violation.
No exceptions:
Test approach by skill type:
Rule-enforcement skills (TDD, verification-before-completion):
Technique skills (condition-based waiting, root-cause tracing):
Pattern skills (mental models):
Reference skills (documentation, API):
For detailed test methods, see references/skill-testing-guide.md.
For reinforcement patterns that block rationalization escape routes (bulletproofing). Pressure scenarios, counter-example collections, blocking the "this is different" excuse, STOP gates, repeated injection, and so on. See references/bulletproofing-skills.md.
For exact examples, counter-examples, and the authoring procedure in Condition-Skill-Output form, see references/condition-skill-output-detailed.md.
- Writing code without writing the test first
- "I already tested it manually"
- "Writing after the test achieves the same goal"
- "I kept the spirit of it"
- "This is different, because..."
All of these mean: delete the code. Start over with TDD.
RED: run the pressure scenario without the skill. What exactly does it do? What excuses does it make? Which pressure triggers the violation?
GREEN: write the minimal skill that addresses those excuses. Run the same scenario with the skill. The agent must now comply.
REFACTOR: when you find a new excuse, add an explicit response. Retest until there are no loopholes.
RED Phase. Write the failing test:
GREEN Phase. Write the minimal skill:
name, description (max 1024 chars).REFACTOR Phase. Close the loopholes:
Quality checks:
Distribution:
When to use:
When not to use:
For graphviz style rules, see references/graphviz-conventions.dot.
One outstanding example beats several mediocre ones.
Choose the most relevant language:
A good example:
Do not:
After writing any skill, you must stop and complete the distribution process.
Do not:
Distributing an untested skill = distributing untested code. A violation of the quality standard.
How future Claude finds a skill:
Optimize for this flow. Place searchable items toward the front, frequently.
Writing a skill applies TDD to process documentation. The same Iron Law, the same cycle, the same benefits. If you follow TDD for code, you follow it for skills. It is the same principle applied to documentation.
All of this skill's supporting material lives under references/. Do not load it when the SKILL.md body is sufficient. Read the relevant file only in the situations below.
references/anthropic-best-practices.md: a summary of Anthropic's official skill-writing guide. Reference it when writing a skill for external release or when you need spec grounding.references/bulletproofing-skills.md: rationalization-avoidance reinforcement patterns such as pressure scenarios, counter-example collections, blocking the "this is different" excuse, STOP gates, and repeated injection. Reference it when designing tests for rule-enforcement skills.references/condition-skill-output-detailed.md: exact examples, counter-examples, and the authoring procedure in Condition-Skill-Output form. Reference it when refining the description wording.references/graphviz-conventions.dot: Graphviz flowchart style rules. Reference it when writing a flowchart.references/persuasion-principles.md: principles for designing pressure and persuasion scenarios. Reference it when designing RED Phase pressure scenarios.references/review-loop.md: details of the review loop that iteratively hunts for loopholes after GREEN. Reference it when the REFACTOR step gets stuck.references/skill-testing-guide.md: detailed test methods by skill type. Reference it when the body "Test Strategy" section is too blunt.references/testing-skills-with-subagents.md: the procedure for verifying a skill using subagents. Reference it when running a pressure scenario that cannot be tested by hand.references/trigger-eval.md: a method for evaluating the description trigger accuracy (recall and precision). Reference it when confirming for regressions before and after a Condition-Skill-Output wording change.references/examples/CLAUDE_MD_TESTING.md: a real case where test rules were injected into CLAUDE.md to verify skill compliance. Reference it when you need a test-setup example.