Guide · Agent skill
How to use the Story Done agent skill (story-done)
Updated · written with AI from the project's own documentation and checked against our catalogue data
Story Done is an agent skill for Claude that closes a finished story. Instead of accepting a quick 'it's done', it checks each acceptance criterion against evidence in your project, reports any deviations from the design or architecture decisions, and changes the story's status only after you confirm. This guide explains what agent skills are, how to install story-done, how to trigger it with a natural request, and what it needs to work well.
Story DoneDonchitos/Claude-Code-Game-Studios · MIT Download the skill Quick start
- 1Download the ZIP. Download the story-done ZIP from this page to your computer.
- 2Unzip into a skills folder. Unzip into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. Alternatively, upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 3Confirm your project has the needed structure. Check that you have a Bash shell, Git, and story files under production/epics/ with GDD and ADR documents in their expected folders.
- 4Finish a story and ask for close-out. When a story's work is done, say so in plain words, or run /story-done with the story path.
- 5Answer the criterion questions. For behaviour, feel and performance criteria, choose Yes, No or Not tested yet for each one the agent asks about.
- 6Review the verdict and approve. Read the report and traceability table, then say yes only if you agree the story is Complete.
What is an agent skill and what does story-done do?
An agent skill is a folder with a SKILL.md file that gives the agent a specific, repeatable procedure to follow when a matching request comes in. The agent loads the procedure only when it is needed.
Story-done's job is the close-out of one story. The skill works through a checklist: it reads the story and its acceptance criteria, looks for evidence for each criterion in files, tests and design documents, and lists any deviations from the design or scope. It writes its findings into the story file and marks the story Complete only after you agree.
- Verifies each acceptance criterion and records it as covered, untested or deferred.
- Checks for design or ADR deviations and scope problems, reported as facts.
- Updates the story's Status and Last Updated fields and adds a Completion Notes section, after your yes.
- Writes a checkpoint at the end of every run, whatever the verdict.
Install the story-done skill
There are two ways to install it. Download the story-done ZIP from this page, then either unzip it into your user skills folder or into a project's skills folder.
For a single user across projects, unzip into ~/.claude/skills/. For one project only, unzip into that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- User-wide: ~/.claude/skills/
- Single project: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check what the skill needs before you run it
Story-done is built for a specific project structure. It needs a Bash shell for the helper scripts in .claude/scripts and .claude/hooks, and Git, because it runs a git status check. Your story files, GDD and ADR documents must be in the folders the skill expects.
It runs helper scripts but does not use the network. The skill's allowed tools are limited to reading and searching files, writing and editing files, asking you questions, and a fixed set of script and git commands.
- Bash shell available for .claude/scripts and .claude/hooks helpers
- Git installed, for the git status --porcelain check
- Story files under production/epics/, GDD files under design/gdd/, ADRs in docs/architecture/
- Runs scripts: yes. Uses network: no.
How to trigger the skill with a natural request
Tell the agent that a story is finished, done or ready to close, for example 'Story 003 is done, close it out'. The skill's description is written around these phrases. You can also invoke it directly as /story-done, optionally followed by a story file path and a review mode.
If you name no story, the skill first looks at the Current task line in the session checkpoint. If that names no story, it lists stories marked IN_REVIEW or IN_PROGRESS and asks you to pick one.
- 'The login story is done, can we close it?'
- 'Story 004 is finished, check the acceptance criteria.'
- 'Close the inventory story, it's ready.'
- Direct form: /story-done path/to/story.md --review lean
/story-done [story-file-path] [--review full|lean|solo]What happens during a run
The skill runs in phases. It first finds the story and reads its facts and settings. It then decides how much reference material to load, based on the project's configured workflow tier. It verifies each criterion, checks test evidence and the run result, looks for deviations and scope issues, and runs review gates when the review mode is full.
Criteria are checked in different ways. A file or test file that a criterion names can be confirmed by looking. Behaviour, feel and performance criteria are asked to you one at a time, with options Yes, No or Not tested yet. A criterion about something visible needs a retained screenshot that the skill has opened. Anything that needs a full playtest is marked DEFERRED and does not block the close.
- Covered: a test exists under the test root, you confirmed it passes, or a screenshot shows it.
- Untested: no evidence yet. It blocks or is advisory depending on the QA level.
- Deferred: requires a playtest session. It does not block.
- The skill never marks a behaviour criterion passed from reading code alone.
What the skill writes, and what you approve
Nothing is changed until you say yes to the close. After approval, story-done updates the story file's Status, Last Updated and Completion Notes, and the story's entry in production/sprint-status.yaml. It writes to docs/tech-debt-register.md only if you pick that option during the run.
Review the verdict and the traceability table before you agree. The skill is designed for review, not blind sign-off.
- Story file: Status, Last Updated, Completion Notes section
- production/sprint-status.yaml: the story's entry
- docs/tech-debt-register.md: only when you choose that option
- Session checkpoint: written every run
What people use it for
- Closing a combat or inventory story in a game studio project, with each criterion traced to a unit test or screenshot.
- Getting a traceable record of which acceptance criteria were verified and which remain untested before a sprint review.
- Spotting drift between a story's implementation and the GDD or ADR it references before the story is marked Complete.
- Flagging a playtest-only criterion as DEFERRED so it is tracked without blocking the close.
Frequently asked questions
Is the story-done skill free to use?
The skill is published under the MIT licence, as listed on this page. Check the licence file in the source repository for the full terms before you reuse or change it.
What do I need to install story-done?
Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps. You also need a Bash shell and Git.
Does story-done work on any project?
No. It depends on the Claude Code Game Studios style structure: stories under production/epics/, GDD files under design/gdd/, ADRs, and the helper scripts in .claude/scripts and .claude/hooks. Without them it will fail or stop early.
Will story-done mark my story as complete automatically?
No. It only sets the story to Complete after you agree at the end of the run. It can also write to the tech debt register if you choose that option, so review its output first.
Why does the skill say a criterion is untested even though the code looks right?
The skill does not run tests and cannot judge how the game behaves or feels from reading code. A test file being present is reported as test file present, not as passing, so you need to run the tests or play the build to confirm.
What do I do if it says no stories were found?
That message means production/epics/ holds no story file. Run /create-stories with an epic slug to create them, and at the standard and full levels run /create-epics first if there is no epic yet.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Story-done suits game teams using the Claude Code Game Studios structure who want an evidence-based, traceable close-out of each story. It is a poor fit for projects without that story, epic and script layout, or for teams that want automatic sign-off or cannot rely on manual playtesting for feel and behaviour criteria.
Download the skill