sdd-spec

Write specifications with requirements and scenarios (delta specs for changes). Trigger: When the orchestrator launches you to write or update specs for a change.

Quality

60%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/sdd-spec/SKILL.md

Quality

Content

85%

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

This is a well-structured skill with clear, actionable guidance for writing delta specifications. The multi-step workflow is well-sequenced with appropriate branching for different artifact store modes, and templates are concrete and copy-paste ready. Minor verbosity exists in explaining RFC 2119 keywords that Claude already knows, but overall token efficiency is reasonable given the task complexity.

Suggestions

Remove the RFC 2119 Keywords Quick Reference table — Claude already knows these keywords and their meanings, saving ~10 lines of token budget.

Dimension	Reasoning	Score
Conciseness	The skill is mostly efficient but includes some unnecessary content like the RFC 2119 keywords quick reference table, which Claude already knows. The artifact store mode branching logic adds necessary complexity but could be slightly tighter. The overall length is reasonable for the complexity of the task.	2 / 3
Actionability	The skill provides concrete, copy-paste-ready templates for delta specs and full specs, specific file path conventions, exact markdown formats for the return summary, and clear branching logic for each artifact store mode. Every step has specific, executable guidance.	3 / 3
Workflow Clarity	The 6-step workflow is clearly sequenced with explicit dependencies (e.g., Step 1 loads skills before Step 2 identifies domains). Step 5 is marked as MANDATORY with bold emphasis. The branching per artifact mode at each step provides clear validation of which path to follow. The persistence contract references shared conventions for retrieval and persistence checkpoints.	3 / 3
Progressive Disclosure	The skill appropriately references shared conventions via one-level-deep links (sdd-phase-common.md Sections A-D, openspec-convention.md) rather than inlining them. The main content stays focused on spec-writing specifics while delegating common patterns to shared files. Navigation is clearly signaled.	3 / 3
	Total	11 / 12 Passed

Description

35%

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 a basic sense of what the skill does (writing specs with requirements and scenarios) but relies on internal system jargon ('orchestrator launches you') rather than natural user trigger terms. It lacks the concrete detail and explicit user-facing trigger guidance needed for reliable skill selection from a large pool of skills.

Suggestions

Replace the orchestrator-focused trigger with natural user keywords, e.g., 'Use when the user asks to write, draft, or update a specification, requirements document, acceptance criteria, or feature spec.'

Add more specific concrete actions, e.g., 'Drafts feature specifications with functional requirements, acceptance criteria, and user scenarios. Generates delta specs that describe only the changes needed for an existing spec.'

Include common user-facing trigger terms like 'spec', 'requirements doc', 'acceptance criteria', 'user stories', 'feature spec', '.md spec file' to improve keyword matching.

Dimension	Reasoning	Score
Specificity	Names the domain (specifications) and some actions (write, update, requirements, scenarios, delta specs), but lacks comprehensive detail about what concrete actions are performed beyond 'write specifications'.	2 / 3
Completeness	The 'what' is partially addressed (write specifications with requirements and scenarios), but the 'when' clause is weak — it says 'when the orchestrator launches you' which is an internal system trigger, not an explicit user-facing trigger condition. This doesn't help Claude decide when to select this skill based on user input.	2 / 3
Trigger Term Quality	The trigger clause references an 'orchestrator' launching the skill rather than natural user keywords. Users would say things like 'spec', 'requirements document', 'feature spec', 'acceptance criteria' — none of which appear. The trigger is system-internal jargon, not user-facing language.	1 / 3
Distinctiveness Conflict Risk	The mention of 'specifications', 'requirements', 'scenarios', and 'delta specs' provides some distinctiveness, but 'write specifications' could overlap with documentation or planning skills. The lack of specific file types, formats, or domain context increases conflict risk.	2 / 3
	Total	7 / 12 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: Gentleman-Programming/agent-teams-lite
Commit: 6901875

Reviewed: 3 months 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.