agentleFS
veep2012veep2012/doc_mcp/.agents/skills/story-guardian/SKILL.md

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.

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
  1. Distinctive:

    Use this skill whenever work involves creating, refining, or reviewing stories for initiatives, parent stories, or numbered sub-stories.

    line 10
  2. Distinctive:

    Use for any of the following:

    line 22
  3. Very specific:

    If the story content is stored in documentation/, also apply:

    line 42
  4. Distinctive:

    Before drafting or updating a story, read the minimal set of repository docs that describe the feature, workflow, or subsystem in scope.

    line 48
  5. Distinctive:

    Use only the docs that materially affect the story.

    line 49
  6. Distinctive:

    If the story covers setup, runtime behavior, troubleshooting, or test flow, include the canonical docs for those areas in the reading list.

    line 50
  7. Distinctive:

    Keep descriptions focused on outcome and scope, not implementation tasks.

    line 57
  8. Very specific:

    Use Acceptance Criteria for story-specific validation.

    line 58
  9. Very specific:

    Use Definition of Done for short reusable completion gates.

    line 59
  10. Distinctive:

    Prefer simple business language over technical detail unless the user asks for more detail.

    line 62
  11. Distinctive:

    Avoid embedding long task lists into the description.

    line 63
  12. Distinctive:

    Keep requirements or architecture detail in linked documents when the story becomes too dense.

    line 64

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Story Guardian

Overview

Use this skill whenever work involves creating, refining, or reviewing stories for initiatives, parent stories, or numbered sub-stories.

Core rule:

  1. Story content must follow documentation/_story_template.md.
  2. Story wording must stay concise and outcome-focused.
  3. Parent stories must remain broad; detailed delivery belongs in numbered sub-stories.
  4. Stage-based technical stories should use the technical implementation-story template.
  5. Acceptance criteria must stay story-specific.
  6. 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.md
    • documentation/_documentation_standards.md
    • documentation/_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 Criteria for story-specific validation.
  • Use Definition of Done for 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.