How to use the Writing Specs agent skill (writing-specs)

What is an agent skill and what does writing-specs do?

An agent skill is a folder containing a SKILL.md file that an AI agent loads to follow a particular set of instructions when a request matches the skill's description. The writing-specs skill is part of the ThinkRail workflow family, and its SKILL.md is the shared quality bar for every spec a workflow produces.

The skill does not run a workflow or execute code. It is guidance that shapes how the agent drafts or revises a spec at the step where one is written.

• Keeps specs short: small enough to read in one sitting, explaining intent rather than listing files or restating code.
• Records only settled content; unsettled sections are left out instead of filled with [TBD] or placeholder headings.
• Marks anything inferred rather than confirmed, inline where it stands.
• Sets new and inferred specs to status: draft until a user has reviewed them.
• Keeps rationale, decisions, invariants and bug post-mortems in the spec, not in code comments.
• Keeps the goal doc about the product: no versions, releases, phases, MVP/v1/v2 splits or later lists.

How do you install the writing-specs skill?

Download the ZIP of the skill from this page. The skill's files are SKILL.md. Unzip it into one of two places, depending on how you want to use it.

For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder so that it applies only to that repository.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/writing-specs/
• Project only: .claude/skills/writing-specs/ inside your repository

How do you trigger the skill with natural requests?

The skill loads when a request matches its description, which is about drafting or revising a spec artifact: a goal-and-requirements doc, an architecture doc or a module SPEC. You do not need to type a special command. Ask for the spec in plain language and name the kind of document you want.

The skill also loads when a workflow skill names it at a step that writes a spec, so requests made inside a ThinkRail workflow usually trigger it without extra wording.

• Draft a goal-and-requirements doc for this product, keep it to what the product does and what it excludes.
• Revise the module SPEC for the payments module so the rationale lives in the spec, not in code comments.
• Write an architecture spec for the sync service and mark anything you could not confirm from the code.

What does it need and what are the safety notes?

The skill lists no requirements. It does not run scripts and does not use the network. Its only file is SKILL.md.

It is written for projects that follow ThinkRail spec-graph conventions. It refers to spec_* tools and status fields, so in a setup without those, parts of the guidance will not map onto anything you have.

• Requires: nothing listed
• Runs scripts: no
• Uses network: no
• Files: SKILL.md

What does a good spec look like after the skill runs?

Expect a spec that is brief and specific. A module spec should explain what the module is for, what it owns and where its boundary runs. Dependencies between sibling modules belong in the parent's spec, and each fact should appear once, with links by id instead of repeated text.

Expect unconfirmed points to be labelled where they occur, and a new spec to carry status: draft until you review it.

• Read the spec in one sitting; if it is longer, ask the agent to cut it to intent and boundary.
• Check every inline unconfirmed marker before you accept the spec.
• Review the draft yourself before changing status out of draft.

Tips for getting the most out of it

Give the agent the real source material, such as the code, notes or a discussion summary, so it has something to confirm against. Without it, more of the spec will be marked unconfirmed.

Keep one spec per genuine boundary, not one per directory or file. If you are unsure whether a module needs its own spec, describe the boundary and ask the agent to justify the split.

• Paste or point to the code and decisions the spec should reflect.
• Ask for revisions in small steps, one spec at a time.
• When the agent moves a rationale paragraph out of code, check that only a one-line pointer remains where misediting would break something.