Skip to content
Get packs

Guide · Agent skill

How to use the Story Readiness Checker agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The Story Readiness Checker is an agent skill for Claude Code that reviews game development story files and reports whether each one has what a developer needs before writing code. This guide is for producers, leads and solo developers using the Claude Code Game Studios template, and it explains what the skill does, how to install it, how to trigger it and how to read its verdicts. By the end you will be able to run a readiness check on one story, an epic or a whole sprint.

Story Readiness CheckerDonchitos/Claude-Code-Game-Studios · MIT

Quick start

  1. 1Download the ZIP. Get the story-readiness ZIP from this skill's page in the directory.
  2. 2Unzip into a skills folder. Extract it to ~/.claude/skills/ for all projects, or to the project's .claude/skills/ folder for one project.
  3. 3Confirm the template files exist. Check that .claude/scripts/story-facts.sh, .claude/scripts/adr-status.sh and .claude/hooks/yaml-helper.sh are present in your project.
  4. 4Ask for a readiness check. Say in plain language that you want to know whether a story, an epic or the sprint's stories are ready to build.
  5. 5Read the verdicts. Review each story's BLOCKED, NEEDS WORK, NOT ASSESSED or READY verdict and its listed gaps.
  6. 6Fix and re-run. Apply the suggested fixes yourself, then ask for the check again to confirm the result.

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file that tells a compatible agent how to perform a specific task. When a request matches the skill's description, the agent follows its instructions. The skill is named story-readiness.

The skill checks each story for clear acceptance criteria, no unresolved design questions, a valid architecture decision record (ADR) and finished dependencies. It gives each story one verdict: BLOCKED, NEEDS WORK, NOT ASSESSED or READY, along with a list of gaps and suggested fixes.

  • BLOCKED: a finding you can clear, such as a referenced ADR that is Proposed, Deprecated or Superseded, or a dependency that is missing or in Draft.
  • NEEDS WORK: a blocking checklist item fails and the story can be fixed now.
  • NOT ASSESSED: the story could not be evaluated, for example because the file is unreadable or a referenced ADR has no readable status. It is never reported as READY.
  • READY: every item passes, is not applicable with a reason, or is advisory. Advisory gaps are still listed.

Install the skill from a ZIP file

Download the ZIP from the skill's page in this directory and unzip it. You can install it for yourself or for one project.

For all your projects, unzip the folder into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. Either way the result should be a story-readiness folder containing SKILL.md.

If you use the Claude apps instead of Claude Code, open Settings, go to Capabilities, then Skills, and upload the skill there.

  • Personal install: ~/.claude/skills/story-readiness/
  • Project install: .claude/skills/story-readiness/ inside your project

Check the requirements before you run it

The skill is built for the Claude Code Game Studios template. Most of its checks read files from that template's folder layout, so a project without these files will get reports of missing items rather than useful verdicts.

The skill runs its checks with scripts through bash, so you need a bash shell. It also needs these template files: .claude/scripts/story-facts.sh, .claude/scripts/adr-status.sh and .claude/hooks/yaml-helper.sh. It reads documents such as docs/architecture/tr-registry.yaml and production/sprint-status.yaml.

The skill runs scripts. It does not use the network.

  • Claude Code or a compatible SKILL.md agent
  • A bash shell
  • Template files: .claude/scripts/story-facts.sh, .claude/scripts/adr-status.sh, .claude/hooks/yaml-helper.sh
  • Template documents such as docs/architecture/tr-registry.yaml and production/sprint-status.yaml

Trigger the skill with natural requests

You do not need to type a command. Ask in plain language whether a story, or the sprint's stories, are ready to start or build. The skill's description is written around that kind of request, so the agent will pick it up.

You can also name the scope. The skill's argument hint accepts a story file path, the word all for every story under production/epics/, or the word sprint for the current sprint. You can add --review full, --review lean or --review solo to set the review mode for that run.

  • "Are the stories in the current sprint ready to build?"
  • "Check whether production/epics/combat/story-003-dash.md is ready to start."
  • "Is every story in the inventory epic ready for implementation?"
  • "Run a readiness check on all stories before we start the sprint."

Read the report and act on the gaps

The report lists each story with its verdict. Under each verdict you will see the failing items, each with a suggested fix. Fixes are written as actions, such as accepting a Proposed ADR or pointing a story at its successor ADR.

The skill is read-only. It does not edit your story files. If you want help, it can draft fixes in the chat, and you apply them yourself. Work through BLOCKED stories first, because a known blocker is more useful than an unknown one.

  • Fix BLOCKED items before NEEDS WORK items.
  • Treat NOT ASSESSED as a prompt to check the named file or ADR, not as a pass.
  • Re-run the check after you change a story to confirm its verdict.

Safety notes: scripts and files

The skill runs bash scripts from your project, including story-facts.sh and adr-status.sh. Read those scripts before you install the skill in a project you do not fully trust, since the agent will run them when you ask for a check.

The skill reads story files, ADRs and registries, and it is written not to edit them. It makes no network calls.

  • Scripts run locally through bash, so review them first.
  • No network access is used.
  • The skill does not write or edit files.

Tips for better results

Keep your story files, ADRs, TR registry and sprint plan in the folder layout the template expects. The more of these files exist, the more items the skill can actually check.

The skill checks documentation completeness. It does not tell you whether the code works, so keep your normal testing and sign-off steps.

  • Run the check on a whole sprint before the sprint starts, not only on single stories.
  • Use the epic option when you are reviewing one feature area.
  • Keep ADR status fields filled in, since a missing status is reported as a malformed ADR.

What people use it for

  • A solo developer checks that each story in the current sprint has acceptance criteria and finished dependencies before starting work.
  • A producer gets a quick readiness report across every story in one epic before assigning tasks.
  • A lead finds stories that cite a Proposed or Superseded ADR and sends them back for an architecture decision.
  • A team checks stories at the start of a sprint and fixes open design questions before any code is written.

Frequently asked questions

Is the Story Readiness Checker free to use?

The source for this skill is published under the MIT licence, which this page lists. Check the licence file in the repository for the full terms before you reuse or redistribute it.

What do I need to install the story-readiness skill?

You need Claude Code or a compatible SKILL.md agent and a bash shell. The skill also needs the Claude Code Game Studios template files, including the scripts in .claude/scripts/ and .claude/hooks/.

Where do I put the story-readiness folder?

Put it in ~/.claude/skills/ to use it across projects, or in a project's .claude/skills/ folder to use it in that project only. In the Claude apps, upload it under Settings, Capabilities, Skills.

Does the skill edit my story files?

No. It is read-only. It reports verdicts and gaps and can draft fixes in the chat, but you make the changes yourself.

Why does the skill say my stories are NOT ASSESSED?

This usually means the story file is unreadable, a referenced ADR has no readable status, or a design document the story names cannot be found. The report names what could not be read, so check that file first.

Can it check projects that don't use the Game Studios template?

It is not intended for that. Most checks depend on the template's story files, ADRs and sprint status YAML, so other projects will get reports of missing items. It also checks documentation completeness, not whether code works.

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

Use this skill if you run game projects on the Claude Code Game Studios template and want a consistent readiness check on stories before anyone writes code. Pick something else if your project does not use that folder layout or story and ADR conventions, or if you need final quality sign-off, since this checks documentation rather than working code.

Download the skill