What is using-stories?

A quick reference for a project workflow where stories are work items managed through a command-line tool and completed only after evidence and review checks.

Use it when working in projects that contain the specified story-workflow configuration and need guidance on its story commands.

It helps contributors follow the project's rules for claiming, parking, completing, and recording discovered work.

using-stories — Skill for Claude Code and Codex by shousper/claude-kit

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Any agent

npx skills add shousper/claude-kit --skill using-stories

Clone the repo

git clone --depth 1 https://github.com/shousper/claude-kit

Made for: Claude Code, Codex.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/skills/shousper/claude-kit/using-stories/github.svg)](https://agentmods.dev/skills/shousper/claude-kit/using-stories)

Your own site

<a href="https://agentmods.dev/skills/shousper/claude-kit/using-stories"><img src="https://agentmods.dev/badge/skills/shousper/claude-kit/using-stories/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/skills/shousper/claude-kit/using-stories"><img src="https://agentmods.dev/badge/skills/shousper/claude-kit/using-stories.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 109 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.

When invoked 896 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00109	$0.00896
Opus 5.5	$0.00044	$0.00358
Sonnet 5.5	$0.00022	$0.00179
Haiku 4.5	$0.00011	$0.00090

Measured 1mo ago against content hash b3cd5007543c, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

using-stories scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 1mo ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

shared/stories/skills/using-stories/SKILL.md · 42 lines

How it starts

The opening of the file, as written. The whole thing — 42 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Using Stories

This project runs the story workflow. The board is stories/*.md; the story CLI is the ONLY way to change it.

Rules

Never hand-edit board or loop files (stories/** and everything under .agents/shousper-stories/local/: execution state, loop files, learnings, evidence). Every mutation is a story command — a hook denies direct writes and names the command to run instead. Do not route around it with the shell. Story loops are per-session: a loop only ever re-prompts the session that started it.
done is evidence- and plan-gated. story done refuses a story with no ## Implementation Plan on record (<10 words = thin), runs command gates, and checks review verdicts itself. Never declare a story complete — the CLI decides.
Ready is computed, never stored. Trust story ready, not file contents or memory.
Park, don't stall. Human-only decision → story park <id> --question "…", take the next story. Parked questions surface at run end — never bury them. While a loop is bound to your session the ask-the-user tool is denied: a question is a park.
Discovered work is filed, not done. story create --title "…" --description "…" --ac "…" --discovered-from <id>, then back to the claimed story. The CLI refuses a story without a description and at least one acceptance criterion — write the spec at filing time, never "fill it in later".
One worktree per story. Claimed work lives in .worktrees/st-<id> on branch story/st-<id>. Commit there; never merge to main yourself — integration is the CLI's job.
Budgets are visible and final. The loop shows iteration N · stalls a/b at each turn end; a run ends after b consecutive turn ends without board progress. Never restart a stopped loop or edit loop state; a human decides.

CLI quick reference

story ready --json                 # claim-safe workable set; feedback items first
story claim <id>                   # claim + create worktree
story show <id> | story board      # read views
story update <id> --… [--complexity hard|frontier]   # field changes (legal transitions only); absent = routine
story note <id> --body "…"         # append an implementation note
story create --title "…" --description "…" --ac "…" [--ac "…"] --type <t> [--complexity hard|frontier] [--discovered-from <id>] [--depends-on …] [--touches …]   # or --body-file <path>
story park <id> --question "…"     # blocked on a human
story record <id> --gate <g> --verdict pass|fail --evidence <path>
story done <id> [--allow-empty] [--allow-unplanned]   # gates → plan check → evidence → integrate
story loop status | story loop stop
story doctor [--fix]               # board integrity + adoption of hand-written stories (+ layout migration)

Read the full file on GitHub · 42 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

1mo ago Changed · +4 tokens per session b3cd5007543c
1mo ago First seen · 42 lines · 105 tokens per session scan A d5e233969765

Subscribe to this mod's changes

using-stories is a skill published in the GitHub repository shousper/claude-kit (4 stars, last pushed 1mo ago), licensed MIT. It adds 109 tokens to every session and 896 once invoked, about $0.0004 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Project management

story-readiness

Checks whether a story is ready to implement: clear acceptance criteria, no open questions, valid ADR and dependencies. Use when the user asks if a story, or the sprint's stories, are ready to start or build.

Donchitos/Claude-Code-Game-Studios · 48 tokens

recipe-create-meet-space

Create a Google Meet meeting space and share the join link.

googleworkspace/cli · 18 tokens

workthreads

SpecStory Workthreads - a weekly work-thread rollup across a team's repos from SpecStory coding histories (any agent - Claude Code, Codex, Cursor, Gemini, and more). It groups the window's sessions into threads of work per project and labels each new / open / recently closed, so a lead sees what shipped, what is still…

specstoryai/getspecstory · 126 tokens

atmos-config

Atmos root configuration: atmos.yaml discovery, precedence, deep merging, basepath, imports, minimal bootstrap, and routing to narrower Atmos skills.

cloudposse/atmos · 31 tokens

projects

List all managed projects with status, branch, open PRs, and open issue counts — portfolio-level view.

me2resh/apexyard · 24 tokens

qa-project-bootstrap

Onboard a new QA engineer to an existing codebase, or audit an existing test architecture. Produces a 30-day ramp plan: codebase orientation, framework walkthrough, test architecture audit, mentorship pairing, and first-test guidance. Use when: "QA onboarding," "new tester," "ramp up," "test architecture audit,"…

petrkindlmann/qa-skills · 124 tokens