technical-specification
Creates detailed technical specifications for software projects covering requirements, architecture, APIs, and testing strategies. Use when planning features, documenting system design, or creating architecture decision records.
57
64%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/technical-specification/skills/technical-specification/SKILL.mdQuality
Discovery
92%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 is a well-crafted skill description that clearly communicates both what the skill does and when to use it. It uses appropriate third-person voice, includes natural trigger terms, and has an explicit 'Use when' clause. The only minor weakness is potential overlap with other architecture or documentation-focused skills, though the combination of all listed capabilities helps distinguish it.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: creating technical specifications covering requirements, architecture, APIs, and testing strategies. Also mentions planning features, documenting system design, and creating architecture decision records. | 3 / 3 |
Completeness | Clearly answers both 'what' (creates detailed technical specifications covering requirements, architecture, APIs, and testing strategies) and 'when' (explicit 'Use when' clause covering planning features, documenting system design, or creating architecture decision records). | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'technical specifications', 'requirements', 'architecture', 'APIs', 'testing strategies', 'planning features', 'system design', 'architecture decision records'. These are terms developers naturally use when requesting this type of work. | 3 / 3 |
Distinctiveness Conflict Risk | While it targets technical specifications specifically, there could be overlap with general documentation skills, API design skills, or architecture-focused skills. Terms like 'architecture' and 'APIs' are broad enough to potentially conflict with more specialized skills in those areas. | 2 / 3 |
Total | 11 / 12 Passed |
Implementation
37%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a solid template structure for technical specifications with concrete examples (API design, SQL schema, requirements tables), but it lacks a clear workflow for how to actually create a spec step-by-step. The content is moderately concise but includes some generic best practices Claude already knows, and the large inline template could be better split with the referenced template file. The biggest weakness is the absence of any sequenced process or validation checkpoints.
Suggestions
Add a clear numbered workflow (e.g., 1. Gather context from user, 2. Draft executive summary, 3. Define requirements, 4. Validate completeness checklist) to guide Claude through spec creation step-by-step.
Trim the best practices section to only non-obvious guidance—remove items like 'don't use vague requirements' that Claude already understands.
Move the full inline template to the referenced template.md file and keep only a minimal skeleton (section headers with one-line descriptions) in SKILL.md to improve progressive disclosure.
Add a validation/completeness checklist step that Claude should run before presenting the final spec (e.g., 'Verify all P0 requirements have acceptance criteria, all APIs have request/response examples, all risks have mitigations').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The template is reasonably structured but includes placeholder content that could be more compact. The best practices section adds some value but is somewhat generic advice Claude already knows (e.g., 'don't use vague requirements'). The inline template is lengthy but serves as a concrete reference. | 2 / 3 |
Actionability | The skill provides a concrete template with specific sections and examples (SQL schema, API design), which is useful. However, it's mostly a fill-in-the-blank template rather than executable guidance—there are no commands, scripts, or step-by-step instructions for actually creating a spec. The placeholders like '[Description]' and '[Risk]' reduce actionability. | 2 / 3 |
Workflow Clarity | There is no clear workflow or sequenced process for creating a technical specification. The skill presents a template and best practices but doesn't guide Claude through the steps of gathering requirements, drafting sections, validating completeness, or iterating with stakeholders. For a multi-section document creation task, this lack of sequencing is a significant gap. | 1 / 3 |
Progressive Disclosure | The skill references 'references/template.md' for a comprehensive template, which is good progressive disclosure structure. However, no bundle files are provided, so the reference is unverifiable. The inline template is quite long and could have been split more aggressively, with only a minimal example kept in the main file. | 2 / 3 |
Total | 7 / 12 Passed |
Validation
100%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
- secondsky/claude-skills
- Commit
5e92b71
- 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.