technical-specification
Technical specification writing for implementation details. Use when documenting how to build a solution (post-decision), API contracts, schemas, and system design. Complements RFC skill which handles decision-making.
75
73%
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/technical-specification/SKILL.mdQuality
Discovery
89%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 description that clearly defines its scope and distinguishes itself from related skills (RFC). It has strong trigger terms and explicit guidance on when to use it. The main weakness is that the specific actions could be more concrete - listing specific deliverables like 'endpoint documentation' or 'data model definitions' would strengthen it.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (technical specification writing) and some actions (documenting implementation details, API contracts, schemas, system design), but doesn't list comprehensive concrete actions like 'create endpoint documentation' or 'define data models'. | 2 / 3 |
Completeness | Clearly answers both what (technical specification writing for implementation details, API contracts, schemas, system design) and when (documenting how to build a solution post-decision). Also helpfully distinguishes from RFC skill for decision-making. | 3 / 3 |
Trigger Term Quality | Includes natural keywords users would say: 'technical specification', 'implementation details', 'API contracts', 'schemas', 'system design', and 'post-decision'. These are terms developers naturally use when needing this type of documentation. | 3 / 3 |
Distinctiveness Conflict Risk | Explicitly differentiates from RFC skill by clarifying this is for post-decision implementation documentation. The specific triggers (API contracts, schemas, system design) create a clear niche distinct from general documentation skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides comprehensive coverage of tech spec documentation but suffers from verbosity and lacks concrete, executable examples. The structure and organization are strong, with good use of tables and clear references to external resources. However, the actionability is weakened by describing what to include rather than showing complete examples of each section.
Suggestions
Add a complete, minimal tech spec example (even abbreviated) showing all required sections filled in with realistic content rather than just describing what each section should contain.
Integrate the completeness checklist into a step-by-step workflow: 'Step 1: Create file with header metadata → Step 2: Write executive summary → Step 3: Validate with checklist before marking APPROVED'.
Remove or condense the 'When This Skill Activates' section - Claude can infer activation contexts from the document structure and RFC comparison table.
Provide concrete API specification examples with actual endpoint definitions, request/response JSON, and error formats rather than just listing what to include.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill contains useful information but is verbose in places. The RFC vs Tech Spec comparison table and lifecycle explanations are helpful, but sections like 'When This Skill Activates' list items Claude could infer. The document could be tightened by 30-40%. | 2 / 3 |
Actionability | Provides good structural guidance with YAML metadata examples and section outlines, but lacks concrete executable examples. API specification section describes what to include but doesn't show actual request/response examples. Commands listed at the end have no implementation details. | 2 / 3 |
Workflow Clarity | The lifecycle diagram and status definitions are clear, but the actual workflow for creating a tech spec lacks explicit validation steps. The 'Completeness Checklist' is good but appears at the end rather than integrated into a step-by-step creation workflow. | 2 / 3 |
Progressive Disclosure | Well-organized with clear sections, appropriate use of tables for comparisons, and references to external templates and checklists at the end. The directory structure and file naming conventions are appropriately placed. References are one level deep and clearly signaled. | 3 / 3 |
Total | 9 / 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.