CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

54

Quality

43%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./plugins/community/sprint/skills/spec-writing/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Discovery

22%

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 description is extremely weak because it never explains what the skill actually does — it only lists trigger phrases and includes meaningless boilerplate filler like 'Use when appropriate context detected' and 'Trigger with relevant phrases based on skill purpose.' The trigger terms provide some relevance but cannot compensate for the complete absence of capability description.

Suggestions

Replace the entire description with a clear statement of what the skill does, e.g., 'Guides users through creating sprint specification documents (specs.md) including scope definition, testing configuration, and acceptance criteria for agentic development workflows.'

Remove the generic filler phrases ('Use when appropriate context detected. Trigger with relevant phrases based on skill purpose.') and replace with a concrete 'Use when...' clause, e.g., 'Use when the user asks how to write sprint specs, needs help structuring a specs.md file, or wants guidance on defining scope and testing requirements.'

Add specific concrete actions the skill performs, such as 'generates specs.md templates', 'defines acceptance criteria', or 'structures sprint scope and testing configuration'.

DimensionReasoningScore

Specificity

The description fails to describe any concrete actions or capabilities. It mentions topic areas like 'writing specs' and 'scope definition' but never states what the skill actually does. Phrases like 'Use when appropriate context detected' and 'Trigger with relevant phrases based on skill purpose' are pure filler with no substance.

1 / 3

Completeness

The 'what does this do' is essentially absent — there is no explanation of what the skill actually performs. The 'when' portion lists trigger phrases but the generic filler ('Use when appropriate context detected. Trigger with relevant phrases based on skill purpose.') adds nothing meaningful. The description fails to clearly answer either question.

1 / 3

Trigger Term Quality

It does include some natural keywords users might say, such as 'writing specs', 'specs.md format', 'sprint requirements', 'testing configuration', and 'scope definition'. However, these are presented as a list without clear domain grounding, and some terms like 'agentic development' are niche jargon.

2 / 3

Distinctiveness Conflict Risk

The mention of 'specs.md format', 'sprint specifications', and 'agentic development' provides some niche specificity that would reduce conflicts. However, terms like 'writing specs' and 'scope definition' are broad enough to overlap with general project management or documentation skills.

2 / 3

Total

6

/

12

Passed

Implementation

64%

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

This is a solid, actionable skill with excellent concrete examples showing exact spec format. Its main weaknesses are moderate verbosity (explanatory prose that Claude doesn't need) and lack of explicit validation checkpoints before specs are consumed by downstream agents. The error handling table and decision guidance for testing configuration add genuine value.

Suggestions

Add a validation checkpoint step (e.g., 'Review the spec against this checklist: goal is one sentence, In Scope lists specific items, Out of Scope is non-empty, Testing section has all three fields') to improve workflow clarity.

Trim the Overview and Prerequisites sections — Claude doesn't need to be told why good specs matter or what a sprint plugin is; just state the file path and jump to instructions.

DimensionReasoningScore

Conciseness

The skill includes some unnecessary explanation (e.g., 'A well-written specification determines the quality of agent output by clearly defining goals, scope boundaries, and testing requirements' is filler). The Prerequisites section explains things Claude can infer. However, the core instructions and examples are reasonably efficient.

2 / 3

Actionability

The skill provides concrete, copy-paste-ready spec examples with exact markdown format, specific configuration values (required/optional/skip, automated/manual), and clear decision criteria for when to use each setting. The numbered instructions give specific guidance on what to write in each section.

3 / 3

Workflow Clarity

The 7 steps are clearly sequenced and cover the full spec-writing process including iterative refinement (step 7). However, there are no validation checkpoints — no step to verify the spec is well-formed or complete before handing off to the architect. For a process that drives autonomous agent behavior, a review/validation step would be important.

2 / 3

Progressive Disclosure

References to external files like `testing-configuration.md` and other skills are present and clearly signaled. However, the main content is somewhat long with inline error handling tables and two full examples that could potentially be in a reference file. The bundle has no files provided, so the referenced `testing-configuration.md` cannot be verified, though the reference path structure is reasonable.

2 / 3

Total

9

/

12

Passed

Validation

90%

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

Validation10 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

10

/

11

Passed

Repository
jeremylongshore/claude-code-plugins-plus-skills
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.