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.

Quality

64%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

tessl review fix ./plugins/technical-specification/skills/technical-specification/SKILL.md

Quality

Content

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

Description

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

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: secondsky/claude-skills
Commit: 5e92b71

Reviewed: about 1 month 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.