CtrlK
BlogDocsLog inGet started
Tessl Logo

flow-spec

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

56

Quality

63%

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

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.

A strongly structured, highly actionable enforced workflow with real validation gates and error feedback loops. Its weaknesses are monolithic structure with an unverifiable cross-reference, and substantial redundant enforcement framing that inflates token cost without adding information.

Suggestions

Deduplicate enforcement rules: keep one canonical gate per step and consolidate 'Prohibited Actions' and per-step 'DO NOT PROCEED' blocks into a single short contract — the same prohibitions are currently stated 2-3 times.

Move the NLSpec template and the provider-banner/state snippets into references/ files (e.g., references/nlspec-template.md) and link them from the step, turning the body into a lean overview.

Fix or inline the 'skills/blocks/codex-host-adapter.md' reference — it does not exist in this bundle, so a host reading it cannot resolve host tool equivalents.

DimensionReasoningScore

Conciseness

The core material (bash commands, question sets, NLSpec template, validation checks) is efficient and teaches nothing Claude already knows, but enforcement language is heavily padded: each step repeats a 'DO NOT PROCEED UNTIL X' gate, and the same prohibitions are restated in 'Error Handling', 'Prohibited Actions', and inline 'CRITICAL: You are PROHIBITED' blocks. This is 'mostly efficient but could be tightened'; not 2 because the verbosity is redundant framing rather than concept explanation, though it is close to the boundary.

3 / 5

Actionability

Concrete, mostly copy-paste-ready guidance throughout: exact bash invocations for state-manager.sh and orchestrate.sh, a fully specified AskUserQuestion block, an executable completeness-check recipe, and a complete NLSpec template. Not 5 because of minor gaps: '<paste NLSpec content here>' inside the bash heredoc, the Agent(...) and EnterPlanMode blocks are descriptive pseudocode, and Step 7's completeness check is narrated rather than scripted.

4 / 5

Workflow Clarity

An explicit 8-step numbered sequence with dedicated validation gates (Step 2 provider availability, Step 5 synthesis-file verification with failure handling, Step 7 completeness scoring), per-step blocking rules, error-recovery guidance for every step, and a final checklist-style summary. This matches 'clear sequence with explicit validation steps; feedback loops for error recovery; checklists for complex processes.'

5 / 5

Progressive Disclosure

Section structure is clear (### STEP headers), but the skill is a ~400-line monolith with no bundle files at all — the NLSpec template, provider banner, and state-management snippets are all inlined where they could live in reference files. The one external pointer, 'skills/blocks/codex-host-adapter.md', is not present in the bundle, so it is effectively a dangling reference. This fits 'some structure but content that should be separate is inline'; not 4 because nothing is actually offloaded to verifiable files.

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 has an explicit, well-formed 'Use when' trigger and a distinctive niche, but the 'what' is a domain label rather than a statement of concrete capabilities. Expanding it to name the artifact and its sections would lift both specificity and completeness.

Suggestions

State the concrete output and its parts, e.g., 'Generates a structured NLSpec (actors, behaviors, constraints, dependencies, acceptance criteria) from multi-AI research and consensus.'

Add natural trigger synonyms users would actually say: 'write a spec', 'specification document', 'requirements', 'define the system before building'.

Briefly gloss what NLSpec is (the term is project-internal and may not be recognized by users scanning the skill list).

DimensionReasoningScore

Specificity

The description names the domain ("NLSPEC authoring") but lists no concrete actions — it never says what authoring produces (e.g., generates specs defining actors, behaviors, constraints, acceptance criteria). This matches the anchor 'Names the domain but actions are minimal or generic' rather than 3, which requires 1-2 concrete actions.

2 / 5

Completeness

Both parts are present: the 'what' ("NLSPEC authoring") and an explicit 'when' ("use when you need a structured specification from multi-AI research and consensus"). It is not 5 because the 'what' is a bare domain label without concrete capability statements, and not 3 because the 'when' is explicit rather than weakly implied.

4 / 5

Trigger Term Quality

"structured specification", "research", "consensus" are relevant keywords a user might say, but common variations are missing — no "spec", "write a spec", "requirements", "design doc", or file-format triggers. This fits 'Some relevant keywords but missing common variations or synonyms'; not 4 because natural phrasing coverage is thin.

3 / 5

Distinctiveness Conflict Risk

"NLSPEC" and "multi-AI research and consensus" carve a fairly distinct niche with low collision risk against generic research or writing skills. Not 5 because "research" and "specification" alone are broad enough to overlap with a plain research or docs skill if a sibling skill exists.

4 / 5

Total

13

/

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