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

68%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

58%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 content is an extremely actionable, well-sequenced orchestration workflow with genuine validation gates and error-recovery loops, but it is held back by heavy repetitive mandate/prohibition framing and a monolithic structure with no bundle files and one dangling referenced path. Splitting the template and defensive bash blocks into reference files and trimming the redundant enforcement language would improve it substantially.

Suggestions

Move the full NLSpec template, the Step 3 feature-context validation block, and the Step 6.5 challenge-dispatch script into references/ files (e.g., references/nlspec-template.md, references/feature-context.sh) and link them from SKILL.md to shrink the monolithic 470-line body.

Remove or fix the dangling reference to skills/blocks/codex-host-adapter.md — the file does not exist in the bundle — and either bundle the host-adapter guidance or drop the pointer.

Trim the redundant enforcement framing: the repeated per-step "DO NOT PROCEED TO STEP X until..." gates, the "STOP - SKILL ALREADY LOADED" banner, and the Prohibited Actions section that restates prohibitions already stated inline in Steps 4-7.

DimensionReasoningScore

Conciseness

The ~470-line body has several padded/redundant passages: "STOP - SKILL ALREADY LOADED / DO NOT call Skill() again. DO NOT load any more skills.", the "EXECUTION CONTRACT (MANDATORY - CANNOT SKIP)" / "ENFORCED execution mode" framing, a repeated "DO NOT PROCEED TO STEP X until..." gate after every step, a 25-line defensive jq validation block in Step 3, and a Prohibited Actions section that restates prohibitions already asserted inline in Steps 4-7. This matches the 'noticeably verbose; several unnecessary explanations or padded sections' anchor. Not 1 because nearly all content is load-bearing procedural instruction rather than concepts Claude already knows; not 3 because the redundancy exceeds minor trimmable instances.

2 / 5

Actionability

The guidance is overwhelmingly concrete and executable: exact orchestrate.sh probe invocations with environment variables, exact state-manager.sh and feature-workflow.sh commands, a jq receipt check keyed on the exact run ID, a full NLSpec markdown template, and a concrete save command. Minor gaps keep it at 4 rather than 5: interpolated placeholders ("<project name>", "<actors>", "<complexity class>") require manual substitution, the workflow depends on external plugin scripts (including a sourced scripts/lib/result-file.sh) not present in this bundle, and the Agent() Sonnet fallback is written as a schematic call rather than literal code.

4 / 5

Workflow Clarity

The 8-step sequence is explicitly numbered with mandatory validation gates at Steps 2 (provider availability), 5 (accepted-synthesis receipt with run-ID match), and 7 (six-section completeness check plus a scoring tool), per-step error handling with feedback loops ("If validation fails: report, show logs, DO NOT proceed"), and a final summary checklist of saved artifacts and next steps. This matches the 5 anchor: clear sequence, explicit validation steps, error-recovery loops, and a checklist.

5 / 5

Progressive Disclosure

The body is a monolithic ~470-line SKILL.md with no bundle files at all — no references/, scripts/, or assets/ directories exist — and it cites "skills/blocks/codex-host-adapter.md", a path not present in the bundle, plus many scripts under $OCTO_ROOT and ~/.claude-octopus that live outside the skill. Large content that clearly belongs in separate files (the full NLSpec template, the Step 3 feature-context validation block, the Step 6.5 challenge-dispatch script) is inlined, matching the anchor 'content that clearly belongs in separate files is inlined'. Not 1 because the numbered steps and headers make the file navigable despite its size; not 3 because there are no real reference files to organize around and one referenced path dangles.

2 / 5

Total

13

/

20

Passed

Description

62%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 correctly pairs a what with an explicit 'use when' clause and occupies a distinct niche, but it is thin on concrete actions and leans on project jargon ("NLSpec", "multi-AI research and consensus") rather than natural user trigger phrases. A stronger version would name the concrete operations and add synonyms users would actually say.

Suggestions

List 2-3 concrete actions (e.g., 'interviews the user for actors/constraints, runs multi-provider research, synthesizes a testable NLSpec document') so the what is more than a domain label.

Add natural trigger terms and synonyms users would say — 'write a spec', 'specification document', 'requirements spec', 'feature spec' — alongside the current 'structured specification'.

Briefly gloss what an NLSpec is (e.g., 'a structured behavior/actor/constraint specification') so the jargon term does not carry the entire meaning.

DimensionReasoningScore

Specificity

"NLSpec authoring" names the domain and states one concrete deliverable — a "structured specification from multi-AI research and consensus" — matching the anchor of naming the domain plus 1-2 concrete actions. It does not list several specific operations (like extract/fill/merge), which rules out 4, but it goes beyond a bare domain label like "Processes PDF files", ruling out 2.

3 / 5

Completeness

Both parts are explicitly present: the what is "NLSpec authoring — ... structured specification from multi-AI research and consensus" and the when is "use when you need a structured specification from multi-AI research and consensus". The 'when' clause is present but somewhat circular (restates the what) and could name concrete trigger situations, so it matches the 4 anchor rather than the fully explicit 5; the explicit 'use when' wording rules out 3.

4 / 5

Trigger Term Quality

"structured specification" is a natural user phrase, but the headline terms "NLSpec" and "multi-AI research and consensus" are project-specific jargon, and common user phrasings like "write a spec", "requirements", or "spec document" are absent. This fits the 'some relevant keywords but missing common variations or synonyms' anchor rather than the good coverage of 4.

3 / 5

Distinctiveness Conflict Risk

The niche term "NLSpec" plus the multi-AI research/consensus angle make this mostly distinct with only minor overlap risk against generic spec-writing or planning skills triggered by "specification". Not 5 because "structured specification" overlaps with general spec/plan-writing skills; not 3 because the multi-AI consensus framing is distinctive.

4 / 5

Total

14

/

20

Passed

Validation

100%

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

nyldn/claude-octopus

Path

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.