1. Where It Fits
- Before implementation, when the ticket is still ambiguous.
- Before PR review, when generated code needs evidence.
- Before API rollout, when consumers need a clear contract.
- After incidents, when the team needs a spec gap analysis.
Spec-first AI workflow
Agent Skills for Spec-First Work
A skill is a folder with a SKILL.md in it. That is the whole mechanism. What makes it worth using for spec work is when it loads: a spec template you paste by hand is a habit you have to remember, while a skill is instructions the agent pulls in on its own when the task matches. This page covers what goes in the file, which location wins when two skills share a name, and where a spec belongs when the alternatives are CLAUDE.md, a slash command, or a subagent.
Use case: structure before implementation
What a SKILL.md actually contains
Two parts: YAML frontmatter between --- markers, then Markdown instructions the agent follows once the skill is active. One rule catches people out — the opening --- has to be the file's first line. Put anything above it and the whole file, markers included, is treated as skill content.
.claude/skills/spec-packet/SKILL.md
---
name: spec-packet
description: Turn a ticket into a reviewable spec before any code is written. Use when the request names a feature, a bug, or an API change but leaves scope, failure paths, or evidence undecided.
allowed-tools: Read Grep Glob
---
Write the spec first. Do not propose an implementation in this turn.
## Required sections
goal / non-goals / roles / behaviour / failure paths /
acceptance criteria (AC-1..n) / evidence per criterion / rollback
## Rules
- Every empty field stays `{to-be-filled}`. Never invent a requirement.
- Assumptions go in "Open questions", not into the body as fact.
- Acceptance criteria describe behaviour, never file names.
See [reference.md](reference.md) for the filled refund example.
The fields worth knowing for spec work:
| Field | What it does | Why it matters for a spec skill |
|---|---|---|
description | Tells the agent what the skill does and when to use it. This is what automatic invocation is decided from. | The highest-leverage line in the file. Write the trigger conditions, not a summary — "use when scope or failure paths are undecided" fires; "helps with specs" does not. |
name | Display label in listings. For personal and project skills the command comes from the directory name, not this field. | Renaming the folder renames the command. Renaming this field does not. |
when_to_use | Extra invocation context, appended to the description in the listing. | Room for the negative cases: when the ticket is already specified, skip. |
allowed-tools | Tools pre-approved for the turn that invokes the skill. The grant clears on the next user message. | A drafting skill needs to read the repo, not write to it. Read, Grep and Glob are usually the whole list. |
disable-model-invocation | Set true and only a person can run it, by name. The description stays out of context entirely. | Correct for anything with side effects — a skill that commits, deploys, or files a ticket should never fire on its own reading of the room. |
paths | Glob patterns that gate automatic activation to matching files. | Scope an API-contract skill to openapi/** so it stays quiet during unrelated work. |
Six of these fields travel: name, description, license, compatibility, metadata and allowed-tools are part of the open Agent Skills specification. The rest are Claude Code extensions. If a skill is meant to be shared outside one tool, keep it to the six.
Where skills live, and which one wins
Four locations, and they override each other in a fixed order. This matters the first time a personal skill quietly shadows the project one your team agreed on.
| Location | Path | Scope | Precedence |
|---|---|---|---|
| Enterprise | Managed settings directory | Every user in the organisation | Highest |
| Personal | ~/.claude/skills/<name>/SKILL.md | All of your projects | Beats project |
| Project | .claude/skills/<name>/SKILL.md | This repository | Beats plugin |
| Plugin | <plugin>/skills/<name>/SKILL.md | Wherever the plugin is enabled | Lowest, namespaced plugin:skill |
Two more rules with practical consequences. A .claude/skills/ directory in a subproject loads under its own qualified name (/apps/web:review), so a monorepo can ship one spec skill per package without collisions. And SKILL.md should stay under about 500 lines — detail belongs in sibling files linked from it, which are read only when the agent needs them. That last property is the reason a skill beats a long CLAUDE.md for reference material: the filled example costs nothing until someone asks for it.
Skill, CLAUDE.md, slash command, or subagent?
All four can hold spec instructions. They differ in when the content loads and what it costs, which is the only question that decides where a spec belongs.
| Mechanism | Loads | Put this there |
|---|---|---|
CLAUDE.md | Every session, every turn | Facts true for all work in the repo: the stack, the commit convention, the test command. Not a procedure. |
| Skill | On demand, by name or by matching the description | The spec template, the review checklist, the ticket-to-spec procedure. Anything you would otherwise paste. |
| Slash command | Only when a person types it | A short one-file prompt with no supporting material. Skills win a name clash. |
| Subagent | In its own forked context | Work whose intermediate output you do not want in the main thread — a wide review pass, for instance. A skill can run this way with context: fork. |
The rule of thumb that follows: if you have pasted the same instructions twice, that is a skill. If it is a fact rather than a procedure, it belongs in CLAUDE.md. One caveat on scale — the skill listing gets a budget of roughly one percent of the context window, and when descriptions overflow it the least-used ones are dropped first. Thirty half-considered skills degrade the ones you rely on.
Worked example: a spec template that stops being copy-paste
The Claude Code spec template on this site is written to be pasted at the start of a run. That works, right up until someone forgets. Moving the same content into a skill changes the failure mode: the agent loads it because the request matched, not because a person remembered.
.claude/skills/spec-packet/ ├── SKILL.md the procedure and the rules (keep it short) ├── reference.md the filled refund example, loaded on demand └── criteria.md the acceptance-criteria patterns Committed to the repo, so every reviewer gets the same procedure and changes to it show up in a pull request.
Three things are worth getting right when you do this. Write the description as trigger conditions, because that string is the only thing standing between a skill and never being used. Keep allowed-tools to reads, so a drafting skill cannot start editing the repository it is describing. And put the long filled example in a sibling file rather than in SKILL.md — it is the part you want available and the part you do not want resident in context all day.
What does not change: a skill drafts, a person still approves. The boundaries below are the same whether the procedure arrives by paste or by frontmatter.
Walkthrough: one vague ticket through the skill
The folder above is the mechanism. This is what it should produce, traced through an illustrative ticket. Because the rules in SKILL.md keep empty fields as {to-be-filled} and send assumptions to "Open questions", the skill's first useful output is a list of questions, not a draft. Quote the ticket verbatim at the top of the spec, so reviewers can see what was requested and what was inferred.
ticket.md (quoted as received) "Customers can't cancel subscriptions — need to add cancellation flow with retention offer. Support is drowning in refund requests. Legal also wants a paper trail. Let's get this shipped this sprint."
Four sentences, and no definition of "cancel", no success metric, no acceptance criteria. Each gap becomes a question with an owner:
| Gap in the ticket | Question the skill should return | Owner |
|---|---|---|
| What "cancel" means | Immediate loss of access, or end of the billing cycle with no renewal? If end of cycle: write access, read-only, or a grace period? | Product |
| Retention offer | A discount, a pause, a downgrade, or several? Who owns the offer rules? | Product |
| Refunds | Prorated refunds on immediate cancel? Who approves the refund logic? | Finance |
| What a cancelled account still touches | What happens to active API keys, scheduled exports and team seats? | Engineering |
| Support path | Self-service only, or does support need a manual override for edge cases? | Support |
| "Paper trail" | Signed confirmation, emailed receipt, immutable audit log, or all three? | Legal |
| Success and rollback | Which metric shows it worked, and what is the rollback if it starts issuing bad refunds? | Product, engineering |
Once owners answer, the draft fills slots instead of interpreting prose. With an illustrative set of answers, the parts reviewers mark up look like this:
Decisions (owner-approved)
- Cancel = end of billing cycle, no renewal, 7-day grace window
- Retention offer = one offer: 30% off for the next 3 billing cycles
- Non-goals: plan downgrades, seat reassignment, reactivation
- Paper trail = signed confirmation + immutable audit row
AC-1 Given an active paying customer with more than 7 days left in the cycle
When they confirm cancellation and decline the retention offer
Then access stays active until the billing period end date
And no further invoices are generated
And an audit row is written with the confirmation timestamp
AC-2 Given a customer accepts the retention offer
When the acceptance is confirmed
Then 30% off applies to the next 3 billing cycles
And offer_accepted_at is recorded
Risks (what breaks, which data, who is affected)
- Webhook consumers miss the new cancellation event if it is not allowlisted
- Billing cron double-processes a subscription cancelled and renewed in the same minute
- Concurrent audit writes collide with month-end finance exports
Open questions
- Q1 Limit retention offers to one per customer per 12 months?
Proposed by the draft, not in the ticket. Legal to decide.
The failure to watch for is added scope presented as core flow. A typical example is a win-back email sequence that appears in neither the ticket nor the answers. The rule "never invent a requirement" is there for exactly this: anything with no source moves to Open questions or out of the spec, and stays there until an owner accepts it. Q1 shows the right shape: a sensible idea, but still labelled as a proposal and given an owner.
If you plan in conversation rather than from a ticket, Matt Pocock's /to-spec skill does a version of this at the end of the chat: it records the decisions you made and checks the test seams before writing. The to-spec skill explained covers its template, when to skip it, and the acceptance-criteria section worth adding.
How this relates to Superpowers and SDD tools
A spec skill follows the same discipline visible in tools such as Superpowers: clarify the spec before planning, turn the plan into bounded work, use tests and review gates, and keep human approval separate from AI output. If you are comparing OpenSpec, Superpowers, and GitHub Spec Kit, start with the SDD patterns comparison, then decide which artifacts your team actually needs.
2. Inputs to Provide
- The original ticket or PRD excerpt.
- The template fields the output must follow.
- Known non-goals, dependencies, and owners.
- Existing API/schema snippets when contract behavior matters.
3. Outputs Worth Keeping
- A scoped spec draft with explicit open questions.
- Given/When/Then acceptance criteria.
- A risk register with owner, likelihood, impact, and mitigation.
- A reviewer checklist tied to release evidence.
4. Human Review Boundary
- A skill can draft; it should not approve scope.
- It can propose risks; owners still accept or reject them.
- It can summarize contract diffs; engineers still decide compatibility.
- It can produce test ideas; failing evidence still blocks release.
5. When Not to Use It
- When product ownership is unresolved.
- When the input contains secrets or regulated data.
- When the team wants approval without review.
- When the task is small enough for a short checklist.
6. Adoption Test
After two weeks, compare three signals: fewer clarification comments, clearer acceptance tests, and fewer PR review surprises. If those do not improve, narrow the workflow before adding more automation.
Ticket to Reviewable Spec
A strong spec skill starts with a bounded artifact and ends with something reviewers can mark up. The output should not be a polished essay. It should be a draft with decisions, assumptions, missing inputs, and tests.
Input: - Ticket: "Add bulk user disable for workspace admins" - Template: feature-spec.md - Required sections: goal, non-goals, roles, API behavior, audit log, rollback, acceptance criteria Expected skill output: - Spec draft with unresolved questions called out - 8-12 Given/When/Then acceptance criteria - Risk register for permission mistakes, partial failures, and audit gaps - Reviewer checklist for product, backend, QA, and support
Editorial note: the field reference above follows the Claude Code skills documentation and the open Agent Skills specification, both linked under References. The workflow patterns are how Spec Coding would use a skill inside a spec-first delivery process — adapt them to your team before adoption.
1. Prompt Boundaries
- Name the source material the skill may use.
- Forbid invented requirements and hidden implementation choices.
- Require every assumption to appear in an "open questions" list.
- Keep output in the template your team already reviews.
2. Reviewable Output
- Spec: goal, non-goals, decisions, API/data impact.
- Acceptance criteria: happy path, failure path, boundary path.
- Risk register: owner, mitigation, evidence, rollback trigger.
- Questions: items that block implementation until answered.
3. Team Controls
- Store approved prompts in the repository.
- Keep specs as Markdown so the tool can be replaced later.
- Require PR evidence for generated code.
- Log which prompt version produced the draft.
4. Adoption Decision
Adopt a spec skill only when it improves the artifact reviewers already need. If the team gets more text but not clearer decisions, the workflow is too broad. Narrow the task to one repeatable handoff and measure whether review comments become more specific.
The useful question is not whether the draft sounds good. It is whether another engineer can implement from it with fewer clarifying messages.
Adoption Checklist
Choose one workflow first: ticket to spec, API diff to review note, incident to postmortem seed, or acceptance criteria rewrite. Do not automate the whole delivery process on day one.
What to Measure After Two Weeks
Track whether specs need fewer clarification comments, whether QA can derive tests earlier, whether generated PRs include evidence, and whether reviewers find missing risks before implementation.
When to Pause
Pause adoption when outputs invent requirements, hide unresolved questions, bypass product/security review, or cannot be traced back to a prompt and source artifact.
Source Gate
Before running a workflow, list the exact source artifacts the skill may use: ticket URL, product note, existing spec, API schema, error table, or incident timeline. If a requirement is not in one of those sources, the output should label it as an assumption rather than presenting it as approved scope.
Output Gate
Before accepting the draft, check that every section maps to a reviewer action. Product should be able to approve scope, engineering should be able to inspect API or data behavior, QA should be able to derive tests, and support should see customer-visible failure states.
Release Gate
Before generated code ships, require evidence tied back to the spec: passing tests, API diff review, migration rollback notes, feature flag state, and the metric or alert that proves the workflow is healthy after deployment.
Is a skill a replacement for a technical spec?
No. It can draft and critique the spec, but the approved artifact still needs human ownership, version history, and test evidence.
What should the first workflow be?
Start with a narrow ticket-to-spec workflow. It has clear inputs, a visible output, and obvious review questions, so the team can judge quality quickly.
How do you keep output from becoming generic?
Require source references, explicit assumptions, concrete examples, and a rejection pass for vague words such as "fast", "robust", "simple", and "seamless".
Use a Spec Skill With a Spec Boundary
Pair a spec skill with a reusable template and a review checklist. That keeps AI output close to the decisions the team actually has to approve.
The field reference on this page follows the official documentation linked under References. The workflow patterns are Spec Coding's own editorial position, not a guarantee about any tool's behaviour. Use the patterns here as reusable review habits.
References
- Claude Code documentation: Skills — the frontmatter field reference, the location precedence order, and the comparisons with slash commands, subagents and
CLAUDE.mdused on this page. - Agent Skills specification — the six portable frontmatter fields, for skills meant to work outside one tool.
- AGENTS.md — the sibling convention for repository-level agent instructions, read from the nearest file in the directory tree.
- Superpowers — a skills-based spec-first pipeline, discussed above.
Field names verified against the linked documentation on 2026-09-08. External documentation changes; check the source before relying on a specific field.