story-guardian
Skill0 starsChanged 3 months agoMITView on GitHub
Standardize story creation, refinement, and review against `documentation/_story_template.md`. Use when creating or updating parent stories, numbered sub-stories, acceptance criteria, or definitions of done.
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- backend-doc-syncSkill
- check-documentation-gapsSkill
- check-test-gapsSkill
- commiterSkill
- docs-guardianSkill
- monthly-doc-actualizerSkill
- release-note-writerSkill
- story-checkSkill
- story-updateSkill
- tech-debtSkill
- test-scenario-guardianSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 9 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Use this skill whenever work involves creating, refining, or reviewing stories for initiatives, parent stories, or numbered sub-stories.
- Distinctive: line 22
Use for any of the following:
- Very specific: line 42
If the story content is stored in documentation/, also apply:
- Distinctive: line 48
Before drafting or updating a story, read the minimal set of repository docs that describe the feature, workflow, or subsystem in scope.
- Distinctive: line 49
Use only the docs that materially affect the story.
- Distinctive: line 50
If the story covers setup, runtime behavior, troubleshooting, or test flow, include the canonical docs for those areas in the reading list.
- Distinctive: line 57
Keep descriptions focused on outcome and scope, not implementation tasks.
- Very specific: line 58
Use Acceptance Criteria for story-specific validation.
- Very specific: line 59
Use Definition of Done for short reusable completion gates.
- Distinctive: line 62
Prefer simple business language over technical detail unless the user asks for more detail.
- Distinctive: line 63
Avoid embedding long task lists into the description.
- Distinctive: line 64
Keep requirements or architecture detail in linked documents when the story becomes too dense.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Story Guardian
Overview
Use this skill whenever work involves creating, refining, or reviewing stories for initiatives, parent stories, or numbered sub-stories.
Core rule:
- Story content must follow
documentation/_story_template.md. - Story wording must stay concise and outcome-focused.
- Parent stories must remain broad; detailed delivery belongs in numbered sub-stories.
- Stage-based technical stories should use the technical implementation-story template.
- Acceptance criteria must stay story-specific.
- Definition of Done must stay short and reusable.
When To Use
Use for any of the following:
- Creating a new parent story.
- Creating a new numbered sub-story.
- Creating a stage-based technical implementation story.
- Refining story title or description.
- Writing or tightening acceptance criteria.
- Writing or tightening Definition of Done.
- Reviewing existing story text for consistency.
Workflow (Required)
Step 1: Classify the story work
Choose one:
- Parent story
- Sub-story
- Technical implementation story
- Story review
Step 2: Load the template and standards
- Read
documentation/_story_template.md. - If the story content is stored in
documentation/, also apply:documentation/_documentation_template.mddocumentation/_documentation_standards.mddocumentation/_documentation-index.md
Step 3: Pre-Development Reading
- Before drafting or updating a story, read the minimal set of repository docs that describe the feature, workflow, or subsystem in scope.
- Use only the docs that materially affect the story; do not load unrelated material.
- If the story covers setup, runtime behavior, troubleshooting, or test flow, include the canonical docs for those areas in the reading list.
- Record the selected docs in the story itself under
Pre-Development Reading.
Step 4: Apply structure rules
- Parent stories must contain a concise title and broad description.
- Sub-stories should use numbered titles such as
0. Define Requirements. - Technical implementation stories should use the stage-style template with description, context, problem, desired outcome, scope, proposed fix, acceptance criteria, test plan, documentation sync, and definition of done.
- Keep descriptions focused on outcome and scope, not implementation tasks.
- Use
Acceptance Criteriafor story-specific validation. - Use
Definition of Donefor short reusable completion gates.
Step 5: Tighten content
- Prefer simple business language over technical detail unless the user asks for more detail.
- Avoid embedding long task lists into the description.
- Keep requirements or architecture detail in linked documents when the story becomes too dense.
- Split stories when one story covers multiple independently deliverable outcomes.
- For technical implementation stories, keep the template general-purpose and stage-oriented rather than scheduler-specific.
Step 6: Report result
State one outcome:
- Compliant
- Updated to compliant
- Partially compliant (list exact gaps)
Output Requirements
Always report:
- Story type handled
- Template sections created or normalized
- Whether the story remains broad enough or should be split
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

