| name | writing-skills |
| description | 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로 만들어줘". |
| scenarios | ["이 워크플로우를 skill로 만들어줘","새 skill SKILL.md 작성해줘","Create a skill for this repeatable process","기존 skill 개선해줘","I want to capture this pattern as a reusable skill","Skill 설명이 너무 약한 것 같아, 개선해줘"] |
| compatibility | {"optional":["think-tool"],"remote_mcp_note":"think-tool이 있으면 RED 단계 압박 시나리오를 설계하고 어떤 실패를 겨냥하는지 미리 정리하는 데 활용됩니다. Claude 설정 → MCP Servers에서 remote SSE 엔드포인트를 추가하세요."} |
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.
