writing-skills
This skill produces convention-compliant SKILL.md files. It does not grade
its own output — that job belongs to two gates it hands off to by name. Read
this file when you're about to draft, edit, or repair a skill; read the gates'
own SKILL.md files when it's time to actually run them.
The Docs Cycle, Borrowed From TDD
develop:test-driven-development treats a passing test as worthless until
someone watched it fail for the predicted reason first. This skill borrows
that shape for prose instead of code:
| Code TDD |
Docs equivalent here |
| Failing test, written before the fix |
A scenario where an agent misbehaves without the skill present — the gap the skill must close |
| Watching it fail for the right reason |
Confirming the miss is a real gap, not a fluke of that one prompt |
| Minimal code to go green |
The smallest SKILL.md draft that plausibly closes the gap |
| Refactor once green |
Trimming and reordering the draft without reopening the gap |
The mechanics of running that pressure scenario — how to construct one, how
many pressures to stack, how to read the transcript — are not re-taught here;
see testing-skills-with-subagents.md for the method and
examples/CLAUDE_MD_TESTING.md for worked scenario scripts. What this skill
owns is turning a confirmed gap into a draft; what happens to that draft next
is covered below.
Dual-Mode Authoring
The same four moves run whether you're drafting alone or a harness:harness
run is driving.
| Move |
Solo |
Harness-engaged |
| Scope the gap |
You name the miss from memory or a quick manual probe |
SetGoal's acceptance criteria already state the gap as a subgoal |
| Draft |
You write the SKILL.md directly |
An Implement executor writes it against the subgoal's acceptance bar |
| Trigger check |
You invoke skill:skill-trigger-validator yourself before calling it done |
The QualityGate stage invokes it as part of scoring the subgoal |
| Ship gate |
You invoke skill:skill-quality-assurance yourself and act on its report |
QualityGate invokes it; a failing report blocks the subgoal, not just a suggestion |
Unsure which lane you're in: if a harness pipeline handed you this task, act
in harness-engaged mode and let its stage boundaries decide when a gate runs.
Otherwise default to solo and run both gates yourself before calling the work
done.
Process
- Confirm the gap is real. State the situation where the current skill
(or the absence of one) produces the wrong outcome. No gap, no draft —
go find one before writing anything.
- Place the file.
<plugin>/skills/<kebab-name>/SKILL.md, one skill per
directory, per .claude/conventions/coding.md.
- Draft frontmatter.
name and a description that opens with "Use
when" and states triggering conditions only — never a summary of what the
skill does internally, that's the shortcut agents take instead of reading
the body. Add scenarios (2–3 EN, 2–3 KR) and a compatibility block if
an MCP tool genuinely changes the outcome.
- Draft the body in this relative order:
Process, Output Template,
What Claude Does / What You Do, Related Skills — other sections may
sit between them, but these four stay in that sequence and nothing titled
Overview or Background sits ahead of Process.
- Run the RED-phase check from the cycle above — by hand in solo mode,
or read off the subgoal's acceptance criteria in harness mode.
- Hand off, don't re-score. Call
skill:skill-trigger-validator for
description and trigger coverage, then skill:skill-quality-assurance
for the full pre-ship pass. Fix what they flag; don't re-derive their
checks inline in the draft.
- Close what the gates flagged, re-run the gate that flagged it, repeat
until both pass clean.
- Ship housekeeping. Per
.claude/conventions/boundaries.md: bump the
plugin's version in .claude-plugin/marketplace.json, update that
plugin's README.md, and re-run scripts/validate_plugins.py.
Output Template
A finished unit of work from this skill is:
- The
SKILL.md file (plus any supporting files it actually points to).
- A one-line statement of the gap it closes (from step 1).
- The
skill-trigger-validator verdict and, if it rewrote the description,
which wording won.
- The
skill-quality-assurance report's Top Improvements section, with
each 🔴 item resolved before calling the skill shipped.
- The version-bump / README-update diff from step 8.
Reference Files
anthropic-best-practices.md — Anthropic's own authoring guidance; read
this before inventing structure from scratch.references/authoring-reference.md — the SKILL.md structure template,
flowchart rules, code-example rules, and file-organization patterns.references/checklist.md — a step-by-step drafting checklist matching
the Process above, useful as a TodoWrite seed.testing-skills-with-subagents.md — how to build the RED-phase pressure
scenario the Docs Cycle above assumes you already know how to run.examples/CLAUDE_MD_TESTING.md — worked pressure-scenario scripts to
adapt rather than write from a blank page.persuasion-principles.md — why imperative phrasing and named loopholes
outperform soft guidance in discipline-style skills; consult it when a
draft keeps getting negotiated with in testing.graphviz-conventions.dot and render-graphs.js — style rules and a
render script for the rare skill where a small inline flowchart earns its
place; most skills need neither.
What Claude Does / What You Do
| Claude |
You |
| Confirms the gap and drafts frontmatter + body against the Process order |
Confirm the stated gap is the real one, not a proxy for it |
Calls skill:skill-trigger-validator and skill:skill-quality-assurance rather than self-scoring |
Read both reports; call the go/no-go on anything not clearly 🔴 |
| Applies fixes the gates flag and re-runs the gate that flagged them |
Approve the final draft before it ships |
| Performs the version/README housekeeping the boundaries convention requires |
Confirm the version bump matches what actually changed |
Related Skills
skill:skill-trigger-validator — scores and rewrites the description
field for trigger coverage; the authority on step 6's first half.skill:skill-quality-assurance — the six-check pre-ship gate; the
authority on step 6's second half and on whether a skill is worth keeping
at all.develop:test-driven-development — source of the RED-GREEN-REFACTOR shape
this skill re-expresses for documentation instead of code.harness:harness — the six-stage engine that drives the harness-engaged
column above; SetGoal, Implement, and QualityGate own the stage boundaries
this skill defers to in that mode.
1---2name: writing-skills3description: Use when creating a new skill, editing an existing SKILL.md, or fixing one that misfires. Triggers: "스킬 만들어줘", "새 skill 작성", "SKILL.md 써줘", "skill 개선해줘", "create a skill", "skill documentation", "스킬 문서 작성", "workflow skill로 만들어줘".4---56# writing-skills78This skill produces convention-compliant `SKILL.md` files. It does not grade9its own output — that job belongs to two gates it hands off to by name. Read10this file when you're about to draft, edit, or repair a skill; read the gates'11own SKILL.md files when it's time to actually run them.1213## The Docs Cycle, Borrowed From TDD1415`develop:test-driven-development` treats a passing test as worthless until16someone watched it fail for the predicted reason first. This skill borrows17that shape for prose instead of code:1819| Code TDD | Docs equivalent here |20|---|---|21| Failing test, written before the fix | A scenario where an agent misbehaves *without* the skill present — the gap the skill must close |22| Watching it fail for the right reason | Confirming the miss is a real gap, not a fluke of that one prompt |23| Minimal code to go green | The smallest SKILL.md draft that plausibly closes the gap |24| Refactor once green | Trimming and reordering the draft without reopening the gap |2526The mechanics of running that pressure scenario — how to construct one, how27many pressures to stack, how to read the transcript — are not re-taught here;28see `testing-skills-with-subagents.md` for the method and29`examples/CLAUDE_MD_TESTING.md` for worked scenario scripts. What this skill30owns is turning a confirmed gap into a draft; what happens to that draft next31is covered below.3233## Dual-Mode Authoring3435The same four moves run whether you're drafting alone or a `harness:harness`36run is driving.3738| Move | Solo | Harness-engaged |39|---|---|---|40| Scope the gap | You name the miss from memory or a quick manual probe | SetGoal's acceptance criteria already state the gap as a subgoal |41| Draft | You write the SKILL.md directly | An Implement executor writes it against the subgoal's acceptance bar |42| Trigger check | You invoke `skill:skill-trigger-validator` yourself before calling it done | The QualityGate stage invokes it as part of scoring the subgoal |43| Ship gate | You invoke `skill:skill-quality-assurance` yourself and act on its report | QualityGate invokes it; a failing report blocks the subgoal, not just a suggestion |4445Unsure which lane you're in: if a harness pipeline handed you this task, act46in harness-engaged mode and let its stage boundaries decide when a gate runs.47Otherwise default to solo and run both gates yourself before calling the work48done.4950## Process51521. **Confirm the gap is real.** State the situation where the current skill53 (or the absence of one) produces the wrong outcome. No gap, no draft —54 go find one before writing anything.552. **Place the file.** `<plugin>/skills/<kebab-name>/SKILL.md`, one skill per56 directory, per `.claude/conventions/coding.md`.573. **Draft frontmatter.** `name` and a `description` that opens with "Use58 when" and states triggering conditions only — never a summary of what the59 skill does internally, that's the shortcut agents take instead of reading60 the body. Add `scenarios` (2–3 EN, 2–3 KR) and a `compatibility` block if61 an MCP tool genuinely changes the outcome.624. **Draft the body** in this relative order: `Process`, `Output Template`,63 `What Claude Does / What You Do`, `Related Skills` — other sections may64 sit between them, but these four stay in that sequence and nothing titled65 Overview or Background sits ahead of `Process`.665. **Run the RED-phase check** from the cycle above — by hand in solo mode,67 or read off the subgoal's acceptance criteria in harness mode.686. **Hand off, don't re-score.** Call `skill:skill-trigger-validator` for69 description and trigger coverage, then `skill:skill-quality-assurance`70 for the full pre-ship pass. Fix what they flag; don't re-derive their71 checks inline in the draft.727. **Close what the gates flagged**, re-run the gate that flagged it, repeat73 until both pass clean.748. **Ship housekeeping.** Per `.claude/conventions/boundaries.md`: bump the75 plugin's version in `.claude-plugin/marketplace.json`, update that76 plugin's `README.md`, and re-run `scripts/validate_plugins.py`.7778## Output Template7980A finished unit of work from this skill is:81821. The `SKILL.md` file (plus any supporting files it actually points to).832. A one-line statement of the gap it closes (from step 1).843. The `skill-trigger-validator` verdict and, if it rewrote the description,85 which wording won.864. The `skill-quality-assurance` report's Top Improvements section, with87 each 🔴 item resolved before calling the skill shipped.885. The version-bump / README-update diff from step 8.8990## Reference Files9192- `anthropic-best-practices.md` — Anthropic's own authoring guidance; read93 this before inventing structure from scratch.94- `references/authoring-reference.md` — the SKILL.md structure template,95 flowchart rules, code-example rules, and file-organization patterns.96- `references/checklist.md` — a step-by-step drafting checklist matching97 the Process above, useful as a TodoWrite seed.98- `testing-skills-with-subagents.md` — how to build the RED-phase pressure99 scenario the Docs Cycle above assumes you already know how to run.100- `examples/CLAUDE_MD_TESTING.md` — worked pressure-scenario scripts to101 adapt rather than write from a blank page.102- `persuasion-principles.md` — why imperative phrasing and named loopholes103 outperform soft guidance in discipline-style skills; consult it when a104 draft keeps getting negotiated with in testing.105- `graphviz-conventions.dot` and `render-graphs.js` — style rules and a106 render script for the rare skill where a small inline flowchart earns its107 place; most skills need neither.108109## What Claude Does / What You Do110111| Claude | You |112|--------|-----|113| Confirms the gap and drafts frontmatter + body against the Process order | Confirm the stated gap is the real one, not a proxy for it |114| Calls `skill:skill-trigger-validator` and `skill:skill-quality-assurance` rather than self-scoring | Read both reports; call the go/no-go on anything not clearly 🔴 |115| Applies fixes the gates flag and re-runs the gate that flagged them | Approve the final draft before it ships |116| Performs the version/README housekeeping the boundaries convention requires | Confirm the version bump matches what actually changed |117118## Related Skills119120- `skill:skill-trigger-validator` — scores and rewrites the `description`121 field for trigger coverage; the authority on step 6's first half.122- `skill:skill-quality-assurance` — the six-check pre-ship gate; the123 authority on step 6's second half and on whether a skill is worth keeping124 at all.125- `develop:test-driven-development` — source of the RED-GREEN-REFACTOR shape126 this skill re-expresses for documentation instead of code.127- `harness:harness` — the six-stage engine that drives the harness-engaged128 column above; SetGoal, Implement, and QualityGate own the stage boundaries129 this skill defers to in that mode.
newkayak12