spec-add
Add specs, conventions, constraints, or learnings to project guidelines interactively or automatically
52
43%
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 ./.codex/skills/spec-add/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.
The description provides a reasonable sense of what the skill does—adding various types of content to project guidelines—but lacks explicit trigger guidance ('Use when...') and misses common natural language terms users would employ. The actions described are somewhat abstract and could benefit from concrete examples of what 'specs', 'learnings', or 'constraints' mean in practice.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user wants to update project guidelines, add coding conventions, record lessons learned, or modify CLAUDE.md.'
Include more natural trigger terms users would say, such as 'coding standards', 'project rules', 'style guide', 'CLAUDE.md', 'best practices', or 'update conventions'.
Clarify what 'interactively or automatically' means with brief concrete examples, e.g., 'Prompts the user for input or auto-detects patterns from code reviews to update guidelines.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists some actions ('add specs, conventions, constraints, or learnings') and names the domain ('project guidelines'), but the terms are somewhat abstract—what exactly are 'specs' or 'learnings' in this context? The modes 'interactively or automatically' add some detail but remain vague about concrete operations. | 2 / 3 |
Completeness | Describes what the skill does (adding items to project guidelines) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and since the 'what' is also only moderately clear, this scores at 1. | 1 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'guidelines', 'conventions', 'constraints', and 'learnings', but misses common natural phrases users might say such as 'project rules', 'coding standards', 'style guide', 'CLAUDE.md', or 'update guidelines'. The terms are somewhat domain-specific but not comprehensive. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on 'project guidelines' provides some distinctiveness, but terms like 'specs', 'conventions', and 'constraints' could overlap with skills related to documentation, project configuration, or code review. Without clearer scoping, there's moderate conflict risk. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
55%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is highly actionable with excellent workflow clarity and complete executable code, but it is severely over-engineered for a SKILL.md file. The ~400+ lines of inline JavaScript implementation, exhaustive parameter tables, and detailed interactive wizard code make it extremely verbose—most of this implementation detail could be in separate files or generated by Claude from a concise spec. The content would benefit enormously from splitting implementation into referenced files and keeping SKILL.md as a lean overview.
Suggestions
Extract the full JavaScript implementation (Steps 1-7) into a separate IMPLEMENTATION.md or reference file, keeping only the execution flow overview and key decision logic in SKILL.md
Remove or drastically condense the interactive wizard code—Claude can implement prompt flows from a brief specification of the questions and options rather than seeing every request_user_input call spelled out
Consolidate the three parameter/category tables into a single compact reference, or move them to a REFERENCE.md file linked from the overview
Trim the examples section to 2-3 representative cases instead of 7, covering just the primary modes (interactive, direct, auto-confirm)
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Includes exhaustive implementation details (full JavaScript parsing code, interactive wizard prompts, file I/O logic) that Claude could generate from a concise specification. The parameter tables, type subcategory tables, and workflow stage tables add significant bulk. Much of the code is boilerplate that doesn't need to be spelled out line by line. | 1 / 3 |
Actionability | Provides fully executable JavaScript code for every step, concrete CLI examples with expected outputs, specific file paths, regex patterns for auto-detection, and complete implementation logic. Everything is copy-paste ready with no ambiguity. | 3 / 3 |
Workflow Clarity | The execution process is clearly sequenced with an explicit flowchart showing branching paths (interactive vs direct mode), numbered steps, validation checks (duplicate detection, parameter validation), and error recovery. The workflow includes validation before writing and a rebuild step after. | 3 / 3 |
Progressive Disclosure | Everything is crammed into a single monolithic file with no references to external documentation. The full implementation code, all examples, parameter tables, file structure diagrams, and error handling are all inline. The implementation details (Steps 1-7 with full code) should be in a separate file, with SKILL.md providing just the overview, usage patterns, and key decision points. | 1 / 3 |
Total | 8 / 12 Passed |
Validation
72%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 8 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (621 lines); consider splitting into references/ and linking | Warning |
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 8 / 11 Passed | |
- Repository
- catlog22/Claude-Code-Workflow
- Commit
0f8e801
- 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.