create-tech-spec
Create a new Technical Specification for implementation details
71
60%
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/devops-data/skills/create-tech-spec/SKILL.mdQuality
Discovery
32%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 too brief and lacks the completeness needed for effective skill selection. While it identifies the core purpose (creating technical specifications), it fails to provide explicit trigger conditions and misses natural keyword variations users might employ. The description would benefit significantly from a 'Use when...' clause and more specific capability details.
Suggestions
Add a 'Use when...' clause with trigger terms like 'tech spec', 'technical specification', 'implementation plan', 'design document', 'architecture spec'
Expand the capabilities to list specific actions such as 'define system architecture, document API contracts, specify data models, outline implementation requirements'
Include file format or output type information to distinguish from other documentation skills (e.g., 'generates structured markdown specifications')
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Technical Specification) and one action (Create), but lacks comprehensive detail about what creating a technical specification entails or what specific capabilities are involved. | 2 / 3 |
Completeness | Only addresses 'what' (create a technical specification) but completely lacks any 'Use when...' clause or explicit trigger guidance for when Claude should select this skill. | 1 / 3 |
Trigger Term Quality | Includes 'Technical Specification' and 'implementation details' which are relevant terms, but misses common variations users might say like 'tech spec', 'design doc', 'architecture document', or 'spec document'. | 2 / 3 |
Distinctiveness Conflict Risk | Somewhat specific to technical specifications, but could overlap with other documentation skills, design document skills, or general writing skills without clearer boundaries. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
87%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, actionable skill that efficiently communicates how to create technical specifications. The content is appropriately concise, provides concrete examples and file paths, and organizes information logically. The main weakness is in validation workflow - while error handling is mentioned, explicit feedback loops for validation failures could be stronger.
Suggestions
Add explicit feedback loop for RFC validation: 'If RFC not found: display error with list of available RFCs, ask user to confirm or provide correct RFC number'
Include a validation checkpoint after file creation: 'Verify file was created successfully and contains valid frontmatter before displaying confirmation'
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient, providing only necessary information without explaining concepts Claude already knows. Each section serves a clear purpose with no padding or unnecessary context. | 3 / 3 |
Actionability | Provides fully concrete, executable guidance with specific file paths, exact naming conventions, directory structures, and step-by-step instructions. The confirmation message template and example outputs are copy-paste ready. | 3 / 3 |
Workflow Clarity | Steps are clearly sequenced and numbered, but validation checkpoints are weak. The 'If RFC provided, validate and link' step lacks explicit error recovery, and there's no feedback loop for the RFC validation failure case beyond 'warn but allow creation'. | 2 / 3 |
Progressive Disclosure | Well-organized with clear sections (Usage, Arguments, Execution Instructions, Examples, Validation, Error Handling). References the external template file appropriately with a single-level reference. Content is appropriately scoped for a skill file. | 3 / 3 |
Total | 11 / 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.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- jpoutrin/product-forge
- Commit
0ebe7ae
- 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.