spec-writing

Execute this skill should be used when the user asks about "writing specs", "specs.md format", "how to write specifications", "sprint requirements", "testing configuration", "scope definition", or needs guidance on creating effective sprint specifications for agentic development. Use when appropriate context detected. Trigger with relevant phrases based on skill purpose.

Quality

75%

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/community/sprint/skills/spec-writing/SKILL.md

Quality

Content

77%Weight 40%Scale 1-3

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

The body is well-structured and highly actionable, with concrete paths, exact settings, and complete examples driving a clear multi-step workflow. Its main weaknesses are duplicated content between the inline Examples/Error Handling sections and the orphaned reference files, which hurts both conciseness and progressive disclosure.

Suggestions

Link references/examples.md and references/errors.md from the body (or move the inline Examples and Error Handling sections into those files and reference them) so the duplicated content lives in one place.

Trim or remove the Output section, since it restates results already produced by the numbered Instructions.

Add an explicit validation checkpoint (e.g. 'Before saving, confirm specs.md has a Goal, In/Out Scope, and Testing section') to make the workflow's completion check explicit rather than implied by the Output list.

Dimension	Reasoning	Score
Conciseness	The core Instructions are lean and assume Claude's competence, but the inline Examples and Error Handling sections duplicate content that already exists in references/examples.md and references/errors.md, and the Output section restates what the instructions produce, so it could be tightened rather than earning 'every token earns its place'.	2 / 3
Actionability	It gives concrete file paths (`.claude/sprint/[N]/specs.md`), exact configuration values (`QA: required \| optional \| skip`, `UI Testing Mode: automated \| manual`), explicit decision rules for when to use each, and two complete copy-paste-ready spec.md examples, satisfying the score-3 anchor for actionable instruction-only guidance.	3 / 3
Workflow Clarity	A clear 7-step sequenced process is paired with an explicit iterative feedback loop (step 7: review status.md, remove completed items, add new requirements) and a structured error-recovery table; because spec authoring is not a destructive or batch operation, the absence of a hard validation gate does not cap the score.	3 / 3
Progressive Disclosure	testing-configuration.md is well-signaled and one level deep, but references/examples.md and references/errors.md are never linked from the body while their content is duplicated inline, matching the score-2 anchor of 'content that should be separate is inline' and references present but not clearly signaled.	2 / 3
	Total	10 / 12 Passed

Description

72%Weight 40%Scale 1-3

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 provides solid trigger-term coverage and a distinct niche, but its capability statement is vague and padded with generic boilerplate ('Use when appropriate context detected. Trigger with relevant phrases based on skill purpose.'). The opening 'Execute this skill should be used' is also grammatically broken, weakening readability.

Suggestions

Rewrite the opening into clean third-person voice stating concrete actions, e.g. 'Authors effective specs.md files for Sprint plugin sprints: defines goals, in/out scope boundaries, and testing configuration.'

Replace the generic 'Use when appropriate context detected. Trigger with relevant phrases based on skill purpose.' with a concrete 'Use when the user asks about writing specs, specs.md format, sprint requirements, or scope definition.' clause.

Crisply state what the skill produces (e.g. 'generates a complete specs.md with goal, in/out scope, and QA/UI testing settings') so the 'what' is as explicit as the 'when'.

Dimension	Reasoning	Score
Specificity	The description names its domain ('sprint specifications for agentic development') and a single action ('guidance on creating effective sprint specifications'), but does not enumerate multiple concrete actions as a score-3 anchor would; it is more comprehensive than the vague score-1 examples yet stops short of listing several specific actions.	2 / 3
Completeness	It answers both what ('guidance on creating effective sprint specifications') and when (explicit quoted triggers + 'when the user asks about'), but the 'what' is vague and the trailing 'Use when appropriate context detected. Trigger with relevant phrases based on skill purpose.' is generic boilerplate fluff rather than the crisp explicit trigger guidance of the score-3 example, so it does not clearly reach 3.	2 / 3
Trigger Term Quality	It quotes six natural trigger phrases a user in this domain would actually say ('writing specs', 'specs.md format', 'how to write specifications', 'sprint requirements', 'testing configuration', 'scope definition'), matching the score-3 anchor's good coverage of natural terms.	3 / 3
Distinctiveness Conflict Risk	It carves a clear niche (the Sprint plugin's specs.md authoring workflow) with distinct triggers like 'specs.md format' and 'sprint requirements' that are unlikely to fire for unrelated skills, matching the score-3 anchor's clear niche with distinct triggers.	3 / 3
	Total	10 / 12 Passed

Validation

93%

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

Validation for skill structure

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

	Total	15 / 16 Passed

Repository: jeremylongshore/claude-code-plugins-plus-skills
Path: plugins/community/sprint/skills/spec-writing/SKILL.md
Commit: c4eafaf

Reviewed: 5 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.