write-requirements

Generates requirements documentation (user stories, acceptance criteria, out-of-scope) for a feature in an AI-native MVP project. Invoke before any implementation of a new feature begins — a feature without requirements documentation should not be built. If the developer mentions wanting to add or implement something new, trigger this skill before any code is written.

Quality

83%

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

Quality

Content

78%Weight 40%Scale 1-5

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

The content is highly actionable with concrete, executable templates for all three deliverables and a clear workflow with a verification step. Its main weakness is progressive disclosure: substantial template and guidance detail is inlined in SKILL.md rather than split into bundled reference files, which would ease navigation and token cost.

Suggestions

Move the three per-document markdown format templates into bundled reference files (e.g. references/templates/user-stories.md) and link to them from SKILL.md so the main file stays a concise overview.

Strengthen the output verification step into an explicit feedback loop — list the checks to run, state that on failure you fix and re-verify before finalizing, mirroring a validate→fix→retry pattern.

Tighten a few explanatory asides (e.g. "Subjectivity is the enemy here", "a vague story produces a vague implementation") into terse rules so the body leans more on instruction than rationale.

Dimension	Reasoning	Score
Conciseness	The body is largely efficient and assumes Claude's competence, giving formats and rules without explaining what a user story or acceptance criterion is; a few explanatory sentences (e.g. "Subjectivity is the enemy here") are helpful framing but could be trimmed, keeping it just below the lean score-5 anchor.	4 / 5
Actionability	It provides concrete, copy-paste-ready file templates for all three documents with explicit markdown formats, naming rules, TODO markers, and concrete output paths, covering the common cases fully.	5 / 5
Workflow Clarity	The sequence is clear — identify/confirm the feature name, locate inputs, write the three files, then verify — and it includes an explicit pre-write verification checklist, but the verification step is framed as a self-check rather than an enforceable validate→fix→retry feedback loop with an explicit re-run on failure.	4 / 5
Progressive Disclosure	The body is well sectioned, but it inlines full per-document format templates and detailed guidance that arguably belong in separate reference files, and it points to external inputs (docs/functional/glossary.md, docs/constitution.md) rather than to its own bundled references; no references/scripts/assets bundle exists to delegate the bulk into.	3 / 5
	Total	16 / 20 Passed

Description

87%Weight 40%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.

The description is strong: it states concrete deliverables, an explicit trigger, and a clearly bounded niche tied to pre-implementation gating. It is slightly below the top anchor on specificity and trigger breadth because it does not enumerate per-document actions or a wide range of synonyms, and the second-person/developer-facing phrasing is acceptable here since the skill operates on developer intent.

Dimension	Reasoning	Score
Specificity	Names several concrete outputs ("user stories, acceptance criteria, out-of-scope") and the domain ("requirements documentation for a feature in an AI-native MVP project"), which is solid coverage though it does not enumerate the distinct sub-actions per document the way the score-5 anchor does.	4 / 5
Completeness	It explicitly answers both what ("Generates requirements documentation ... user stories, acceptance criteria, out-of-scope") and when ("Invoke before any implementation of a new feature begins", "If the developer mentions wanting to add or implement something new, trigger this skill before any code is written") with concrete trigger phrases.	5 / 5
Trigger Term Quality	Natural trigger phrasing is present ("If the developer mentions wanting to add or implement something new"), and it captures the common way a user would surface the need, but it leans on "requirements documentation" / "feature" rather than a broad spread of synonyms and file/term variations the score-5 anchor expects.	4 / 5
Distinctiveness Conflict Risk	The niche is sharply defined — pre-implementation requirements generation for AI-native MVP features — with a distinctive trigger condition ("a feature without requirements documentation should not be built"), making overlap with unrelated skills minimal.	5 / 5
	Total	18 / 20 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: Simonvm9114/flag-feedback
Path: .claude/skills/write-requirements/SKILL.md
Commit: c5bcbb3

Reviewed: 1 day 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.