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.
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.