writing-skills

Name: writing-skills
Author: heymegabyte

18stars4forks

How to install writing-skills?

heymegabyte/claude-skills/writing-skills

$npx -y skills add heymegabyte/claude-skills --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	Writing a skill IS TDD on process documentation: watch an agent fail the task WITHOUT the skill (RED), write the skill against those exact failures (GREEN), close the loopholes it then invents (REFACTOR). If you never watched it fail without the skill, you don't know the skill teaches the right thing.
4
5	Vendored from [obra/Superpowers](https://github.com/obra/Superpowers) (MIT, Jesse Vincent), compressed to house style per `[[vendored-skill-compression]]`.
6
7	REQUIRED BACKGROUND: superpowers:test-driven-development defines the RED-GREEN-REFACTOR cycle this adapts.
8
9	## Authoring contract lives in one canonical place
10
11	Ordered-by-weight bullets, the behavior-anchored `description` template, description-SDO (WHEN not WHAT), and "match the form to the failure" are the house authoring contract — see `[[skill-authoring-contract]]`, don't restate them. Token-efficient prose style: `[[instruction-compression-playbook]]`. This file covers only what's specific to creating + testing a skill.
12
13	## What a skill is
14
15	A reference guide for a proven technique, pattern, or tool — reusable, not a narrative of how you solved something once. Three shapes:
16
17	- Technique — a concrete method with steps (`condition-based-waiting`, `root-cause-tracing`).
18	- Pattern — a way of thinking about a class of problem (`flatten-with-flags`).
19	- Reference — API/syntax/tool docs.
20
21	## When to create one
22
23	- Create when: the technique wasn't obvious to you, you'd reuse it across projects, and it applies broadly.
24	- Don't create for: one-offs, things well-documented elsewhere, project-specific conventions (put those in the instructions file), or anything a regex/validator can enforce — automate that instead of documenting it.
25
26	## Iron Law
27
28	NO SKILL — OR EDIT — SHIPS WITHOUT A FAILING TEST FIRST. Wrote it before testing? Delete it, start from baseline. No exception for "simple additions", "just a section", or "documentation updates". Don't keep untested changes "as reference". Delete means delete.
29
30	## Structure
31
32	Two required frontmatter fields: `name` (letters/numbers/hyphens only) and `description` (≤1024 chars total; see [agentskills.io/specification](https://agentskills.io/specification) for the rest). Then a lean body:
33
34	```markdown
35	## Overview # what + core principle, 1-2 sentences
36	## When to Use # symptoms / use cases; when NOT to; small flowchart only if the decision is non-obvious
37	## Core Pattern # before/after for techniques & patterns
38	## Quick Reference # table or bullets for scanning
39	## Implementation # inline code for simple cases; link a file for heavy reference
40	## Common Mistakes # what goes wrong + the fix
41	```
42
43	SKILL.md is a table of contents (progressive disclosure). Inline only what changes per task; split out when content is heavy:
44
45	- Heavy reference (100+ lines of API/syntax) → its own file, loaded on demand.
46	- Reusable tool (script, template) → its own file.
47	- Keep inline: principles, concepts, code patterns under ~50 lines.
48
49	Cross-reference other skills by name with an explicit marker (`REQUIRED: superpowers:test-driven-development`) — never `@path`, which force-loads the file and burns 200k+ context before you need it.
50
51	## Code examples
52
53	One excellent example beats five languages. Make it complete, runnable, from a real scenario, commented with WHY — not a fill-in-the-blank template. You're good at porting; one great example is enough.
54
55	## Flowcharts
56
57	Use a small inline flowchart ONLY for a non-obvious decision point, a process loop where you might stop too early, or an "A vs B" choice. Never for reference material (use tables/lists), code (use markdown blocks), or linear steps (use a numbered list). Style rules: `graphviz-conventions.dot`. Render for a human: `./render-graphs.js ../some-skill [--combine]`.
58
59	## Testing & bulletproofing
60
61	The full method — pressure scenarios, the RED-GREEN-REFACTOR loop for skills, rationalization tables, red-flags, micro-testing wording against a no-guidance control, and the per-skill deployment gate — lives in [testing-skills.md](testing-skills.md). A worked campaign is in [examples/CLAUDE_MD_TESTING.md](examples/CLAUDE_MD_TESTING.md). Persuasion levers that make a discipline skill bind: persuasion-principles.md.
62
63	The one-line discipline: discipline/judgment skills get pressure-tested under 3+ stacked pressures; pure reference skills get retrieval-tested instead.
64
65	## See
66
67	- [testing-skills.md](testing-skills.md) — the testing + bulletproofing method
68	- anthropic-best-practices.md — pointer to Anthropic's public authoring guide + local deltas
69	- persuasion-principles.md — Cialdini levers for compliance under pressure
70	- `[[skill-authoring-contract]]` — the canonical authoring contract (structure, description template, form-to-failure)
71	- `[[instruction-compression-playbook]]` — token-efficient prose styl

People who liked this also viewed

6 picks

Type

find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 20262.6M27k
grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026633k182k
vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026573k29k
improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026522k182k
setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026454k182k
triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026424k182k

writing-skills

18stars4forks

View on GitHub

How to install writing-skills?

heymegabyte/claude-skills/writing-skills

$npx -y skills add heymegabyte/claude-skills --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	Writing a skill IS TDD on process documentation: watch an agent fail the task WITHOUT the skill (RED), write the skill against those exact failures (GREEN), close the loopholes it then invents (REFACTOR). If you never watched it fail without the skill, you don't know the skill teaches the right thing.
4
5	Vendored from [obra/Superpowers](https://github.com/obra/Superpowers) (MIT, Jesse Vincent), compressed to house style per `[[vendored-skill-compression]]`.
6
7	REQUIRED BACKGROUND: superpowers:test-driven-development defines the RED-GREEN-REFACTOR cycle this adapts.
8
9	## Authoring contract lives in one canonical place
10
11	Ordered-by-weight bullets, the behavior-anchored `description` template, description-SDO (WHEN not WHAT), and "match the form to the failure" are the house authoring contract — see `[[skill-authoring-contract]]`, don't restate them. Token-efficient prose style: `[[instruction-compression-playbook]]`. This file covers only what's specific to creating + testing a skill.
12
13	## What a skill is
14
15	A reference guide for a proven technique, pattern, or tool — reusable, not a narrative of how you solved something once. Three shapes:
16
17	- Technique — a concrete method with steps (`condition-based-waiting`, `root-cause-tracing`).
18	- Pattern — a way of thinking about a class of problem (`flatten-with-flags`).
19	- Reference — API/syntax/tool docs.
20
21	## When to create one
22
23	- Create when: the technique wasn't obvious to you, you'd reuse it across projects, and it applies broadly.
24	- Don't create for: one-offs, things well-documented elsewhere, project-specific conventions (put those in the instructions file), or anything a regex/validator can enforce — automate that instead of documenting it.
25
26	## Iron Law
27
28	NO SKILL — OR EDIT — SHIPS WITHOUT A FAILING TEST FIRST. Wrote it before testing? Delete it, start from baseline. No exception for "simple additions", "just a section", or "documentation updates". Don't keep untested changes "as reference". Delete means delete.
29
30	## Structure
31
32	Two required frontmatter fields: `name` (letters/numbers/hyphens only) and `description` (≤1024 chars total; see [agentskills.io/specification](https://agentskills.io/specification) for the rest). Then a lean body:
33
34	```markdown
35	## Overview # what + core principle, 1-2 sentences
36	## When to Use # symptoms / use cases; when NOT to; small flowchart only if the decision is non-obvious
37	## Core Pattern # before/after for techniques & patterns
38	## Quick Reference # table or bullets for scanning
39	## Implementation # inline code for simple cases; link a file for heavy reference
40	## Common Mistakes # what goes wrong + the fix
41	```
42
43	SKILL.md is a table of contents (progressive disclosure). Inline only what changes per task; split out when content is heavy:
44
45	- Heavy reference (100+ lines of API/syntax) → its own file, loaded on demand.
46	- Reusable tool (script, template) → its own file.
47	- Keep inline: principles, concepts, code patterns under ~50 lines.
48
49	Cross-reference other skills by name with an explicit marker (`REQUIRED: superpowers:test-driven-development`) — never `@path`, which force-loads the file and burns 200k+ context before you need it.
50
51	## Code examples
52
53	One excellent example beats five languages. Make it complete, runnable, from a real scenario, commented with WHY — not a fill-in-the-blank template. You're good at porting; one great example is enough.
54
55	## Flowcharts
56
57	Use a small inline flowchart ONLY for a non-obvious decision point, a process loop where you might stop too early, or an "A vs B" choice. Never for reference material (use tables/lists), code (use markdown blocks), or linear steps (use a numbered list). Style rules: `graphviz-conventions.dot`. Render for a human: `./render-graphs.js ../some-skill [--combine]`.
58
59	## Testing & bulletproofing
60
61	The full method — pressure scenarios, the RED-GREEN-REFACTOR loop for skills, rationalization tables, red-flags, micro-testing wording against a no-guidance control, and the per-skill deployment gate — lives in [testing-skills.md](testing-skills.md). A worked campaign is in [examples/CLAUDE_MD_TESTING.md](examples/CLAUDE_MD_TESTING.md). Persuasion levers that make a discipline skill bind: persuasion-principles.md.
62
63	The one-line discipline: discipline/judgment skills get pressure-tested under 3+ stacked pressures; pure reference skills get retrieval-tested instead.
64
65	## See
66
67	- [testing-skills.md](testing-skills.md) — the testing + bulletproofing method
68	- anthropic-best-practices.md — pointer to Anthropic's public authoring guide + local deltas
69	- persuasion-principles.md — Cialdini levers for compliance under pressure
70	- `[[skill-authoring-contract]]` — the canonical authoring contract (structure, description template, form-to-failure)
71	- `[[instruction-compression-playbook]]` — token-efficient prose styl

People who liked this also viewed

6 picks

Type