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.

Quality

73%

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/devops-data/skills/technical-specification/SKILL.md

Quality

Content

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

Description

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

Validation

90%

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 — 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: 5 months 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.