Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
78
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 ./skills/core/agent-ops-spec/SKILL.mdQuality
Discovery
75%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description is structurally sound with a clear 'Use when' clause and a distinct niche around specification management. Its main weakness is the vague verb 'Manage' which doesn't enumerate specific actions, and the trigger terms could be broader to capture more natural user phrasings like 'user stories' or 'spec'.
Suggestions
Replace 'Manage' with specific concrete actions like 'Create, update, and validate specification documents' to improve specificity.
Add more natural trigger terms users might say, such as 'user stories', 'spec', 'definition of done', or 'feature requirements'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (specification documents) and mentions some actions like 'tracked and validated against implementation', but doesn't list multiple concrete actions (e.g., create, update, delete, compare specs to code). 'Manage' is somewhat vague. | 2 / 3 |
Completeness | Clearly answers both 'what' (manage specification documents in .agent/specs/) and 'when' (when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated). Has an explicit 'Use when' clause. | 3 / 3 |
Trigger Term Quality | Includes relevant terms like 'requirements', 'acceptance criteria', 'feature descriptions', and 'specs', but misses common variations users might say such as 'spec', 'user stories', 'definition of done', 'test criteria', or 'feature spec'. | 2 / 3 |
Distinctiveness Conflict Risk | The specific path '.agent/specs/' and the focus on specification documents with acceptance criteria creates a clear niche that is unlikely to conflict with general documentation or code skills. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
72%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a concise, well-structured skill that effectively outlines the spec management workflow without unnecessary verbosity. Its main weakness is insufficient actionability—it tells Claude what to do but doesn't show concrete examples of spec content, traceability checklists, or validation outcomes. The validation workflow also lacks error recovery guidance.
Suggestions
Add a concrete example of a traceability checklist (requirement → implementation location → test) so Claude knows exactly what format to produce.
Include a brief inline example of a filled-in spec or at least show the key fields/sections expected, rather than relying solely on the external template reference.
Add explicit guidance for what to do when validation finds unmet requirements (e.g., flag gaps, update issue status, notify user).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient. No unnecessary explanations of what specs are or why they matter—it jumps straight into actionable procedure. Every line serves a purpose. | 3 / 3 |
Actionability | The steps are concrete but lack executable examples. There's no sample spec content, no example of what a traceability checklist looks like, and the template is referenced but not shown inline. The guidance describes what to do rather than showing it. | 2 / 3 |
Workflow Clarity | Two workflows (creating and validating) are clearly sequenced, but the validation workflow lacks explicit checkpoints or feedback loops. There's no guidance on what to do if validation fails or how to handle partial compliance against a spec. | 2 / 3 |
Progressive Disclosure | The skill is appropriately short with a clear reference to the spec template as a one-level-deep link. Content is well-organized into logical sections (Purpose, Location, Procedure, Template) for easy navigation. | 3 / 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 | |
632759f
Table of Contents
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.