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.
75
68%
Does it follow best practices?
Impact
Pending
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 strong skill description that clearly articulates specific capabilities and includes an explicit 'Use when' clause with relevant trigger terms. The description uses proper third-person voice and covers both what the skill does and when to use it. The only minor weakness is potential overlap with other documentation or architecture-related skills, though the focus on 'technical specifications' helps differentiate 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 or architecture-focused skills. Terms like 'system design' and 'architecture' are somewhat broad and could conflict with other design or planning skills. | 2 / 3 |
Total | 11 / 12 Passed |
Implementation
44%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill provides a solid template structure for technical specifications with appropriate progressive disclosure to a fuller reference template. However, it lacks a clear workflow for how Claude should actually create specs (gathering requirements, iterating, validating completeness), and the examples are generic placeholders rather than realistic demonstrations. The Do/Don't section is somewhat redundant with the template itself.
Suggestions
Add a step-by-step workflow section describing how Claude should approach creating a spec (e.g., 1. Clarify scope with user, 2. Draft executive summary, 3. Define requirements, 4. Validate completeness against checklist)
Include at least one realistic filled-out example section (e.g., a complete Executive Summary + Functional Requirements for a concrete feature like 'user authentication') to show what good output looks like
Remove or significantly trim the Do/Don't section since most of these points are already embodied in the template structure itself
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The template is reasonably structured but includes some filler content (placeholder text like '[Name]', '[Description]') that adds bulk without teaching Claude anything new. The Do/Don't list at the end restates things already implicit in the template itself, adding redundancy. | 2 / 3 |
Actionability | The template provides a concrete structure with specific sections, tables, and example SQL/API snippets, which is helpful. However, the examples are generic placeholders rather than realistic filled-out examples that would show Claude what good output looks like. It's more of a skeleton than executable guidance. | 2 / 3 |
Workflow Clarity | There is no workflow for how to actually create a spec — no sequenced steps, no validation checkpoints, no guidance on how to gather information, iterate on drafts, or verify completeness. It's just a template with no process around it. | 1 / 3 |
Progressive Disclosure | The skill provides a concise inline template and clearly references a more comprehensive template at 'references/template.md' with a well-signaled list of what additional content it contains. This is a clean one-level-deep reference structure. | 3 / 3 |
Total | 8 / 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
88da5ff
- 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.