Skill Authoring Guide
Structure
From CSO (Claude Search Optimization) research:
- Description: Contains ONLY triggering conditions ("Use when..."). Never workflow summaries. If the description tells the agent what the skill does internally, the agent will shortcut the full skill content.
- Word count targets: <200 for frequently-invoked, <500 for standard, <800 max. Verify with
wc -w before finalizing.
- Cross-reference, don't duplicate: Reference other skills inline with context-specific takeaways (e.g.,
**Verification discipline** (from /verify): <what to do here>). Never copy full content between skills — summarize the relevant point and cite the source.
- For discipline skills: Include an anti-rationalization table (excuse/reality pairs from observed failures), an Iron Law (one-line absolute rule), and a Red Flags list (thoughts that signal rationalization).
Tone
Skills are persuasive documents. They must sound authoritative and human, not like AI slop.
Avoid:
- Significance inflation: "crucial", "pivotal", "vital", "key" (just state the rule)
- Promotional language: "groundbreaking", "powerful", "seamless"
- Sycophantic tone: "Great!", "Of course!", "Certainly!"
- Filler: "In order to", "It is important to note that"
- Excessive hedging: "could potentially", "might possibly"
- Copula avoidance: "serves as", "stands as" (just use "is")
- Em dash overuse, emoji decoration, bold-header lists
Do:
- Vary sentence length. Short for rules. Longer for context.
- Have a voice. Don't write like a press release.
- Be specific. "Run tests before claiming completion" beats "ensure verification"
Persuasion Principles
LLMs respond to the same persuasion techniques as humans (Meincke et al., 2025):
- Authority: Imperative language for rules ("YOU MUST", "NEVER", "ALWAYS")
- Commitment: Required announcements, explicit choices, checkboxes
- Social Proof: Universal framing ("Every time", "Always", "No exceptions")
These techniques doubled compliance rates in studies. Use them deliberately in discipline-enforcing skills.
Checklist Before Finalizing
wc -w — within target?- Description — triggering conditions only?
- No duplication — cross-references instead?
- Anti-rationalization table — built from observed failures, not hypothesized?
- Read it aloud — does it sound human?
Informed by obra/superpowers writing-skills skill and persuasion-principles reference
1---2name: writing-skills-123description: Use when writing a new SKILL.md, revising an existing skill's instructions, or converting a repeated workflow into a reusable skill.4---5
6# Skill Authoring Guide
7
8## Structure
9
10From CSO (Claude Search Optimization) research:
11
12- **Description**: Contains ONLY triggering conditions ("Use when..."). Never workflow summaries. If the description tells the agent what the skill does internally, the agent will shortcut the full skill content.
13- **Word count targets**: <200 for frequently-invoked, <500 for standard, <800 max. Verify with `wc -w` before finalizing.
14- **Cross-reference, don't duplicate**: Reference other skills inline with context-specific takeaways (e.g., `**Verification discipline** (from /verify): <what to do here>`). Never copy full content between skills — summarize the relevant point and cite the source.
15- **For discipline skills**: Include an anti-rationalization table (excuse/reality pairs from observed failures), an Iron Law (one-line absolute rule), and a Red Flags list (thoughts that signal rationalization).
16
17## Tone
18
19Skills are persuasive documents. They must sound authoritative and human, not like AI slop.
20
21**Avoid**:
22- Significance inflation: "crucial", "pivotal", "vital", "key" (just state the rule)
23- Promotional language: "groundbreaking", "powerful", "seamless"
24- Sycophantic tone: "Great!", "Of course!", "Certainly!"
25- Filler: "In order to", "It is important to note that"
26- Excessive hedging: "could potentially", "might possibly"
27- Copula avoidance: "serves as", "stands as" (just use "is")
28- Em dash overuse, emoji decoration, bold-header lists
29
30**Do**:
31- Vary sentence length. Short for rules. Longer for context.
32- Have a voice. Don't write like a press release.
33- Be specific. "Run tests before claiming completion" beats "ensure verification"
34
35## Persuasion Principles
36
37LLMs respond to the same persuasion techniques as humans (Meincke et al., 2025):
38
39- **Authority**: Imperative language for rules ("YOU MUST", "NEVER", "ALWAYS")
40- **Commitment**: Required announcements, explicit choices, checkboxes
41- **Social Proof**: Universal framing ("Every time", "Always", "No exceptions")
42
43These techniques doubled compliance rates in studies. Use them deliberately in discipline-enforcing skills.
44
45## Checklist Before Finalizing
46
471. `wc -w` — within target?
482. Description — triggering conditions only?
493. No duplication — cross-references instead?
504. Anti-rationalization table — built from observed failures, not hypothesized?
515. Read it aloud — does it sound human?
52
53*Informed by obra/superpowers writing-skills skill and persuasion-principles reference*
majiayu000