From skills
Defines where spec-driven working artifacts — the spec (e.g. `SPEC.md`), the plan, and the task list (e.g. `tasks/plan.md`, `tasks/todo.md`) — live on disk under `docs/specs/<id>-<slug>/`, and how those directories are numbered, scoped, and resolved so multiple specs can run in parallel without overwriting one another. Use this BEFORE creating, locating, or updating any spec, plan, or task/todo file: whenever a spec/plan/build workflow writes these artifacts, whenever you need to find the right feature directory to act on, when more than one spec or feature is in progress at once, or when a draft spec gets a tracker issue number assigned. Trigger even if only one spec exists and even if the user never mentions where the file should go. Governs only where artifacts live and how they are addressed, not what content goes in them.
How this skill is triggered — by the user, by Claude, or both
Slash command
/skills:artifact-anatomyThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Spec-driven workflows produce working artifacts — a spec, a plan, and a task list — that are living documents kept in version control as the shared source of truth between the human and the agent. This skill defines their on-disk layout, numbering namespace, and resolution rules so that several specs can be worked **in parallel**, each scoped to its own numbered feature directory, instead of ov...
Spec-driven workflows produce working artifacts — a spec, a plan, and a task list — that are living documents kept in version control as the shared source of truth between the human and the agent. This skill defines their on-disk layout, numbering namespace, and resolution rules so that several specs can be worked in parallel, each scoped to its own numbered feature directory, instead of overwriting a single global spec file at the repo root.
It governs the where and the naming. It does not govern the what: writing the spec content and breaking work into tasks are separate concerns handled by your spec and planning workflows.
Workflow-agnostic. Examples use the common
SPEC.md+tasks/plan.md+tasks/todo.mdartifact set, but the same layout applies to whatever spec/plan/task files your toolchain produces — substitute your own filenames.
When NOT to use: Deciding what content goes in the spec, plan, or task list. This skill only decides where artifacts live and how they are addressed.
One feature per numbered directory under docs/specs/. The directory contents are unchanged from a single-spec layout — same filenames, same content — only their location moves:
docs/specs/
142-payment-retry/
SPEC.md
tasks/
plan.md
todo.md
draft-search-revamp/
SPEC.md
tasks/
plan.md
todo.md
The artifact filenames keep their exact names and structure. The only new thing is the docs/specs/<id>-<slug>/ wrapper that scopes them to one feature.
The <id> prefix marks where the work is tracked, and the two forms are kept strictly separate so a glance at docs/specs/ is unambiguous:
142-payment-retry) — a real issue-tracker issue number. Reserved exclusively for issue numbers.draft- prefix (draft-search-revamp) — no issue yet; a local draft. Never give a local-only spec a bare number.When a draft later gets an issue number, rename the directory in one step:
git mv docs/specs/draft-search-revamp docs/specs/160-search-revamp
This keeps the guarantee that a bare number always maps to a tracker issue, while letting work start before any issue exists.
Resolve <id> in order, stopping at the first that applies:
#142 mentioned in context → use that number: docs/specs/142-payment-retry/.docs/specs/draft-<slug>/.Do not auto-detect the issue tracker (scanning branch names, running gh issue list). That is out of scope — rely on the supplied reference plus the single question.
docs/specs/<that>/.docs/specs/*/:
tasks/ if the project still uses one (see Backward compatibility)A root spec file (e.g. SPEC.md) with its tasks/ directory is treated as the single, unnumbered default feature. Projects that have only ever had one spec keep working with no change; the numbered docs/specs/<id>-<slug>/ layout is opt-in and only needed once a second spec enters progress.
| Rationalization | Reality |
|---|---|
| "There's only one spec, a root spec file is fine." | Today there's one. The moment a second spec starts, the root spec collides and one overwrites the other. The numbered directory costs nothing now and prevents the collision later. |
| "I'll just give the local spec a number, close enough." | Bare numbers are reserved for real issue numbers. A fake number breaks the one guarantee the namespace provides — that a number maps to a tracker issue. Use draft-. |
| "I can tell which feature they mean." | When multiple docs/specs/* directories exist, guessing risks editing the wrong feature's artifacts. List them and ask. |
| "I'll auto-detect the issue from the branch name." | Auto-detection is explicitly out of scope and adds fragile coupling. Ask the one question instead. |
tasks/ to the repo root while another spec is already in progressdocs/specs/3-foo/) that has no corresponding tracker issueAfter resolving artifact locations, confirm:
docs/specs/<id>-<slug>/ directorydraft-npx claudepluginhub shihyuho/skills --plugin skillsCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.