# Writing Skills

> Writing Skills

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

---


# Writing Skills

A skill exists to pull consistent behavior out of a probabilistic model. Every rule below serves
that: say only what changes behavior, make it easy to find, keep it easy to read.

This is the shared craft — a lightweight, always-on reference to write a SKILL.md well. For an
interactive workshop that scaffolds, runs evals/benchmarks, and optimizes a description, install
Anthropic's [`skill-creator`](https://github.com/anthropics/skills/tree/main/skills/skill-creator);
these principles still apply to what it produces.

For environment specifics, pair this with the matching surface skill:
[`claude-md-and-folder-standards`](../claude-md-and-folder-standards/SKILL.md) for Claude Code, or
[`authoring-app-skills`](../authoring-app-skills/SKILL.md) for the Claude app/Cowork.

## Frontmatter

- Required: `name` (lowercase, hyphens, ≤64 chars, no "claude"/"anthropic") and `description`.
- **The description is the whole discovery mechanism.** It's the only part preloaded every session;
  the model picks this skill from it alone. Write it in **third person**, and state both **what** the
  skill does and **when** to use it (the triggering conditions). Front-load the distinctive trigger word.

## Say only what changes behavior

- Assume the model is already smart. Add only what it would get wrong or can't know.
- **No-op test, per sentence:** if a line doesn't change behavior versus the default, delete it —
  don't reword it. "Write clean code" fails. Real conventions, gotchas, and exact steps pass.
- One idea, one home. Duplication across sections (or skills) drifts and rots — link instead.

## Progressive disclosure

- The SKILL.md body is the map, not the whole territory. Keep occasional/heavy detail in sibling
  files and link to them; they cost nothing until read.
- **Keep links one level deep from SKILL.md.** Nested pointers get partially read and missed.
- Inline what *every* path needs; push behind a link what only *some* paths need.

## Scope & size

- One workflow or domain per skill. If two distinct triggers want independent firing, that's two skills.
- Keep the body tight — say only what earns its place. Anthropic's ceiling is 500 lines; split to
  sibling files well before that. Fewer lines that all pass the no-op test beats padding to a limit.

## Style that reads reliably

- **Match specificity to fragility.** Fragile, one-right-way tasks get exact steps; open tasks get
  direction and trust. Over-specifying an open task is as harmful as under-specifying a fragile one.
- Use one term per concept throughout — consistency helps the model parse.
- Show input→output examples where quality depends on shape; they teach faster than description.
- **Steer toward the target behavior, not away from the wrong one.** Prohibitions make the banned
  behavior more salient — prefer stating what to do; reserve "don't" for true guardrails, paired
  with the positive alternative.
- No time-sensitive phrasing ("after August"). Put superseded guidance in an "old patterns" aside.

## Before done

1. Does the description alone tell a cold model what this is and when to fire it?
2. Every remaining sentence passes the no-op test?
3. One domain, links one level deep, no duplication with sibling skills?