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 sufficient specificity about what kind of project, state, or specs are involved. Without these, Claude would struggle to reliably select this skill from a pool of alternatives.
Suggestions
Add an explicit 'Use when...' clause describing trigger scenarios, 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 language and concrete examples of what gets configured (e.g., 'project settings', 'build configuration', 'test specs').
Include common user-facing trigger terms such as 'setup', 'init', 'initialize', 'new project', 'configuration wizard', or 'onboarding'.
| 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.
The skill provides a thorough and well-sequenced workflow for project initialization with clear decision logic and error handling. However, it is extremely verbose—most of the inline JavaScript/pseudocode is implementation detail that inflates the token cost without adding proportional value. The monolithic structure with no progressive disclosure compounds the verbosity problem.
Suggestions
Reduce the body to a concise overview (~100 lines) covering the flow, flags, decision logic, and key rules, then move questionnaire option sets, agent prompts, and helper functions into separate referenced files.
Remove or drastically shorten the inline JavaScript examples—describe the behavior and constraints concisely rather than providing full pseudocode implementations that aren't directly executable.
Split the questionnaire round definitions into a separate reference file (e.g., QUESTIONNAIRE_ROUNDS.md) since they are the bulk of the content and are repetitive in structure.
Clarify the actual API surface (spawn_agent, request_user_input, Write, Read, Bash) with a brief reference section or link, so the pseudocode becomes truly actionable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Contains extensive pseudocode/JavaScript that Claude could generate from a concise specification. The multi-round questionnaire options, helper functions, and summary templates are spelled out in exhaustive detail when a compact description of the flow and key rules would suffice. Much of this is implementation detail Claude doesn't need verbatim. | 1 / 3 |
Actionability | Provides concrete code examples and a detailed step-by-step process, but the code is pseudocode-like JavaScript that mixes real APIs (spawn_agent, Bash) with invented helpers (functions.request_user_input, Write, Read, file_exists) whose exact signatures and behavior are unclear. Not truly copy-paste executable without significant interpretation. | 2 / 3 |
Workflow Clarity | The multi-step process is clearly sequenced with an ASCII flow diagram, explicit flag parsing, decision branching, numbered steps, and per-round processing instructions. Error handling is documented in a table, and validation checkpoints (check existing state, deduplication, rebuild spec index) are present throughout. | 3 / 3 |
Progressive Disclosure | All content is in a single monolithic file with no references to supporting documents. The questionnaire rounds, helper functions, summary templates, and agent prompts are all inlined, creating a massive wall of text. Content like the agent prompt, questionnaire option sets, and file-writing helpers should be split into 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 (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
227244f
- 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.