flow-spec

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

Quality

76%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Critical

Do not install without reviewing

Fix and improve this skill with Tessl

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

Quality

Content

77%

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

The skill body is highly actionable and exceptionally clear in its sequenced workflow with explicit validation gates, but it is verbose from repeated enforcement emphasis and monolithic, keeping large template and script blocks inline rather than splitting them into one-level-deep reference files. Reducing redundant directives and externalizing the NLSpec template would improve both conciseness and progressive disclosure.

Suggestions

Cut the redundant enforcement language (e.g., the standalone 'Prohibited Actions' section that restates inline constraints) and consolidate repeated 'MANDATORY/DO NOT PROCEED' emphasis to tighten the token budget.

Externalize the large NLSpec template block (and optionally the bash script snippets) into a reference file (e.g., references/nlspec-template.md) and link to it from a concise overview, achieving one-level-deep progressive disclosure.

Convert the bare backtick reference to skills/blocks/codex-host-adapter.md into a clearly signaled markdown link so navigation is explicit.

Dimension	Reasoning	Score
Conciseness	The procedural content is substantive and useful, but it is padded with repetitive enforcement emphasis ('MANDATORY', 'DO NOT PROCEED', 'CRITICAL', 'PROHIBITED') and a 'Prohibited Actions' section that rehashes constraints already stated inline, so it could be tightened without losing information.	2 / 3
Actionability	Provides concrete, executable bash commands with real script paths, explicit AskUserQuestion parameters, a copy-paste-ready NLSpec template, and specific validation commands, matching the 'fully executable, copy-paste ready' anchor.	3 / 3
Workflow Clarity	An explicit 8-step sequence with mandatory validation gates (Step 5 synthesis verification, Step 7 completeness check), feedback loops in the Error Handling section, and per-step 'DO NOT PROCEED until...' checkpoints matches the top anchor for clear sequencing with validation.	3 / 3
Progressive Disclosure	The body is well-organized into clearly headed sections, but it is a monolithic ~400-line single file with the full NLSpec template and all scripts inline; the single external reference (codex-host-adapter.md) is signaled with a plain backtick path rather than clearly navigable links, so it does not reach the one-level-deep reference ideal.	2 / 3
	Total	10 / 12 Passed

Description

75%

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 well-structured with an explicit 'use when' trigger and a distinct niche, but it relies on the jargon term 'NLSpec' and describes a single core action rather than enumerating multiple concrete capabilities. Tightening trigger vocabulary and listing concrete actions would raise specificity and trigger-term quality.

Suggestions

Replace or supplement the jargon 'NLSpec' with natural terms users would actually say, e.g., 'spec', 'specification', 'requirements document', 'spec out a feature'.

Enumerate concrete actions (e.g., 'gather clarifying inputs, run multi-AI research, synthesize a structured spec, validate completeness') instead of naming only the single 'authoring' action.

Add common phrasing variants like 'write a spec' or 'generate a requirements spec' to broaden trigger coverage.

Dimension	Reasoning	Score
Specificity	Names the domain and primary action ('NLSpec authoring', 'structured specification from multi-AI research and consensus') but lists a single core action rather than multiple distinct concrete actions, fitting the 'names domain and some actions' anchor rather than the 'lists multiple specific actions' level.	2 / 3
Completeness	Explicitly answers both what (NLSpec authoring / structured specification from multi-AI research) and when via an explicit 'use when you need a structured specification' trigger clause, matching the top anchor.	3 / 3
Trigger Term Quality	Includes some natural terms ('structured specification', 'spec') but leans on the proprietary jargon 'NLSpec' and omits common variations a user might say ('write a spec', 'requirements doc', 'spec out a feature'), so it does not reach full natural-keyword coverage.	2 / 3
Distinctiveness Conflict Risk	The 'multi-AI research and consensus' qualification carves out a clear, distinct niche (spec authoring via multi-provider synthesis) that is unlikely to trigger for unrelated skills.	3 / 3
	Total	10 / 12 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: nyldn/claude-octopus
Path: .claude/skills/flow-spec/SKILL.md
Commit: 9f39f0c

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