user-story

Create user stories with Mike Cohn format and Gherkin acceptance criteria. Use when turning user needs into development-ready work with clear outcomes and testable conditions.

Quality

69%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/sdlc/skills/user-story/SKILL.md

Quality

Content

56%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill provides a well-structured workflow for creating user stories with good examples and quality checks at each step. However, it is significantly over-verbose, spending many tokens explaining concepts Claude already knows (what user stories are, why Gherkin works, anti-patterns of story writing). The referenced bundle files (template.md, examples/sample.md, scripts/) don't exist, undermining the progressive disclosure structure.

Suggestions

Cut 'Key Concepts' section drastically—remove 'Why This Structure Works,' 'Anti-Patterns,' and 'When to/NOT to Use This' subsections, as Claude already understands these frameworks and the frontmatter description covers when to use the skill.

Consolidate the 5 'Common Pitfalls' into a brief checklist (5 bullet points max) rather than giving each its own subsection with Symptom/Consequence/Fix structure.

Provide the referenced bundle files (template.md, examples/sample.md, scripts/user-story-template.py) or remove references to them to avoid broken navigation.

Move the detailed quality checks and red flags into a separate CHECKLIST.md file to keep the main SKILL.md as a concise overview with workflow steps.

Dimension	Reasoning	Score
Conciseness	Significantly verbose. Sections like 'Why This Structure Works,' 'Anti-Patterns,' 'When to Use This,' and 'When NOT to Use This' explain concepts Claude already understands well. The 'Key Concepts' section extensively explains the Mike Cohn format and Gherkin, which are well-known frameworks Claude doesn't need taught. The five common pitfalls section is largely redundant with the quality checks already embedded in Steps 2-3. The file is ~200+ lines when it could be ~80.	2 / 5
Actionability	The step-by-step process with concrete templates and fill-in-the-blank markdown is actionable. The quality checks and good/bad examples provide clear guidance. However, the helper script references a file that doesn't exist in the bundle, and the template.md reference is unverifiable. The guidance is mostly concrete but relies on external files that aren't provided.	4 / 5
Workflow Clarity	Clear 5-step sequence (Gather Context → Write Use Case → Write Acceptance Criteria → Add Summary → Validate and Refine) with quality checks at each step. Step 5 includes validation. However, this is not a destructive/batch operation so the feedback loop cap doesn't apply. Minor gap: the validation step is somewhat vague ('read aloud to the team') rather than providing concrete verification criteria.	4 / 5
Progressive Disclosure	References to external files (template.md, examples/sample.md, scripts/user-story-template.py, related skills) are well-signaled, but none of these files exist in the bundle. The SKILL.md itself inlines a lot of content that could be in separate files (anti-patterns, pitfalls, key concepts). The references section is well-organized but the overall file is too long for what should be an overview.	3 / 5
	Total	13 / 20 Passed

Description

82%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This is a well-crafted description that clearly communicates both purpose and trigger conditions. Its main strength is the explicit 'Use when' clause and distinctive methodology references (Mike Cohn, Gherkin). The primary weakness is that the 'what' could be more specific about the range of actions performed and could include additional trigger synonyms.

Suggestions

Expand the capability list with more specific actions, e.g., 'Create user stories, define acceptance criteria, split epics into stories' to improve specificity.

Add common synonyms and related terms like 'agile', 'backlog items', 'BDD', 'Given/When/Then' to improve trigger term coverage.

Dimension	Reasoning	Score
Specificity	Names the domain (user stories) and mentions two concrete formats (Mike Cohn format, Gherkin acceptance criteria), but doesn't elaborate on what specific actions are performed beyond 'create'. Missing details like prioritization, splitting stories, or generating examples.	3 / 5
Completeness	Clearly answers both 'what' (create user stories with Mike Cohn format and Gherkin acceptance criteria) and 'when' (when turning user needs into development-ready work with clear outcomes and testable conditions). The 'Use when' clause is explicit and contains concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes strong natural trigger terms like 'user stories', 'acceptance criteria', 'Gherkin', 'Mike Cohn', 'development-ready', and 'testable conditions'. Missing some common synonyms like 'agile', 'backlog', 'BDD', 'Given/When/Then', 'requirements', or 'tickets'.	4 / 5
Distinctiveness Conflict Risk	Highly distinctive with specific methodology references (Mike Cohn format, Gherkin). The combination of user story creation with specific formats creates a clear niche that is unlikely to conflict with other skills like general requirements gathering or project management.	5 / 5
	Total	17 / 20 Passed

Validation

90%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: whimzyLive/nightshift-ai
Path: plugins/sdlc/skills/user-story/SKILL.md
Commit: 7741177

Reviewed: 9 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.