spec-collaboration

Interactive and collaborative specification drafting skill for FinanceHub. Enforces one-question-at-a-time decision making, progressive spec document updates, and architectural validation gates.

Quality

61%

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 ./.agents/skills/spec-collaboration/SKILL.md

Quality

Content

65%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 is lean, well-structured, and clearly sequenced, but its guidance stays at a high level — no spec template, example question, or concrete validation step — which limits actionability and workflow clarity. Adding a minimal spec skeleton and a concrete validation/feedback loop would resolve the two weakest dimensions.

Suggestions

Include a minimal spec document template (section headings) inline so Claude knows exactly what to populate in .agents/specs/<spec-name>.md.

Show one concrete ask_question example (e.g. a sample decision question with options and rationale) to make the 'one question at a time' rule executable.

Define the sign-off validation as a concrete, runnable check with a validate→fix→retry loop (e.g. 're-read spec for unanswered questions; if any remain, ask another question before sign-off') rather than a vague 'empirical or architectural check'.

Dimension	Reasoning	Score
Conciseness	The ~25-line body is lean and does not explain concepts Claude already knows; only the opening sentence ("This skill governs the interactive process of crafting technical specifications...") lightly duplicates the frontmatter, a minor trim opportunity that keeps it just below a 5.	4 / 5
Actionability	It names a concrete path (".agents/specs/<spec-name>.md") and tool ("ask_question"), but offers no spec template, example question, or example ask_question call, leaving key execution details missing as expected for an instruction skill.	3 / 5
Workflow Clarity	The ASCII flow ([Identify Goal] ──> ... ──> [Sign-off]) gives a clear sequence and a validation/sign-off gate, but the validation is vague ("an empirical check or architectural alignment check") with no concrete checkpoint or validate→fix→retry feedback loop.	3 / 5
Progressive Disclosure	At under 50 lines with no bundle files and no need for external references, the well-organized sections (Core Principles, Spec Workflow Steps) meet the simple-skill exception for a top score.	5 / 5
	Total	15 / 20 Passed

Description

58%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.

The description is specific, third-person, and well-scoped to FinanceHub, but it omits any 'Use when...' trigger guidance, which caps completeness and limits trigger-term quality. Adding explicit natural-language trigger phrases would lift the two lowest dimensions.

Suggestions

Append a 'Use when...' clause naming concrete triggers, e.g. 'Use when drafting or revising FinanceHub feature specs, roadmaps, or architectural decisions with the user.'

Add natural synonyms and variations users might say (e.g. 'spec', 'technical spec', 'feature spec', 'roadmap', 'architectural design') to broaden trigger-term coverage.

Optionally name 1-2 more concrete capabilities (e.g. 'produces a versioned spec document', 'runs architectural alignment checks') to push specificity toward comprehensive coverage.

Dimension	Reasoning	Score
Specificity	Quotes "one-question-at-a-time decision making", "progressive spec document updates", and "architectural validation gates" — several concrete, distinct behaviors rather than generic verbs, though coverage of the full spec-drafting surface is narrow enough to stop short of comprehensive.	4 / 5
Completeness	The 'what' is clear ("specification drafting skill ... Enforces one-question-at-a-time decision making"), but there is no 'when' clause or equivalent explicit trigger guidance, which the guidelines cap at 3.	3 / 5
Trigger Term Quality	Natural terms like "specification drafting" and "spec" appear, but there are no explicit trigger phrases, few synonyms, and no 'Use when...' guidance, leaving common variations users would actually say uncovered.	3 / 5
Distinctiveness Conflict Risk	Scoping to "FinanceHub" and the distinctive one-question-at-a-time enforcement give it a clear niche with only minor overlap risk against other spec/planning skills, though the absent trigger guidance slightly weakens distinctiveness.	4 / 5
	Total	14 / 20 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: JoseMD12/finance-hub
Path: .agents/skills/spec-collaboration/SKILL.md
Commit: a8dbf2a

Reviewed: 3 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.