# Writing Skills > 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로 만들어줘". - Skill: `newkayak12/writing-skills` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add newkayak12/writing-skills` - Raw SKILL.md: https://api.skillmd.com/api/skills/newkayak12/writing-skills/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: newkayak12 (https://skillmd.com/u/newkayak12) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/newkayak12/writing-skills --- # 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 1. **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. 2. **Place the file.** `/skills//SKILL.md`, one skill per directory, per `.claude/conventions/coding.md`. 3. **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. 4. **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`. 5. **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. 6. **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. 7. **Close what the gates flagged**, re-run the gate that flagged it, repeat until both pass clean. 8. **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: 1. The `SKILL.md` file (plus any supporting files it actually points to). 2. A one-line statement of the gap it closes (from step 1). 3. The `skill-trigger-validator` verdict and, if it rewrote the description, which wording won. 4. The `skill-quality-assurance` report's Top Improvements section, with each 🔴 item resolved before calling the skill shipped. 5. 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.