writing-skills

Name: writing-skills
Author: obra

145kinstalls23kforks

How to install writing-skills?

obra/superpowers/writing-skills

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

Installs into the current project.

Summary

Use when creating new skills, editing existing skills, or verifying skills work before deployment

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

People who liked this also viewed

6 picks

Type

hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026262k37k
request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026165k181k
analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026161k507
explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026161k507
ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026160k181k
scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026149k181k

writing-skills

145kinstalls23kforks

View on GitHub

How to install writing-skills?

obra/superpowers/writing-skills

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

Installs into the current project.

Summary

Use when creating new skills, editing existing skills, or verifying skills work before deployment

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

People who liked this also viewed

6 picks

Type