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.
Overall
score
37%
Does it follow best practices?
Validation for skill structure
Install with Tessl CLI
npx tessl i github:jeremylongshore/claude-code-plugins-plus-skills --skill spec-writingActivation
22%This description suffers from vague language, circular statements, and lack of concrete actions. While it includes some useful trigger terms, the ending ('Use when appropriate context detected. Trigger with relevant phrases based on skill purpose') is meaningless boilerplate that provides no guidance. The description fails to explain what the skill actually does beyond providing 'guidance'.
Suggestions
Replace vague 'guidance' language with specific actions (e.g., 'Generates sprint specification documents, defines testing configurations, structures scope requirements in specs.md format').
Remove the circular, meaningless ending ('Use when appropriate context detected. Trigger with relevant phrases based on skill purpose') and replace with concrete trigger guidance.
Add a clear 'Use when...' clause that specifies exact scenarios, such as 'Use when user needs to create a new specs.md file, define sprint scope, or configure testing parameters for agentic workflows.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses vague, abstract language like 'guidance on creating effective sprint specifications' without listing concrete actions. It doesn't specify what the skill actually does (e.g., 'generates spec templates', 'validates spec structure', 'creates testing configurations'). | 1 / 3 |
Completeness | The 'what' is extremely weak - it only says 'guidance on creating effective sprint specifications' without explaining what actions the skill performs. The 'when' section exists but is undermined by the vague, circular ending 'Use when appropriate context detected. Trigger with relevant phrases based on skill purpose.' | 1 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'writing specs', 'specs.md format', 'sprint requirements', 'scope definition'. However, the final sentence 'Trigger with relevant phrases based on skill purpose' is meaningless filler that adds no value. | 2 / 3 |
Distinctiveness Conflict Risk | The terms 'specs.md format' and 'agentic development' provide some distinctiveness, but 'writing specs', 'requirements', and 'scope definition' could easily overlap with general documentation or project management skills. | 2 / 3 |
Total | 6 / 12 Passed |
Implementation
22%This skill content is a generic template with no actual spec-writing guidance. It fails to provide any actionable information about writing specifications, sprint requirements, testing configuration, or scope definition despite the description claiming these capabilities. The content is essentially placeholder text that would leave Claude with no useful knowledge about the task.
Suggestions
Add concrete examples of well-written spec.md files showing the expected format, sections, and content structure
Include specific instructions for defining scope, requirements, acceptance criteria, and testing configuration
Provide a step-by-step workflow for creating specs: gather requirements → define scope → write acceptance criteria → specify tests → validate completeness
Replace generic placeholder text with actual spec-writing guidance, including templates or schemas for the spec format
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is brief but entirely generic - it doesn't waste tokens on explanations Claude knows, but the tokens it does use provide no skill-specific value. It's a template with placeholder text rather than meaningful content. | 2 / 3 |
Actionability | The instructions are completely vague and abstract ('Invoke this skill when trigger conditions are met', 'Provide necessary context'). There are no concrete examples, code, commands, or specific guidance for writing specs. | 1 / 3 |
Workflow Clarity | The 4-step process is generic boilerplate that could apply to any skill. There are no spec-writing-specific steps, no validation checkpoints, and no actual workflow for creating sprint specifications. | 1 / 3 |
Progressive Disclosure | References to external files (errors.md, examples.md) are present and one-level deep, but the references use unresolved template variables ({baseDir}) and the main content provides no useful overview to build upon. | 2 / 3 |
Total | 6 / 12 Passed |
Validation
88%Validation — 14 / 16 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata' field is not a dictionary | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 14 / 16 Passed | |
Reviewed
Table of Contents
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.