flow-spec

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

Quality

71%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

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

Quality

Content

73%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 skill delivers a well-sequenced, validated workflow with strong actionability via concrete scripts and a complete template. Its main weakness is verbosity from repeated enforcement language and a monolithic structure that could benefit from offloading detail to reference files.

Suggestions

Consolidate the repeated "DO NOT PROCEED" / "CANNOT" / "PROHIBITED" language into a single enforcement section to reduce padding.

Move the full NLSpec template and the adversarial-review prompt into a reference file, keeping SKILL.md as an overview with a one-level-deep pointer.

Trim restated justifications under each CRITICAL/PROHIBITED bullet since the enforcement intent is already conveyed by the gates.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient with concrete commands, but repeated emphasis ("MANDATORY", "DO NOT PROCEED", "CANNOT", "PROHIBITED") restated across step guards and a dedicated Prohibited Actions section adds noticeable padding that could be tightened.	3 / 5
Actionability	Concrete, mostly copy-paste-ready bash commands (check-providers.sh, state-manager.sh, orchestrate.sh) and a full NLSpec template are provided, with only minor placeholder gaps like <project description>.	4 / 5
Workflow Clarity	An explicit 8-step sequence with blocking validation gates (Steps 5 and 7), per-step "DO NOT PROCEED" checkpoints, and a feedback-oriented Error Handling section provides clear validation and recovery loops.	5 / 5
Progressive Disclosure	Content is well-sectioned by numbered steps with no nested references, but the ~400-line body is monolithic with the full template and prohibitions inlined where extraction could help; no bundle files exist to offload detail.	4 / 5
	Total	16 / 20 Passed

Description

70%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 third-person, distinguishes the skill via a coined term, and answers both what and when, though with moderate rather than comprehensive specificity. Trigger phrasing is solid but could name more natural synonyms.

Suggestions

Add a short list of concrete authoring actions (e.g., 'elicits actors, behaviors, and constraints') to raise specificity.

Expand the 'when' clause with concrete situational triggers users would actually say (e.g., 'use when starting a feature from scratch or needing a testable spec').

Include natural synonyms like 'spec', 'requirements', or 'spec sheet' in the description itself rather than only in aliases.

Dimension	Reasoning	Score
Specificity	"NLSpec authoring" names the domain and "structured specification from multi-AI research and consensus" names a concrete output, but no enumerated concrete actions are listed, so coverage is not comprehensive.	3 / 5
Completeness	It states both what ("NLSpec authoring") and when ("use when you need a structured specification from multi-AI research and consensus"), but the trigger could be more explicit with concrete situational cues.	4 / 5
Trigger Term Quality	"structured specification", "multi-AI research", and "consensus" are reasonably natural phrases, and aliases (spec, nlspec, specification) broaden coverage, though a few common synonyms are absent.	4 / 5
Distinctiveness Conflict Risk	The coined term "NLSpec" plus "multi-AI research and consensus" carves a fairly distinct niche, with only minor overlap risk against generic spec-writing skills.	4 / 5
	Total	15 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
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
Commit: f9b8c92

Reviewed: ~11 hours 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.