# Writing Skills

> Use when authoring a new skill for the Leyline plugin, modifying an existing skill's behavior-shaping text, or adding to the testing-anti-patterns / forbidden-phrases lists. Applies TDD-for-prose - baseline pressure test without the skill, write the minimal skill text that rebuts the observed rationalizations, verify compliance, refactor against new loopholes.

- Skill: `forsonny/writing-skills` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add forsonny/writing-skills`
- Raw SKILL.md: https://api.skillmd.com/api/skills/forsonny/writing-skills/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: forsonny (https://skillmd.com/u/forsonny)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/forsonny/writing-skills

---


## Announce on entry

> I'm using the writing-skills skill. Skills are behavior-shaping code, not documentation. I will baseline with a pressure test, write the minimal rebuttal text, verify compliance, refactor against new rationalizations, and only then commit. If the content-change detection or the pressure-test trace cannot be produced, I will STOP rather than committing a skill change without evidence.

## Iron Law

```
NO SKILL CONTENT CHANGE WITHOUT BEFORE-AND-AFTER PRESSURE-TEST EVIDENCE
```

> Violating the letter of the rules is violating the spirit of the rules.

## Core principle

Skills are code that shapes agent behavior. Prose quality is irrelevant; behavioral compliance is the bar. If you cannot produce a baseline pressure test showing a fresh agent rationalizing around the discipline you are trying to install, you do not yet know what the skill should say. Write the test first; write the skill second; verify the test passes; hunt for new rationalizations; repeat.

The plugin's contributor rules make this non-negotiable: modifying an existing skill's behavior-shaping text without before-and-after pressure-test evidence is banned. This skill is how you produce the evidence.

## Hard gate / preconditions (STOP if not satisfied)

Before committing any content change to any `SKILL.md`, `testing-anti-patterns.md`, or agent-definition file:

1. **Content-change detection** - run the detection procedure below. If the change matches a content-change signal, the pressure-test cycle is required. If the change is genuinely non-content (cross-reference, typo in a non-match-surface location, frontmatter update not touching the description), document the determination in the PR and skip.
2. **RED trace captured** - baseline scenario run without the skill. Trace pasted into the PR and saved under `tests/<group>/<scenario-name>.md` Outcome section.
3. **GREEN trace captured** - same scenario re-run with the skill loaded. Compliance observed; forbidden phrases absent; iron-law / hard-gate blocks fire correctly.
4. **Refactor rounds run** - at least one variation of the scenario tested (pressure-shift or rationalization-invention). Loopholes found are closed; re-verified.
5. **Meta-skill self-test** - if the change touches `skills/writing-skills/` itself, run the cycle ON writing-skills (baseline a contributor-pressure scenario; verify the skill resists the "skip the pressure test" pressure). This skill's rules apply to itself.

If any precondition fails, STOP. Do not ship the change.

### Content-change detection procedure

Run each of these commands against the PR's diff; any non-empty result signals a content change:

```
# New or removed iron laws, hard gates, or preemption sentences
git diff HEAD -- '**/SKILL.md' | grep -E '^[+-].*(NO .* WITHOUT|Violating the letter|Do NOT)'

# New, removed, or reordered anti-pattern titles (changing the match surface)
git diff HEAD -- '**/SKILL.md' | grep -E '^[+-].*\*\*".*"\*\*'

# New or removed forbidden phrases
git diff HEAD -- '**/SKILL.md' | grep -E '^[+-].*^- "[^"]+"$'

# Announce-on-entry text changes
git diff HEAD -- '**/SKILL.md' | grep -B2 -A2 '^## Announce on entry' | grep -E '^[+-]'

# Red Flags table cell changes (either column)
git diff HEAD -- '**/SKILL.md' | grep -E '^[+-].*\|.*\|.*\|'

# Frontmatter description field changes
git diff HEAD -- '**/SKILL.md' | grep -E '^[+-]description:'
```

Empty across all six: non-content change, skip the pressure-test cycle. Non-empty on any: content change, the iron law applies.

Edge cases explicitly enumerated:

- **Typo fix inside a forbidden phrase, Red Flag entry, or anti-pattern name:** CONTENT CHANGE. The phrase's match surface changed.
- **Reordering Red Flag rows or forbidden phrases:** CONTENT CHANGE (ordering affects how the agent reads the table).
- **Renaming an anti-pattern:** CONTENT CHANGE.
- **Cross-reference path update with no text change:** non-content.
- **Grammar fix inside the Core principle or process prose (not touching forbidden phrases, anti-patterns, or the iron law):** non-content, but err toward pressure test if unsure.
- **Frontmatter `description` wording change:** CONTENT CHANGE (activates the skill; routing-affecting).
- **Frontmatter `name` change:** CONTENT CHANGE (breaks callers; out of scope for a routine PR).

## When to use

```dot
digraph when_to_use {
    "Skill change needed" [shape=doublecircle];
    "New skill or existing?" [shape=diamond];
    "Content-change detection positive?" [shape=diamond];
    "Use writing-skills (full cycle)" [shape=box];
    "Non-content path: document determination in PR; ship" [shape=doublecircle];
    "Full cycle: RED / GREEN / REFACTOR / commit with traces" [shape=doublecircle];

    "Skill change needed" -> "New skill or existing?";
    "New skill or existing?" -> "Full cycle: RED / GREEN / REFACTOR / commit with traces" [label="new"];
    "New skill or existing?" -> "Content-change detection positive?" [label="existing"];
    "Content-change detection positive?" -> "Full cycle: RED / GREEN / REFACTOR / commit with traces" [label="yes"];
    "Content-change detection positive?" -> "Non-content path: document determination in PR; ship" [label="no - ran detection; all six checks empty"];
}
```

Content-change detection is MECHANICAL (see Hard gate, above). Judgment-only "this feels like a typo" is insufficient; run the six grep commands.

If you are unsure whether a change is content or non-content, it is content. Err toward the pressure test.

## TDD-for-prose mapping

| TDD concept | Skill creation |
|-------------|----------------|
| Test case | Pressure scenario dispatched to a fresh subagent |
| Production code | `SKILL.md` body |
| Test fails (RED) | The subagent rationalizes around the discipline without the skill present |
| Test passes (GREEN) | The subagent complies with the discipline when the skill is loaded |
| Refactor | Close loopholes while maintaining compliance |
| Write test first | Baseline pressure scenario BEFORE writing any skill text |
| Watch it fail | Record the exact phrases and rationalizations the subagent uses |
| Minimal code | Write the minimal SKILL.md text that rebuts those phrases |
| Watch it pass | Re-run the scenario with the skill loaded; confirm compliance |
| Refactor cycle | Look for new rationalizations the agent invents now that the obvious paths are blocked; tighten the text; re-verify |

## Required background

You must understand `test-driven-development` (iron law 1) before using `writing-skills`. RED-GREEN-REFACTOR defines the cycle; this skill adapts it to prose. If you are unfamiliar, read `../test-driven-development/SKILL.md` first.

## When NOT to create a skill

Do not create a skill for:

- **One-off solutions** - a technique used once, specific to one project.
- **Standard practices documented elsewhere** - if the Anthropic docs or a canonical reference already teach it, link to that instead.
- **Project-specific conventions** - those belong in the project's `CLAUDE.md`, not in a cross-project skill.
- **Mechanical constraints** - if a regex, validator, or linter can enforce it, automate the check; do not write prose.
- **Personal preferences that don't generalize** - a skill that only helps one contributor is a personal-skill (lives under `~/.claude/skills/`), not a plugin skill.

Create a skill only when: (a) the technique is not intuitively obvious; (b) it will be referenced across projects; (c) the pattern is general enough to apply broadly; (d) others would benefit from the same discipline.

## Skill types

- **Technique** - a concrete method with steps (example in this plugin: `using-git-worktrees`).
- **Pattern** - a way of thinking about a problem (example in this plugin: `dispatching-parallel-agents`).
- **Reference** - API docs, syntax guides, tool documentation (example in this plugin: `persuasion-principles.md` under `skills/writing-skills/`).
- **Subagent-prompt template** - a constructed-context prompt for a fresh subagent dispatched by a pipeline-stage skill (example in this plugin: `skills/subagent-driven-development/implementer-prompt.md`).

The SKILL.md says which type; the pressure-test scenarios vary accordingly.

## Process

```dot
digraph writing_skills_flow {
    Start [shape=doublecircle, label="Skill change needed"];
    ContentCheck [shape=diamond, label="Content change?"];
    PRDoc [shape=box, label="Document in PR as non-content; ship"];
    Baseline [shape=box, label="1. RED: baseline pressure test without the skill"];
    Record [shape=box, label="2. Record exact rationalizations"];
    Write [shape=box, label="3. GREEN: write minimal skill text rebutting recorded rationalizations"];
    Verify [shape=box, label="4. Run scenario with skill loaded"];
    Passes [shape=diamond, label="Agent complies?"];
    Adjust [shape=box, label="Adjust wording; add forbidden phrases; re-verify"];
    Refactor [shape=box, label="5. REFACTOR: hunt for new rationalizations; tighten"];
    NewFails [shape=diamond, label="New rationalization found?"];
    AddToSkill [shape=box, label="Add rebuttal; re-verify"];
    Commit [shape=box, label="6. Commit skill + paste RED / GREEN traces into PR"];
    End [shape=doublecircle, label="Skill shipped"];

    Start -> ContentCheck;
    ContentCheck -> PRDoc [label="no"];
    ContentCheck -> Baseline [label="yes"];
    PRDoc -> End;
    Baseline -> Record -> Write -> Verify -> Passes;
    Passes -> Adjust [label="no"];
    Adjust -> Verify;
    Passes -> Refactor [label="yes"];
    Refactor -> NewFails;
    NewFails -> AddToSkill [label="yes"];
    AddToSkill -> Verify;
    NewFails -> Commit [label="no"];
    Commit -> End;
}
```

## Checklist

1. **RED - baseline the scenario.** Write a pressure test (see `testing-skills-with-subagents.md`). Dispatch a fresh subagent with the scenario but WITHOUT the skill loaded. Record:
   - The tool calls the subagent made.
   - The exact phrases it used to rationalize around the discipline you want.
   - Whether it complied or not.

   If it complied without the skill, the skill is not needed for this scenario; pick a harder scenario or write a different skill.

2. **Record the rationalizations verbatim.** These go into the skill's Forbidden-phrases list, Red-flags table, and named anti-patterns. Do not paraphrase; copy them character-for-character.

3. **GREEN - write the minimal skill text that rebuts those rationalizations.** Start with:
   - Frontmatter (name, description - "Use when..." per `../../dev/reference/skill-file-format.md`).
   - Announce-on-entry sentence (commits to STOP behavior).
   - Iron law (if applicable) in a fenced code block.
   - "Violating the letter..." preemption sentence immediately after.
   - The minimum body that names the rationalizations from step 2 and rebuts each.

4. **Re-run the scenario with the skill loaded.** The agent must comply. If it does not:
   - The skill is not strong enough; tighten the wording.
   - Add specific forbidden phrases matching the agent's new rationalizations.
   - Re-verify.

5. **REFACTOR - hunt for new rationalizations.** Once the obvious paths are blocked, agents invent new ones. Run variations of the scenario (different framings, different pressure sources, different tool sets). Record the new rationalizations; add to the skill; re-verify.

6. **Commit the skill AND the pressure-test evidence.** The PR must include:
   - The RED trace (baseline without the skill).
   - The GREEN trace (scenario with the skill, showing compliance).
   - A one-sentence write-up of what rationalization the new text plugs.

   PRs without these traces are closed unreviewed per `.github/PULL_REQUEST_TEMPLATE.md`.

## Supporting files

- `anthropic-best-practices.md` - official skill-authoring conventions, mapped to Leyline's opinionated extensions.
- `persuasion-principles.md` - notes on how skill language actually influences agent behavior (what shapes of text produce compliance vs what shapes produce rationalization).
- `graphviz-conventions.dot` - DOT shape/edge conventions used in in-skill diagrams (doublecircle for start/end, diamond for decision, box for action).
- `testing-skills-with-subagents.md` - the pressure-testing methodology in detail, with scenario templates.
- `examples/` - worked examples of skills produced by this process, with their RED/GREEN traces.

## Mandatory body sections

Every Leyline skill must have these sections, in this order, unless the skill type explicitly exempts one:

1. **Frontmatter** - `name`, `description` starting with "Use when..." (under 1024 bytes total).
2. **Announce on entry** - the literal sentence the agent emits on invocation, committing to STOP on precondition failure.
3. **Iron law** (if applicable) - fenced code block.
4. **"Violating the letter..." preemption** - immediately after the iron law.
5. **Core principle** - one paragraph naming what this skill exists to prevent.
6. **Hard gate / preconditions** - mechanical checks the agent must run. Use grep templates where possible; do not leave checks as prose unless they are genuinely unrunnable mechanically.
7. **Process** - a DOT diagram showing decision points and action boxes. Numbered steps in prose where the diagram alone is unclear.
8. **Checklist** - one TodoWrite entry per step the agent executes.
9. **Anti-patterns** - Title Case in quotes, each with an explanatory body that names the specific failure mode.
10. **Red flags** - two-column Markdown table (`Thought` / `Reality`) with rationalizations agents actually use.
11. **Forbidden phrases** - explicit sentence fragments the agent must not emit.
12. **Output artifacts** - what the skill produces (files, commits, markers).
13. **Successor** - the next skill the pipeline invokes, or "returns to caller" for overlays, or "none - pipeline terminates" for terminal skills.
14. **Missing-successor fallback** - what to do if the named successor is absent from the plugin version.
15. **Related** - cross-references.

## Skill types - required section variance

- **Pipeline-stage skill** - all 15 sections required.
- **Overlay skill** (Stage 6: TDD, systematic-debugging, verification-before-completion, design-driven-development, accessibility-verification) - sections 6 (Hard gate), 12 (Output artifacts), 13 (Successor), and 14 (Missing-successor fallback) are exempted or reduced: the iron law serves as the entry gate instead of a numbered Hard gate; outputs are the compliance evidence itself (not a committed artifact); the successor is "returns to caller; no pipeline successor"; missing-successor fallback is N/A because overlays have no named successor. Other sections (announce, iron law, "Violating the letter...", core principle, process, checklist, anti-patterns, red flags, forbidden phrases, related) remain required.
- **Reference file** (non-`SKILL.md` supporting content, including `testing-anti-patterns.md`, `anthropic-best-practices.md`, `persuasion-principles.md`, the reviewer-prompt templates) - no YAML frontmatter required; an H1 title serves as the file identifier. No announce / iron law / process required. Each reference file must still declare its role at the top and cross-reference the invoking skill at the bottom.
- **Subagent-prompt template** - the prompt string is the body inside a fenced code block; surrounding Markdown describes when to dispatch and what inputs to substitute. No frontmatter. Canonical example: `skills/subagent-driven-development/implementer-prompt.md`.
- **Meta-skill** (`writing-skills`, this file) - pipeline-stage structure applies, plus Hard gate includes a meta-rule that changes to THIS skill run the full cycle against a contributor-pressure scenario in `tests/`.

## Anti-patterns

- **"Ship The Skill; Tests Come Later"** - skills without tests regress silently. The tests ARE the skill; no tests means no evidence of behavior change.
- **"Paraphrase The Agent's Rationalization For Clarity"** - the agent reaches for specific sentence shapes. Paraphrasing changes the match surface; the agent's next rationalization will not match the paraphrase. Copy verbatim.
- **"Add To The Body When A Forbidden Phrase Is Simpler"** - forbidden phrases are a cheaper, more specific block than prose. Prefer them.
- **"Write A Single Long Anti-Pattern Block"** - each anti-pattern gets its own named bullet. Aggregation hides which specific shortcut is being blocked.
- **"Skip The Announce-On-Entry Because It's Ceremonial"** - the announce commits the agent. Skipping it leaves the agent free to slide past the discipline without ever having acknowledged it.
- **"Refactor To Reads Well But Loses Behavior"** - compliance-edit without re-running the pressure test silently regresses the skill. Contributor rules block this for a reason.
- **"Stop Testing After GREEN"** - REFACTOR is where the loopholes get closed. Agents invent new rationalizations once the obvious paths are blocked; the second and third iterations of testing are the most valuable.

## Red flags

| Thought | Reality |
|---------|---------|
| "The skill text reads cleanly; ship it" | Reading clean is not complying under pressure. Run the scenario. |
| "I already know what the agent will rationalize" | Then writing it down takes 5 minutes. Do it; don't guess. |
| "The baseline is obvious; skip RED" | The baseline's purpose is to record the exact phrases you will rebut. "Obvious" never produces a compliance list. |
| "One pressure-test round is enough" | One round blocks the obvious paths. Two rounds blocks the less obvious. Three rounds is where most real skills settle. |
| "Mandatory sections are bureaucratic" | The structure is behavior-shaping. Missing sections are missing defenses. |
| "I can write the skill from a template" | Templates produce templates. Skills that survive pressure testing have text specific to the rationalization they block. |

## Forbidden phrases

Do not say:

- "Tests come later"
- "Good enough for v1"
- "I'll add forbidden phrases if agents complain"
- "Paraphrased for clarity"
- "Skipped the baseline; the skill is obvious"
- "Compliance-edit; no pressure test needed"

## Output artifacts

- New or modified `SKILL.md` / reference file / subagent-prompt template committed to the repo.
- Corresponding scenario file under `tests/<group>/<scenario-name>.md` with RED and GREEN traces captured in the Outcome section.
- PR entry referencing both, with the `.github/PULL_REQUEST_TEMPLATE.md` skill-change-evidence section completed.
- If the content-change detection ran and came up empty (non-content change), a one-line PR note citing the six detection commands with their empty outputs.

## Returns to caller

This is a meta-skill. After the six-step cycle completes and the skill is committed with traces, control returns to the caller (usually a contributor-PR session, or a plugin-author session). No pipeline successor.

### Missing-successor fallback

Not applicable — meta-skill does not name a pipeline successor. However, if the `tests/` directory, the scenario group (e.g., `tests/skill-triggering/`), or `scripts/check-manifests.sh` is missing in this version of the plugin, STOP and surface the gap to the human partner; the full cycle cannot be run without those artifacts present.

## Related

- `../test-driven-development/SKILL.md` - the RED-GREEN-REFACTOR discipline this skill adapts to prose
- `../../dev/principles/tdd-for-prose.md` - canonical methodology reference
- `../../dev/principles/behavior-shaping.md` - why skills are written as behavior-shaping code rather than prose
- `../../dev/reference/skill-file-format.md` - frontmatter and body rules
- `../../dev/reference/diagrams.md` - DOT conventions
- `../using-leyline/SKILL.md` - the entry skill whose structure is the default template
- `testing-skills-with-subagents.md` - pressure-testing methodology in detail
- `anthropic-best-practices.md` - official skill-authoring conventions
- `persuasion-principles.md` - how skill language influences agent behavior
- `graphviz-conventions.dot` - DOT conventions reference file