spec-add
Add specs, conventions, constraints, or learnings to project guidelines interactively or automatically
41
43%
Does it follow best practices?
Impact
—
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 high-level summary of the skill's purpose but lacks the specificity and explicit trigger guidance needed for reliable skill selection. It names the domain (project guidelines) and some actions but uses somewhat abstract terminology and entirely omits a 'Use when...' clause, making it harder for Claude to know when to select this skill over others.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user wants to update project guidelines, CLAUDE.md, coding standards, or when Claude discovers new project conventions or constraints.'
Include more natural trigger terms users would say, such as 'coding standards', 'best practices', 'project rules', 'style guide', 'CLAUDE.md', or 'memory'.
Clarify what 'interactively or automatically' means concretely — e.g., 'Prompts the user for confirmation or silently appends discovered patterns to the guidelines file.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists some actions ('add specs, conventions, constraints, or learnings') and names the domain ('project guidelines'), but the actions are somewhat abstract — what exactly are 'specs' or 'learnings' in this context? The terms 'interactively or automatically' add some detail but remain vague about concrete mechanisms. | 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 a 1. | 1 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'guidelines', 'conventions', 'constraints', and 'learnings', but misses common natural phrases a user might say such as 'project rules', 'coding standards', 'best practices', 'style guide', or 'CLAUDE.md'. The terms are somewhat domain-relevant but not comprehensive. | 2 / 3 |
Distinctiveness Conflict Risk | The concept of 'project guidelines' provides some specificity, 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 implementation code, redundant parameter documentation, and lack of any progressive disclosure make it extremely token-inefficient. The content would benefit enormously from being split into a concise overview SKILL.md with implementation details in referenced files.
Suggestions
Reduce the SKILL.md to a concise overview (~50-80 lines) covering usage examples, parameter summary, and target file resolution, moving the full JavaScript implementation into a separate IMPLEMENTATION.md or actual script file.
Remove redundant documentation — the execution process flowchart, the parameter table, the type/category tables, and the code all describe the same logic three times. Pick one authoritative representation.
Extract the category/type reference tables and file structure diagrams into a separate REFERENCE.md with a clear link from the main skill.
Eliminate explanatory text that Claude can infer from code — e.g., comments like '// Extract flags' and '// Validate values' add no value when the code is self-documenting.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Massive amounts of implementation detail (full JavaScript parsing code, interactive wizard prompts, file system operations) that Claude could generate from a concise specification. The parameter tables, type/category subcategory tables, and full execution flowchart are heavily redundant with the code examples that follow. Much of this could be condensed to 1/4 the size. | 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 details. The code is copy-paste ready and covers all modes (interactive, direct, auto-confirm). | 3 / 3 |
Workflow Clarity | Clear multi-step process with explicit flowchart showing branching paths (interactive vs direct mode), validation steps (duplicate checking, input validation), error handling for each failure mode, and a rebuild step after writing. The execution process diagram clearly sequences all steps with decision points. | 3 / 3 |
Progressive Disclosure | Monolithic wall of content with no references to external files despite the massive size. The full implementation code, parameter tables, category definitions, file structure diagrams, and examples are all inline. This content desperately needs splitting — e.g., implementation details into a separate file, category reference into another. | 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
5ff5e86
- 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.