spec-setup
Initialize project-level state and configure specs via interactive questionnaire.
32
28%
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-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, making it unclear when Claude should choose this skill. The terms used are unlikely to match natural user language, reducing discoverability.
Suggestions
Add a 'Use when...' clause with natural trigger terms, e.g., 'Use when the user wants to set up a new project, initialize configuration, or run a project setup wizard.'
Replace jargon like 'project-level state' and 'configure specs' with concrete, user-facing language describing what is actually being configured (e.g., 'project settings', 'build configuration', 'test specifications').
Include common natural keywords users might say, such as 'setup', 'init', 'new project', 'configure', 'onboarding', or 'project initialization'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names two actions ('initialize project-level state' and 'configure specs') and mentions a mechanism ('interactive questionnaire'), but the actions are somewhat abstract—'project-level state' and 'specs' are not concrete enough to fully understand what is being configured. | 2 / 3 |
Completeness | It describes a vague 'what' but completely lacks a 'when' clause or any explicit trigger guidance. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'what' itself is weak enough to warrant a 1. | 1 / 3 |
Trigger Term Quality | The terms 'project-level state', 'configure specs', and 'interactive questionnaire' are technical jargon that users are unlikely to naturally say. Missing common trigger terms like 'setup', 'init', 'project config', 'onboarding', or 'project settings'. | 1 / 3 |
Distinctiveness Conflict Risk | The mention of 'interactive questionnaire' and 'project-level state' provides some distinctiveness, but 'configure specs' and 'initialize' are generic enough to overlap with other 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 trees, and error handling, but is severely undermined by extreme verbosity and poor progressive disclosure. The ~400+ line monolithic document includes extensive pseudocode for questionnaire options, helper functions, and output templates that could be dramatically condensed or split into referenced files. The code examples fall in an awkward middle ground — too detailed to be concise guidance but not truly executable due to undefined helper functions.
Suggestions
Reduce the document to ~100-150 lines by extracting the questionnaire round details, language-specific options, and helper functions into separate referenced files (e.g., QUESTIONNAIRE_ROUNDS.md, HELPERS.md)
Replace the extensive pseudocode with a concise description of the pattern (e.g., 'Generate 5 rounds of project-aware questions using request_user_input, processing answers after each round') and move detailed examples to a reference file
Either make the code examples truly executable with proper imports and function definitions, or replace them with concise algorithmic descriptions that Claude can implement
Add bundle files for the referenced schema (project-tech-schema.json) and create separate reference documents for the questionnaire configuration and answer processing rules
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Contains extensive pseudocode/JavaScript that explains implementation details Claude could infer. The multi-round questionnaire options, helper functions, and summary templates are exhaustively spelled out when a more concise pattern description would suffice. Much of the code is illustrative rather than executable (uses undefined functions like `functions.request_user_input`, `Write`, `Read`, `file_exists`). | 1 / 3 |
Actionability | Provides substantial concrete guidance with code examples and clear step sequences, but the code is pseudocode-like rather than truly executable — it mixes JavaScript syntax with undefined helper functions (`Write`, `Read`, `Bash`, `spawn_agent`, `functions.request_user_input`) and uses inconsistent patterns. The flow is detailed but not copy-paste ready. | 2 / 3 |
Workflow Clarity | The multi-step process is clearly sequenced with an excellent ASCII flow diagram, explicit decision points for flags, validation checkpoints (checking existing state, deduplication), error handling table, and feedback loops (agent timeout -> status probe -> force finalize -> close). The questionnaire has clear round-by-round processing with explicit 'process answers before next round' instruction. | 3 / 3 |
Progressive Disclosure | The entire implementation is inlined in a single monolithic file with no references to supporting documents. No bundle files are provided despite references to schemas (project-tech-schema.json), external tools (ccw, cli-explore-agent), and related commands. Content that could be split into separate reference files (questionnaire options, helper functions, schema definitions) is all inline, creating a wall of text. | 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 (679 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.