spec-setup

Initialize project-level state and configure specs via interactive questionnaire.

Quality

28%

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-setup/SKILL.md

Quality

Content

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. The ~400+ line document inlines every implementation detail including full questionnaire option lists per language, helper functions, and display templates that should either be in separate files or dramatically condensed. The code examples sit in an uncanny valley between pseudocode and executable code, using undefined APIs without clarifying they're illustrative.

Suggestions

Reduce the document to ~100 lines by extracting questionnaire round details, language-specific options, and helper functions into separate referenced files (e.g., QUESTIONNAIRE_ROUNDS.md, HELPERS.md)

Replace the verbose JavaScript pseudocode with a concise specification of what each round should ask and how answers map to spec files — Claude can generate the implementation from a clear spec

Clarify which APIs are real vs illustrative (e.g., `functions.request_user_input`, `spawn_agent`, `Write`) or replace with actual tool invocations

Move the full summary template strings into a referenced template file rather than inlining them in the skill body

Dimension	Reasoning	Score
Conciseness	Extremely verbose at ~400+ lines. Contains extensive pseudocode/JavaScript that Claude doesn't need spelled out in such detail — dynamic option generation logic, full questionnaire round implementations, helper functions, and summary templates could be dramatically condensed. Much of this is implementation detail that an intelligent agent could derive from a concise specification.	1 / 3
Actionability	Provides concrete code examples and specific commands, but the JavaScript is pseudocode-style (using undefined functions like `functions.request_user_input`, `Write`, `Read`, `file_exists`, `spawn_agent`) rather than truly executable code. The bash commands are concrete and actionable, but the overall implementation mixes real and pseudo APIs.	2 / 3
Workflow Clarity	The multi-step process is clearly sequenced with an excellent flow diagram, explicit decision points for flags (--regenerate, --reset, --skip-specs), validation checkpoints (checking existing state, deduplication), error handling table, and feedback loops (agent timeout -> status probe -> force finalize -> close). The questionnaire rounds are clearly ordered with processing between each round.	3 / 3
Progressive Disclosure	Monolithic wall of text with no bundle files to offload detail into. The entire implementation — all 5 questionnaire rounds with full option lists, helper functions, summary templates, and agent invocation code — is inlined in a single file. The round-by-round questionnaire details, language-specific option generation, and file writing helpers should be in separate referenced files.	1 / 3
	Total	7 / 12 Passed

Description

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 terse and jargon-heavy to serve as an effective skill selector. It lacks a 'Use when...' clause, uses terms users wouldn't naturally say, and doesn't clearly explain what 'project-level state' or 'specs' refer to concretely.

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 'specs' with concrete descriptions of what is being configured (e.g., 'project settings, build configuration, environment variables').

Include natural keywords users would say such as 'setup', 'init', 'configure project', 'new project', 'project wizard', or 'onboarding'.

Dimension	Reasoning	Score
Specificity	Names two actions ('initialize project-level state' and 'configure specs') and mentions a method ('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	Provides a partial '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 vague enough to warrant a 1.	1 / 3
Trigger Term Quality	Uses technical jargon like 'project-level state' and 'specs' 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' adds some distinctiveness, but 'initialize project-level state' and 'configure specs' are generic enough to potentially overlap with other project setup or configuration skills.	2 / 3
	Total	6 / 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 (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: 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.