writing-skills

Name: writing-skills
Author: obra

byobra· 95 skills

Installs

151k

Stars

261k

Forks

23k

How to install writing-skills?

obra/superpowers/writing-skills

$npx -y skills add obra/superpowers --skill writing-skills

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/obra/superpowers" --skill "obra/superpowers/writing-skills"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/obra/superpowers" that are relevant to the current task. Run `npx skills add "https://github.com/obra/superpowers"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# Writing Skills
2
3	## Overview
4
5	Writing skills IS Test-Driven Development applied to process documentation.
6
7	Personal skills live in your runtime's skills directory (`~/.claude/skills/` on Claude Code) — see [codex-tools.md](../using-superpowers/references/codex-tools.md) or [gemini-tools.md](../using-superpowers/references/gemini-tools.md) for the path on those runtimes. Codex, Copilot CLI, and Gemini CLI all also recognize `~/.agents/skills/` as a cross-runtime alias.
8
9	You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
10
11	Core principle: If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
12
13	REQUIRED BACKGROUND: You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
14
15	Official guidance: For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.
16
17	## What is a Skill?
18
19	A skill is a reference guide for proven techniques, patterns, or tools. Skills help future agents find and apply effective approaches.
20
21	Skills are: Reusable techniques, patterns, tools, reference guides
22
23	Skills are NOT: Narratives about how you solved a problem once
24
25	## TDD Mapping for Skills
26
27	\| TDD Concept \| Skill Creation \|
28	\|-------------\|----------------\|
29	\| Test case \| Pressure scenario with subagent \|
30	\| Production code \| Skill document (SKILL.md) \|
31	\| Test fails (RED) \| Agent violates rule without skill (baseline) \|
32	\| Test passes (GREEN) \| Agent complies with skill present \|
33	\| Refactor \| Close loopholes while maintaining compliance \|
34	\| Write test first \| Run baseline scenario BEFORE writing skill \|
35	\| Watch it fail \| Document exact rationalizations agent uses \|
36	\| Minimal code \| Write skill addressing those specific violations \|
37	\| Watch it pass \| Verify agent now complies \|
38	\| Refactor cycle \| Find new rationalizations → plug → re-verify \|
39
40	The entire skill creation process follows RED-GREEN-REFACTOR.
41
42	## When to Create a Skill
43
44	Create when:
45	- Technique wasn't intuitively obvious to you
46	- You'd reference this again across projects
47	- Pattern applies broadly (not project-specific)
48	- Others would benefit
49
50	Don't create for:
51	- One-off solutions
52	- Standard practices well-documented elsewhere
53	- Project-specific conventions (put in your instructions file)
54	- Mechanical constraints (if it's enforceable with regex/validation, automate it—save documentation for judgment calls)
55
56	## Skill Types
57
58	### Technique
59	Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)
60
61	### Pattern
62	Way of thinking about problems (flatten-with-flags, test-invariants)
63
64	### Reference
65	API docs, syntax guides, tool documentation (office docs)
66
67	## Directory Structure
68
69
70	```
71	skills/
72	skill-name/
73	SKILL.md # Main reference (required)
74	supporting-file.* # Only if needed
75	```
76
77	Flat namespace - all skills in one searchable namespace
78
79	Separate files for:
80	1. Heavy reference (100+ lines) - API docs, comprehensive syntax
81	2. Reusable tools - Scripts, utilities, templates
82
83	Keep inline:
84	- Principles and concepts
85	- Code patterns (< 50 lines)
86	- Everything else
87
88	## SKILL.md Structure
89
90	Frontmatter (YAML):
91	- Two required fields: `name` and `description` (see [agentskills.io/specification](https://agentskills.io/specification) for all supported fields)
92	- Max 1024 characters total
93	- `name`: Use letters, numbers, and hyphens only (no parentheses, special chars)
94	- `description`: Third-person, describes ONLY when to use (NOT what it does)
95	- Start with "Use when..." to focus on triggering conditions
96	- Include specific symptoms, situations, and contexts
97	- NEVER summarize the skill's process or workflow (see SDO section for why)
98	- Keep under 500 characters if possible
99
100	```markdown
101	---
102	name: Skill-Name-With-Hyphens
103	description: Use when [specific triggering conditions and symptoms]
104	---
105
106	# Skill Name
107
108	## Overview
109	What is this? Core principle in 1-2 sentences.
110
111	## When to Use
112	[Small inline flowchart IF decision non-obvious]
113
114	Bullet list with SYMPTOMS and use cases
115	When NOT to use
116
117	## Core Pattern (for techniques/patterns)
118	Before/after code comparison
119
120	## Quick Reference
121	Table or bullets for scanning common operations
122
123	## Implementation
124	Inline code for simple patterns
125	Link to file for heavy reference or reusable tools
126
127	## Common Mistakes
128	What goes wrong + fixes
129
130	## Real-World Impact (optional)
131	Concrete results
132	```
133
134
135	## Skill Discovery Optimization (SDO)
136
137	Critical for discovery: Future agents need to FIND your skill
138
139	### 1. Rich Description Field
140
141	Purpose: Your agent reads the description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"
142
143	Format: Start with "Use when..." to focus on triggering conditions
144
145	CRITICAL: Description = When to Use, NOT What the Skill Does
146
147	The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description.
148
149	Why this matters: Testing revealed that when a description summarizes the skill's workflow, an agent may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused an agent to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality).
150
151	When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), the agent correctly read the flowchart and followed the two-stage review process.
152
153	The trap: Descriptions that summarize workflow create a shortcut agents will take. The skill body becomes documentation agents skip.
154
155	```yaml
156	# ❌ BAD: Summarizes workflow - agents may follow this instead of reading skill
157	description: Use when executing plans - dispatches subagent per task with code review between tasks
158
159	# ❌ BAD: Too much process detail
160	description: Use for TDD - write test first, watch it fail, write minimal code, refactor
161
162	# ✅ GOOD: Just triggering conditions, no workflow summary
163	description: Use when executing implementation plans with independent tasks in the current session
164
165	# ✅ GOOD: Triggering conditions only
166	description: Use when implementing any feature or bugfix, before writing implementation code
167	```
168
169	Content:
170	- Use concrete triggers, symptoms, and situations that signal this skill applies
171	- Describe the problem (race conditions, inconsistent behavior) not language-specific symptoms (setTimeout, sleep)
172	- Keep triggers technology-agnostic unless the skill itself is technology-specific
173	- If skill is technology-specific, make that explicit in the trigger
174	- Write in third person (injected into system prompt)
175	- NEVER summarize the skill's process or workflow
176
177	```yaml
178	# ❌ BAD: Too abstract, vague, doesn't include when to use
179	description: For async testing
180
181	# ❌ BAD: First person
182	description: I can help you with async tests when they're flaky
183
184	# ❌ BAD: Mentions technology but skill isn't specific to it
185	description: Use when tests use setTimeout/sleep and are flaky
186
187	# ✅ GOOD: Starts with "Use when", describes problem, no workflow
188	description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
189
190	# ✅ GOOD: Technology-specific skill with explicit trigger
191	description: Use when using React Router and handling authentication redirects
192	```
193
194	### 2. Keyword Coverage
195
196	Use words an agent would search for:
197	- Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
198	- Symptoms: "flaky", "hanging", "zombie", "pollution"
199	- Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
200	- Tools: Actual commands, library names, file types
201
202	### 3. Descriptive Naming
203
204	Use active voice, verb-first:
205	- ✅ `creating-skills` not `skill-creation`
206	- ✅ `condition-based-waiting` not `async-test-helpers`
207
208	### 4. Token Efficiency (Critical)
209
210	Problem: getting-started and frequently-referenced skills load into EVERY conversation. Every token counts.
211
212	Target word counts:
213	- getting-started workflows: <150 words each
214	- Frequently-loaded skills: <200 words total
215	- Other skills: <500 words (still be concise)
216
217	Techniques:
218
219	Move details to tool help:
220	```bash
221	# ❌ BAD: Document all flags in SKILL.md
222	search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
223
224	# ✅ GOOD: Reference --help
225	search-conversations supports multiple modes and filters. Run --help for details.
226	```
227
228	Use cross-references:
229	```markdown
230	# ❌ BAD: Repeat workflow details
231	When searching, dispatch subagent with template...
232	[20 lines of repeated instructions]
233
234	# ✅ GOOD: Reference other skill
235	Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
236	```
237
238	Compress examples:
239	```markdown
240	# ❌ BAD: Verbose example (42 words)
241	your human partner: "How did we handle authentication errors in React Router before?"
242	You: I'll search past conversations for React Router authentication patterns.
243	[Dispatch subagent with search query: "React Router authentication error handling 401"]
244
245	# ✅ GOOD: Minimal example (20 words)
246	Partner: "How did we handle auth errors in React Router?"
247	You: Searching...
248	[Dispatch subagent → synthesis]
249	```
250
251	Eliminate redundancy:
252	- Don't repeat what's in cross-referenced skills
253	- Don't explain what's obvious from command
254	- Don't include multiple examples of same pattern
255
256	Verification:
257	```bash
258	wc -w skills/path/SKILL.md
259	# getting-started workflows: aim for <150 each
260	# Other frequently-loaded: aim for <200 total
261	```
262
263	Name by what you DO or core insight:
264	- ✅ `condition-based-waiting` > `async-test-helpers`
265	- ✅ `using-skills` not `skill-usage`
266	- ✅ `flatten-with-flags` > `data-structure-refactoring`
267	- ✅ `root-cause-tracing` > `debugging-techniques`
268
269	Gerunds (-ing) work well for processes:
270	- `creating-skills`, `testing-skills`, `debugging-with-logs`
271	- Active, describes the action you're taking
272
273	### 5. Cross-Referencing Other Skills
274
275	When writing documentation that references other skills:
276
277	Use skill name only, with explicit requirement markers:
278	- ✅ Good: `REQUIRED SUB-SKILL: Use superpowers:test-driven-development`
279	- ✅ Good: `REQUIRED BACKGROUND: You MUST understand superpowers:systematic-debugging`
280	- ❌ Bad: `See skills/testing/test-driven-development` (unclear if required)
281	- ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)
282
283	Why no @ links: `@` syntax force-loads files immediately, consuming 200k+ context before you need them.
284
285	## Flowchart Usage
286
287	```dot
288	digraph when_flowchart {
289	"Need to show information?" [shape=diamond];
290	"Decision where I might go wrong?" [shape=diamond];
291	"Use markdown" [shape=box];
292	"Small inline flowchart" [shape=box];
293
294	"Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
295	"Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
296	"Decision where I might go wrong?" -> "Use markdown" [label="no"];
297	}
298	```
299
300	Use flowcharts ONLY for:
301	- Non-obvious decision points
302	- Process loops where you might stop too early
303	- "When to use A vs B" decisions
304
305	Never use flowcharts for:
306	- Reference material → Tables, lists
307	- Code examples → Markdown blocks
308	- Linear instructions → Numbered lists
309	- Labels without semantic meaning (step1, helper2)
310
311	See `graphviz-conventions.dot` in this directory for graphviz style rules.
312
313	Visualizing for your human partner: Use `render-graphs.js` in this directory to render a skill's flowcharts to SVG:
314	```bash
315	./render-graphs.js ../some-skill # Each diagram separately
316	./render-graphs.js ../some-skill --combine # All diagrams in one SVG
317	```
318
319	## Code Examples
320
321	One excellent example beats many mediocre ones
322
323	Choose most relevant language:
324	- Testing techniques → TypeScript/JavaScript
325	- System debugging → Shell/Python
326	- Data processing → Python
327
328	Good example:
329	- Complete and runnable
330	- Well-commented explaining WHY
331	- From real scenario
332	- Shows pattern clearly
333	- Ready to adapt (not generic template)
334
335	Don't:
336	- Implement in 5+ languages
337	- Create fill-in-the-blank templates
338	- Write contrived examples
339
340	You're good at porting - one great example is enough.
341
342	## File Organization
343
344	### Self-Contained Skill
345	```
346	defense-in-depth/
347	SKILL.md # Everything inline
348	```
349	When: All content fits, no heavy reference needed
350
351	### Skill with Reusable Tool
352	```
353	condition-based-waiting/
354	SKILL.md # Overview + patterns
355	example.ts # Working helpers to adapt
356	```
357	When: Tool is reusable code, not just narrative
358
359	### Skill with Heavy Reference
360	```
361	pptx/
362	SKILL.md # Overview + workflows
363	pptxgenjs.md # 600 lines API reference
364	ooxml.md # 500 lines XML structure
365	scripts/ # Executable tools
366	```
367	When: Reference material too large for inline
368
369	## The Iron Law (Same as TDD)
370
371	```
372	NO SKILL WITHOUT A FAILING TEST FIRST
373	```
374
375	This applies to NEW skills AND EDITS to existing skills.
376
377	Write skill before testing? Delete it. Start over.
378	Edit skill without testing? Same violation.
379
380	No exceptions:
381	- Not for "simple additions"
382	- Not for "just adding a section"
383	- Not for "documentation updates"
384	- Don't keep untested changes as "reference"
385	- Don't "adapt" while running tests
386	- Delete means delete
387
388	REQUIRED BACKGROUND: The superpowers:test-driven-development skill explains why this matters. Same principles apply to documentation.
389
390	## Testing All Skill Types
391
392	Different skill types need different test approaches:
393
394	### Discipline-Enforcing Skills (rules/requirements)
395
396	Examples: TDD, verification-before-completion, designing-before-coding
397
398	Test with:
399	- Academic questions: Do they understand the rules?
400	- Pressure scenarios: Do they comply under stress?
401	- Multiple pressures combined: time + sunk cost + exhaustion
402	- Identify rationalizations and add explicit counters
403
404	Success criteria: Agent follows rule under maximum pressure
405
406	### Technique Skills (how-to guides)
407
408	Examples: condition-based-waiting, root-cause-tracing, defensive-programming
409
410	Test with:
411	- Application scenarios: Can they apply the technique correctly?
412	- Variation scenarios: Do they handle edge cases?
413	- Missing information tests: Do instructions have gaps?
414
415	Success criteria: Agent successfully applies technique to new scenario
416
417	### Pattern Skills (mental models)
418
419	Examples: reducing-complexity, information-hiding concepts
420
421	Test with:
422	- Recognition scenarios: Do they recognize when pattern applies?
423	- Application scenarios: Can they use the mental model?
424	- Counter-examples: Do they know when NOT to apply?
425
426	Success criteria: Agent correctly identifies when/how to apply pattern
427
428	### Reference Skills (documentation/APIs)
429
430	Examples: API documentation, command references, library guides
431
432	Test with:
433	- Retrieval scenarios: Can they find the right information?
434	- Application scenarios: Can they use what they found correctly?
435	- Gap testing: Are common use cases covered?
436
437	Success criteria: Agent finds and correctly applies reference information
438
439	## Common Rationalizations for Skipping Testing
440
441	\| Excuse \| Reality \|
442	\|--------\|---------\|
443	\| "Skill is obviously clear" \| Clear to you ≠ clear to other agents. Test it. \|
444	\| "It's just a reference" \| References can have gaps, unclear sections. Test retrieval. \|
445	\| "Testing is overkill" \| Untested skills have issues. Always. 15 min testing saves hours. \|
446	\| "I'll test if problems emerge" \| Problems = agents can't use skill. Test BEFORE deploying. \|
447	\| "Too tedious to test" \| Testing is less tedious than debugging bad skill in production. \|
448	\| "I'm confident it's good" \| Overconfidence guarantees issues. Test anyway. \|
449	\| "Academic review is enough" \| Reading ≠ using. Test application scenarios. \|
450	\| "No time to test" \| Deploying untested skill wastes more time fixing it later. \|
451
452	All of these mean: Test before deploying. No exceptions.
453
454	## Match the Form to the Failure
455
456	Before writing guidance, classify the baseline failure. The form that bulletproofs one failure type measurably backfires on another.
457
458	\| Baseline failure \| Right form \| Wrong form \|
459	\|---\|---\|---\|
460	\| Skips/violates a rule under pressure (knows better, does it anyway) \| Prohibition + rationalization table + red flags (see Bulletproofing below) \| Soft guidance ("prefer...", "consider...") \|
461	\| Complies, but output has the wrong shape (bloated prompt, buried verdict, restated spec) \| Positive recipe or contract: state what the output IS — its parts, in order \| Prohibition list ("don't restate", "never narrate") \|
462	\| Omits a required element from something they already produce \| Structural: REQUIRED field or slot in the template they fill in \| Prose reminders near the template \|
463	\| Behavior should depend on a condition \| Conditional keyed to an observable predicate ("if the brief exists, reference it") \| Unconditional rule + exemption clauses \|
464
465	Why prohibitions backfire on shaping problems: under a competing incentive ("make the prompt self-contained"), agents negotiate with "don't X". In head-to-head wording tests on dispatch-prompt guidance, the prohibition arm produced clearly more of the unwanted content than the recipe arm (fully separated distributions), and trended worse than even the no-guidance control — micro-test your own case rather than assuming, but never reach for the prohibition by default. A recipe leaves nothing to negotiate: the output matches the stated shape or it doesn't.
466
467	Rules for whichever form you pick:
468	- No nuance clauses. "Don't X unless it matters" reopens the negotiation — appending a single nuance clause to a winning recipe degraded it from consistent to noisy in the same wording tests. Express a real exception as its own conditional on an observable predicate.
469	- Exemption clauses don't scope. "This limit doesn't apply to code blocks" still suppresses code blocks. If part of the output must be exempt, restructure so the rule can't reach it.
470
471	## Bulletproofing Skills Against Rationalization
472
473	Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure.
474
475	Scope: this toolkit is for discipline failures — an agent that knows the rule and skips it under pressure. For wrong-shaped output or omitted elements, prohibition-based bulletproofing backfires; use the forms in Match the Form to the Failure instead.
476
477	Psychology note: Understanding WHY persuasion techniques work helps you apply them systematically. See persuasion-principles.md for research foundation (Cialdini, 2021; Meincke et al., 2025) on authority, commitment, scarcity, social proof, and unity principles.
478
479	### Close Every Loophole Explicitly
480
481	Don't just state the rule - forbid specific workarounds:
482
483	<Bad>
484	```markdown
485	Write code before test? Delete it.
486	```
487	</Bad>
488
489	<Good>
490	```markdown
491	Write code before test? Delete it. Start over.
492
493	No exceptions:
494	- Don't keep it as "reference"
495	- Don't "adapt" it while writing tests
496	- Don't look at it
497	- Delete means delete
498	```
499	</Good>
500
501	### Address "Spirit vs Letter" Arguments
502
503	Add foundational principle early:
504
505	```markdown
506	Violating the letter of the rules is violating the spirit of the rules.
507	```
508
509	This cuts off entire class of "I'm following the spirit" rationalizations.
510
511	### Build Rationalization Table
512
513	Capture rationalizations from baseline testing (see Testing section below). Every excuse agents make goes in the table:
514
515	```markdown
516	\| Excuse \| Reality \|
517	\|--------\|---------\|
518	\| "Too si

6 picks

Type

Run `npx skills use "https://github.com/obra/superpowers" --skill "obra/superpowers/writing-skills"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/obra/superpowers" that are relevant to the current task. Run `npx skills add "https://github.com/obra/superpowers"` and select the relevant skills, then follow their instructions.

writing-skills

How to install writing-skills?

Related

writing-skills

How to install writing-skills?

Related