spec-builder

Interactive specification builder for autonomous coding projects. Use when users have vague ideas, need help defining requirements, want to create project specs, or before running autonomous-master.

Quality

67%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/spec-builder/SKILL.md

Quality

Content

42%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body communicates the four-phase flow and discovery questions well, but it is padded with a large ASCII diagram and inline templates that duplicate existing reference files, references a non-existent templates/ directory, and provides no script invocation examples or validation checkpoints. It reads more as a feature overview than an operational instruction file for Claude to execute.

Suggestions

Replace the ~90-line ASCII flow diagram with a short 4-step numbered workflow, moving detail to the existing references; this is the largest conciseness win.

Delete the inline "Project Templates" section (it duplicates references/TEMPLATES.md) and either create the referenced templates/*.md files or remove those broken paths from the Templates section.

Add one concrete checkpoint step, e.g., "Before generating the spec, summarize the collected answers back to the user and confirm" plus a one-line example of how to invoke scripts/spec_builder.py, to close the workflow-clarity and actionability gaps.

Dimension	Reasoning	Score
Conciseness	The body spends ~90 lines on a decorative ASCII "SPEC BUILDER FLOW" diagram, inlines four template blocks that duplicate references/TEMPLATES.md, and includes two long mock-dialogue examples — noticeably verbose with several padded sections. It avoids explaining background concepts Claude already knows, so it does not fall to anchor 1.	2 / 5
Actionability	The core and follow-up discovery-question tables are concrete, but the Scripts section lists bare paths ("scripts/spec_builder.py - Core discovery engine") with no invocation examples, and the specification output is shown only as an illustrative transcript rather than executable guidance or a copy-paste-ready spec format. Some concrete guidance exists, but key execution details are missing, matching anchor 3.	3 / 5
Workflow Clarity	The four phases (discovery, elaboration, technology recommendation, output) are clearly sequenced in the diagram and question tables, but there are no checkpoints: no step to confirm collected answers with the user, nor any validation that the generated spec is complete before handing off to autonomous-master. Sequence present but checkpoints missing matches anchor 3 rather than 4.	3 / 5
Progressive Disclosure	References (QUESTION-BANK.md, TEMPLATES.md, TECH-STACKS.md) and scripts exist and are one level deep with dedicated sections, but the four inline template blocks duplicate content that belongs in those separate files, and the listed templates/saas.md, ecommerce.md, social.md, and internal.md paths do not exist, breaking navigation. This fits anchor 3 (references present but content that should be separate is inline / structural gaps).	3 / 5
	Total	11 / 20 Passed

Description

78%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description with a clear what and an explicit, concrete when-clause in third person. Its main weakness is specificity: it names only one action (building specs) rather than enumerating the concrete operations the skill performs. Trigger coverage is good but misses common synonyms like "requirements gathering" or "write a spec".

Suggestions

List 2-3 concrete actions in the description, e.g., "Asks guided discovery questions, expands features into user stories, and recommends a technology stack, producing a spec ready for autonomous start:"

Add natural trigger synonyms such as "requirements gathering", "write a spec", or "define scope" to broaden matching without adding vagueness.

Dimension	Reasoning	Score
Specificity	"Interactive specification builder for autonomous coding projects" names the domain and the single action of building specs, but lists no further concrete actions (e.g., guided discovery questions, feature elaboration, tech-stack recommendation). It matches anchor 3 (domain + 1-2 concrete actions, not comprehensive) rather than 4, which requires several specific actions.	3 / 5
Completeness	It explicitly answers both what ("Interactive specification builder for autonomous coding projects") and when ("Use when users have vague ideas, need help defining requirements, want to create project specs, or before running autonomous-master") with concrete trigger phrases, matching the anchor-5 example pattern. Not below 5 because neither half is vague or merely implied.	5 / 5
Trigger Term Quality	The when-clause uses natural user phrases — "have vague ideas", "need help defining requirements", "want to create project specs" — that a user would plausibly say. A few natural variants are missing (e.g., "write a spec", "gather requirements", "define scope"), so it fits anchor 4 rather than 5.	4 / 5
Distinctiveness Conflict Risk	The niche (spec creation feeding autonomous-master) is distinct, but the when-triggers "vague ideas" and "need help defining requirements" overlap with general brainstorming/planning skills, fitting anchor 4 (mostly distinct, minor overlap with closely related skills) rather than 5.	4 / 5
	Total	16 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: fernandezbaptiste/Skrillz
Path: skills/spec-builder/SKILL.md
Commit: 93ed392

Reviewed: 14 hours 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.