spec-setup
Initialize project-level state and configure specs via interactive questionnaire.
40
28%
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-setup/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.
The description is too vague and jargon-heavy to effectively guide skill selection. It lacks a 'Use when...' clause, natural trigger terms, and specificity about what kind of project, state, or specs are involved. Without clearer context and explicit trigger guidance, Claude would struggle to reliably select this skill from a pool of alternatives.
Suggestions
Add a 'Use when...' clause specifying explicit triggers, e.g., 'Use when the user wants to set up a new project, initialize configuration, or run a setup wizard.'
Replace jargon like 'project-level state' and 'configure specs' with natural terms users would say, such as 'project setup', 'initial configuration', 'project init', or 'onboarding'.
Specify the domain or technology context (e.g., what kind of project or specs) to reduce overlap with other configuration-related skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names two actions ('initialize project-level state' and 'configure specs') and mentions a mechanism ('interactive questionnaire'), but the domain is unclear and the actions are somewhat abstract—what kind of project state? What specs? | 2 / 3 |
Completeness | Describes a vague 'what' but completely lacks a 'when should Claude use it' clause. There is no 'Use when...' or equivalent trigger guidance, which per the rubric caps completeness at 2, and the weak 'what' brings it to 1. | 1 / 3 |
Trigger Term Quality | Uses technical jargon like 'project-level state' and 'configure specs' that users are unlikely to naturally say. Missing common trigger terms like 'setup', 'init', 'project config', 'onboarding', or 'wizard'. | 1 / 3 |
Distinctiveness Conflict Risk | The mention of 'interactive questionnaire' adds some distinctiveness, but 'initialize project-level state' and 'configure specs' are generic enough to overlap with many project setup or configuration skills. | 2 / 3 |
Total | 6 / 12 Passed |
Implementation
39%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill has excellent workflow clarity with well-defined steps, decision points, and error handling, but is severely undermined by extreme verbosity and poor progressive disclosure. The ~400+ line monolithic file includes exhaustive implementation details (full questionnaire option arrays, complete agent prompts, helper function implementations) that should either be in separate files or condensed significantly. The code examples, while detailed, use assumed APIs that aren't truly executable.
Suggestions
Reduce the file to ~100 lines by extracting questionnaire round definitions, the agent prompt template, and helper functions into separate referenced files (e.g., QUESTIONNAIRE_ROUNDS.md, AGENT_PROMPT.md)
Replace the verbose JavaScript pseudocode with concise step descriptions — Claude can generate the implementation from brief instructions like 'Generate language-specific coding style options based on detected primary language'
Remove the full option arrays for each questionnaire round and instead describe the pattern once with one example round, noting that other rounds follow the same pattern with domain-appropriate options
Consolidate the summary template code into a brief description of what to display rather than spelling out every string interpolation
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Contains extensive pseudocode/JavaScript that Claude could generate from a brief description. The multi-round questionnaire options, helper functions, and summary templates are spelled out in exhaustive detail that could be condensed to a fraction of the size. Much of this is implementation detail that doesn't need to be in a skill file. | 1 / 3 |
Actionability | Provides concrete code examples and specific commands, but the JavaScript is pseudocode-like (using undefined functions like `request_user_input`, `spawn_agent`, `Write`, `Read`, `file_exists`) rather than truly executable code. The flow is detailed but relies on many assumed APIs and tools without documenting their actual interfaces. | 2 / 3 |
Workflow Clarity | The multi-step process is clearly sequenced with an excellent flow diagram, explicit decision points for flags, validation checkpoints (checking existing state, handling partial saves), and error recovery (agent timeout retry, user cancellation handling). The error handling table covers edge cases well. | 3 / 3 |
Progressive Disclosure | Monolithic wall of text with everything inline. The entire implementation of all 7 steps, including all 5 questionnaire rounds with their full option lists, helper functions, and summary templates are all in one file. This content desperately needs to be split — questionnaire rounds, the agent prompt, and helper functions could each be separate referenced files. | 1 / 3 |
Total | 7 / 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 (670 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.