CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

flow-spec

NLSpec authoring — use when you need a structured specification from multi-AI research and consensus

Quality

70%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/flow-spec/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

70%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 an exceptionally well-gated, highly actionable workflow: explicit sequencing, two validation gates, per-step error recovery, and concrete executable bash throughout. Its weaknesses are token weight from triplicated enforcement prose and a monolithic structure that inlines a large template and dispatch script instead of splitting them into reference files.

Suggestions

Consolidate the prohibition/enforcement content (Step 4's CRITICAL list, the per-step 'DO NOT PROCEED' boilerplate, Error Handling, and the Prohibited Actions section) into a single rules section, relying on the frontmatter validation_gates for enforcement — this would cut a substantial fraction of tokens without losing operational content.

Move the NLSpec template and the Step 6.5 challenge-dispatch script into references/ files (e.g., references/nlspec-template.md, references/challenge-dispatch.sh) linked from the corresponding steps, keeping SKILL.md as the workflow overview.

Provide the concrete invocation (path, arguments, example output) for feature-clarifications.py collect in Step 7 and an explicit command or Write-tool instruction for staging spec-draft.md in Step 6.5.

DimensionReasoningScore

Conciseness

The ~480-line body contains no explanations of concepts Claude already knows and is dense with task-specific operational content, but the same governance rules are stated three or more times: Step 4's 'CRITICAL: You are PROHIBITED from' list, Error Handling's 'DO NOT substitute with direct research', and Prohibited Actions' 'CANNOT substitute direct Claude analysis for probe results' all repeat the orchestrate.sh prohibition, and 'You MUST use the Bash tool to invoke orchestrate.sh' appears twice within Step 4 alone. Not 2 because every section carries real instructions rather than padding about known concepts; not 4 because the triplicated enforcement prose and per-step 'DO NOT PROCEED' boilerplate are clear tightening targets.

3 / 5

Actionability

Most guidance is copy-paste executable: the Step 5 receipt gate "jq -e --arg run \"$SPEC_RESEARCH_RUN\" '.run_id == $run and .degraded == false'", exact AskUserQuestion option sets ('Options: End Users, Developers, Admins, External Services, Other'), concrete provider-check bash, and a full NLSpec template. Not 5 because a few operations are prose-only — 'Calculate filled and decidable scores with feature-clarifications.py collect' gives no invocation syntax or path, and staging spec-draft.md in Step 6.5 is described but never commanded; not 3 because the vast majority of steps have complete, executable commands with fallbacks.

4 / 5

Workflow Clarity

Eight explicitly sequenced steps each end with a blocking gate ('DO NOT PROCEED TO STEP 4 until state and feature context are read'), there are two dedicated validation checkpoints (Step 5's run-receipt check and Step 7's six-criteria completeness list), frontmatter validation_gates reinforce them, and Error Handling maps every step's failure to a recovery action. This matches the top anchor: explicit validation steps, feedback loops for error recovery, and checklists for a complex process.

5 / 5

Progressive Disclosure

The skill is a single ~480-line file with no bundle files at all; internal step-based headers make it navigable, but content that could live one level deep in references is inlined — the ~55-line 'NLSpec Template' block and the ~35-line Step 6.5 challenge-dispatch script. Not 4 because SKILL.md is a full operational manual rather than an overview pointing to detail files; not 2 because sections are well organized and nothing is buried or nested.

3 / 5

Total

15

/

20

Passed

Description

57%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 explicitly answers both what and when and occupies a distinctive niche, but it is thin on concrete actions, uses second-person trigger phrasing, and offers sparse natural trigger terms. It reads like a niche ecosystem command shorthand rather than a self-describing capability statement.

Suggestions

Rewrite in third person with fuller action coverage, e.g.: 'Authors NLSpec structured specifications — purpose, actors, behaviors, constraints, and acceptance targets — synthesized from multi-AI research and cross-provider consensus.'

Add natural trigger variations users would actually say, e.g.: 'Use when the user asks for a spec, specification, requirements document, or structured feature definition, or wants multi-AI research before implementation.'

DimensionReasoningScore

Specificity

The description offers a single action verb — 'NLSpec authoring' — plus output context ('a structured specification from multi-AI research and consensus'), which names the domain with one concrete action (base 3), but the trigger clause 'use when you need' uses second-person voice, which the guidelines penalize by reducing specificity by 1. Not 3 because the voice penalty applies and action coverage is a single verb; not 1 because the domain and deliverable are concretely named rather than abstract.

2 / 5

Completeness

Both elements are explicit: the what is 'NLSpec authoring' producing 'a structured specification from multi-AI research and consensus', and the when is the 'use when you need a structured specification' clause, so the missing-trigger cap at 3 does not apply. Not 5 because the what leans on the undefined term 'NLSpec' and the when is a single generic condition rather than concrete trigger phrases; not 3 because both what and when are clearly and explicitly present.

4 / 5

Trigger Term Quality

'specification' and 'structured specification' are natural terms a user would say, but common variations and synonyms ('spec', 'requirements', 'write a spec', 'feature spec') are absent, and 'multi-AI research' and 'consensus' are ecosystem jargon rather than phrases users naturally utter. Not 4 because keyword coverage misses several everyday variations; not 2 because 'specification' is a genuinely natural, relevant keyword rather than generic filler.

3 / 5

Distinctiveness Conflict Risk

'NLSpec' and 'multi-AI research and consensus' carve a clear niche with distinctive framing that few skills would share. Not 5 because 'structured specification' alone sits in the broader spec/requirements-writing space where similar skills could overlap; not 3 because the multi-AI research mechanism meaningfully disambiguates it from ordinary spec-writing skills.

4 / 5

Total

13

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository

nyldn/claude-octopus

Path

.claude/skills/flow-spec/SKILL.md

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.