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.

43

Quality

43%

Does it follow best practices?

Impact

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 heavily padded with boilerplate filler phrases ('Use when appropriate context detected', 'Trigger with relevant phrases based on skill purpose') that provide zero informational value. It lists some relevant trigger terms but completely fails to describe what the skill actually does — the core capabilities are absent. The description reads like a template that was never properly filled in.

Suggestions

Replace the boilerplate filler with a concrete description of what the skill does, e.g., 'Generates sprint specification documents in specs.md format, including scope definition, acceptance criteria, testing configuration, and task breakdowns for agentic development workflows.'

Remove the meaningless phrases 'Use when appropriate context detected' and 'Trigger with relevant phrases based on skill purpose' — these add no selection value and waste space.

Structure the description as 'what it does' followed by a clear 'Use when...' clause, e.g., 'Use when the user asks about writing specs, creating specs.md files, defining sprint scope, or configuring test requirements for agentic sprints.'

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' is almost entirely missing — the description never explains what the skill actually does beyond vague references to 'creating effective sprint specifications for agentic development.' The 'when' clause exists but is padded with meaningless boilerplate like 'Use when appropriate context detected' and 'Trigger with relevant phrases based on skill purpose,' which provide no real guidance.

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 broader coverage of variations, and the generic trailing phrases ('relevant phrases based on skill purpose') add no value.

2 / 3

Distinctiveness Conflict Risk

The mention of 'sprint specifications for agentic development' and 'specs.md format' provides some niche specificity, but the lack of concrete capability description and the generic phrasing could cause overlap with general documentation or project planning 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 that demonstrate exactly what a well-formed specs.md looks like. Its main weaknesses are moderate verbosity (the overview, prerequisites, and error handling table could be tightened) and the lack of explicit validation checkpoints in the workflow. The progressive disclosure pattern is reasonable but unverifiable without bundle files.

Suggestions

Add a validation checkpoint after writing the spec, such as a checklist to verify the spec has all required sections (goal, in-scope, out-of-scope, testing) before proceeding to the sprint.

Trim the Overview and Prerequisites sections — Claude doesn't need to be told what a well-written spec does or that the sprint plugin must be installed; focus on the 'how' rather than the 'why'.

Move the Error Handling table to a reference file to reduce the main skill's token footprint, or condense it into a shorter list of the most critical pitfalls.

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') and the Prerequisites section explains things Claude could infer. The Error Handling table adds useful but somewhat verbose content. However, the examples and instructions are reasonably focused.

2 / 3

Actionability

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

3 / 3

Workflow Clarity

The steps are clearly sequenced (1-7) and cover the spec writing process well, but there are no explicit validation checkpoints. Step 7 mentions reviewing previous status.md but there's no 'validate your spec before proceeding' step or feedback loop to verify the spec is well-formed before the architect consumes it.

2 / 3

Progressive Disclosure

The skill references external files like `${CLAUDE_SKILL_DIR}/references/testing-configuration.md` and other skills (sprint-workflow, API contract), which is good progressive disclosure. However, no bundle files are provided to verify these references exist, and the inline content is somewhat long with the error handling table and two full examples that could potentially be in a reference file.

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.