tech-spec-status
Show Tech Spec details or update status through lifecycle
62
47%
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/tech-spec-status/SKILL.mdQuality
Discovery
17%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 terse and lacks the explicit trigger guidance needed for Claude to reliably select it. While it mentions a specific domain (Tech Spec), it fails to explain what Tech Specs are, what lifecycle stages exist, or when this skill should be used over alternatives.
Suggestions
Add a 'Use when...' clause with explicit triggers like 'Use when the user asks about technical specifications, spec status, spec lifecycle, or wants to view/update specification documents'
Expand the capabilities to be more specific: what details can be shown (e.g., 'view spec metadata, requirements, approval status') and what status updates are possible (e.g., 'draft, review, approved, implemented')
Include natural language variations users might say: 'technical specification', 'spec document', 'specification status', 'spec details'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Tech Spec) and two actions (show details, update status), but lacks comprehensive detail about what 'details' means or what lifecycle stages exist. | 2 / 3 |
Completeness | Provides a weak 'what' (show/update Tech Spec) but completely lacks any 'when' clause or explicit trigger guidance for when Claude should select this skill. | 1 / 3 |
Trigger Term Quality | 'Tech Spec' is somewhat technical jargon, and 'lifecycle' is vague. Missing natural user terms like 'specification', 'technical document', 'spec status', or common variations users would actually say. | 1 / 3 |
Distinctiveness Conflict Risk | 'Tech Spec' provides some specificity, but 'show details' and 'update status' are generic actions that could overlap with many document or project management skills. | 2 / 3 |
Total | 6 / 12 Passed |
Implementation
77%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 skill with excellent workflow clarity and concise presentation. The lifecycle management process is clearly documented with validation checkpoints and state transitions. The main weakness is that it describes operations rather than providing executable code for file manipulation and frontmatter updates.
Suggestions
Add executable code snippets for key operations like parsing frontmatter, updating status fields, and moving files with git
Consider extracting detailed transition checks into a separate TRANSITIONS.md file to improve progressive disclosure
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient, using tables and structured formats to convey information without unnecessary explanation. No concepts are over-explained; it assumes Claude understands file operations, git, and frontmatter. | 3 / 3 |
Actionability | Provides clear step-by-step instructions and example outputs, but lacks executable code. The instructions describe what to do (search directories, update frontmatter, move files) without providing actual implementation code or commands beyond the CLI interface examples. | 2 / 3 |
Workflow Clarity | Multi-step processes are clearly sequenced with numbered steps. Pre-transition checks serve as validation checkpoints, and the valid transitions table provides clear constraints. The lifecycle diagram provides excellent visual summary. | 3 / 3 |
Progressive Disclosure | Content is well-organized with clear sections, but everything is in a single file. For a skill of this length (~150 lines), some content like the detailed transition checks or error handling could be split into referenced files for better organization. | 2 / 3 |
Total | 10 / 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.