spec-add

Add specs, conventions, constraints, or learnings to project guidelines interactively or automatically

Quality

43%

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 ./.codex/skills/spec-add/SKILL.md

Quality

Content

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 content is roughly 4x longer than necessary, embedding full implementation code that Claude could generate from a concise spec. The lack of any bundle files means everything is crammed into one monolithic document, violating progressive disclosure principles.

Suggestions

Extract the full implementation code (Steps 1-7) into a separate IMPLEMENTATION.md or reference file, keeping only the execution flowchart and key decision logic in SKILL.md

Remove redundant content: the parameter table, type/category subcategory tables, AND the code all describe the same information three times - pick one authoritative representation

Condense the examples section to 2-3 representative examples instead of 7, and remove the verbose confirmation output templates that Claude can generate

Move the Target File Resolution section to a bundle file since it duplicates information already present in the Step 4 code

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 with clear variable names and logic.	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), error handling, and a rebuild step at the end. The workflow includes feedback for errors and clear decision points.	3 / 3
Progressive Disclosure	Monolithic wall of text with no bundle files to offload content to. The full implementation code, parameter tables, category tables, examples, error handling, and file structure diagrams are all inline. The implementation details (Steps 1-7 with full code) should be in separate reference files, with SKILL.md serving as an overview.	1 / 3
	Total	8 / 12 Passed

Description

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 moderate sense of what the skill does—adding various types of knowledge to project guidelines—but lacks explicit trigger guidance ('Use when...') and natural user-facing keywords. It would benefit from clearer examples of when to invoke it and more concrete language about the specific actions performed.

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 'project rules', 'coding standards', 'best practices', 'CLAUDE.md', 'project notes', or 'style guide'.

Clarify what 'interactively or automatically' means in practice—e.g., 'Prompts the user for input or automatically extracts patterns from code review feedback 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? It also mentions 'interactively or automatically' which adds some detail about how it works.	2 / 3
Completeness	Describes what it does (adds specs/conventions/constraints/learnings 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 the 'what' is also only moderately clear, so 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', 'best practices', 'CLAUDE.md', or 'project config'. The terms are somewhat domain-specific but not strongly aligned with natural user language.	2 / 3
Distinctiveness Conflict Risk	The concept of 'project guidelines' is somewhat specific, but terms like 'specs', 'conventions', and 'constraints' could overlap with skills related to documentation, project setup, or configuration management. It's not generic enough to conflict with everything, but not sharply distinct either.	2 / 3
	Total	7 / 12 Passed

Validation

72%

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 — 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: 07491b0

Reviewed: 20 days 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.