# Spec

> Use this skill when the user asks to 'write a skill spec', 'design a new skill', 'spec out a skill', 'plan a new skill', or invokes '/spec'. Guides the user through writing a skill specification for a new Claude Code skill.

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

---


# Spec — Skill Specification Writer

Guide the user through writing a specification for a new Claude Code skill. The spec should be detailed enough that a developer can implement the skill from it without further clarification.

You ARE the interviewer. Your job is to ask the right questions, then produce the spec.

## Setup

Read two existing specs to calibrate scope and format:

```bash
cat ~/.claude/skills/critique/../../ORDERS/critique.md
cat ~/.claude/skills/critique/../../ORDERS/workstreams.md
```

Also read the existing skills to understand what's already built:

```bash
for skill in ~/.claude/skills/*/SKILL.md; do head -8 "$skill"; echo "---"; done
```

## Step 1: Understand the Idea

If the user provided a name or description, start from that. Otherwise ask:

> What should this skill do? Describe it in 1-2 sentences.

Then ask clarifying questions until you understand:
- **What triggers it** — user invokes `/name`, or it fires automatically on a condition?
- **What it produces** — text output, file changes, pane content, notifications?
- **Who uses it** — the user directly, or other skills/agents?

Keep this brief — 2-3 targeted questions, not an interrogation.

## Step 2: Identify the Phases

Most skills follow a pattern: gather context, plan, execute, report. Ask the user to walk through what happens from invocation to completion. Listen for:

- Where does the skill need **user input or confirmation**?
- Where can it **run autonomously**?
- What are the **mechanical parts** (scripts) vs. **judgment parts** (LLM)?

Propose a phase breakdown (3-5 phases) and confirm with the user.

## Step 3: Draft the Spec

Write the spec as a markdown document following this structure:

```markdown
# Skill Spec: `/name`

**Purpose:** {1-2 sentences.}

---

## 1. Trigger

{How the skill is invoked. Show example invocations with arguments.}

## 2. Phases

### Phase 0: {Name}
{What happens, what tools/scripts are used, what output is produced.}

### Phase 1: {Name}
{...}

### Phase N: {Name}
{...}

## 3. Configuration

| Option | Default | Description |
|--------|---------|-------------|
| ... | ... | ... |

## 4. Error Handling

| Failure | Response |
|---------|----------|
| ... | ... |

## 5. Skill Composition

{Which existing skills does this compose with? Does it use survey, deps,
notify, pane, graph? Is it user-invocable or tool-only?}

## 6. Lessons / Open Questions

{Anything unresolved. Design tensions. Things to figure out during implementation.}
```

**Spec quality rules:**
- Every phase must say what tools it uses (Bash, Read, Write, Agent, etc.)
- Agent dispatch phases must specify `subagent_type` and whether agents run in background
- File paths must be concrete, not vague ("write to `<runtime_dir>/foo.json`", not "write to a file")
- Error handling must cover the realistic failures, not just "if something goes wrong"
- Configuration options should have sensible defaults — the skill should work with zero flags

## Step 4: Review and Refine

Present the draft to the user. Ask:

> Does this capture what you had in mind? Anything to add, cut, or change?

Iterate until the user is satisfied.

## Step 5: Save

Write the final spec to the ORDERS directory:

```bash
# Confirm the path with the user first
```

Write to: `ORDERS/<skill-name>.md`