flow-spec

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

Quality

66%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

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 skill body is a well-sequenced, strongly validated orchestration workflow with mostly copy-paste-ready commands — workflow clarity is excellent. Its weaknesses are token padding from repetitive enforcement language and a monolithic structure that inlines large template/prompt blocks instead of splitting them into reference files.

Suggestions

Consolidate the repeated enforcement boilerplate: state the execution contract once (or rely on the frontmatter's execution_mode/validation_gates) instead of repeating "MANDATORY / DO NOT PROCEED" after every step, and merge the Step 4 PROHIBITED list into the single "Prohibited Actions" section.

Move the 55-line NLSpec template and the adversarial-review prompts into reference files (e.g. references/nlspec-template.md, references/adversarial-review.md) linked from the relevant steps, slimming the main file and improving progressive disclosure.

Replace instruction-shaped pseudo-snippets (AskUserQuestion, Agent spawn, EnterPlanMode) with concrete call examples or exact tool schemas so the guidance is fully copy-paste executable.

Dimension	Reasoning	Score
Conciseness	The body carries genuinely necessary material (concrete bash commands, the NLSpec template, validation criteria) but is padded with repeated enforcement boilerplate: "MANDATORY - CANNOT SKIP", "DO NOT PROCEED TO STEP X until..." after every step, a "STOP - SKILL ALREADY LOADED" header, a Step 4 PROHIBITED list, and a separate "Prohibited Actions" section that restates the same prohibitions. Not a 4: the duplication of prohibition messaging alone is a noticeable amount of tokens that could be trimmed. Not a 2: the bulk of the content is operational, not explanation of concepts Claude already knows.	3 / 5
Actionability	Most guidance is executable: exact bash commands for provider checks, state-manager calls, the orchestrate.sh probe with query structure, the find-based synthesis validation, a complete NLSpec template, and per-step error handling. Not a 5: several blocks are instruction-shaped rather than concrete — the "AskUserQuestion with these questions:" snippet, the pseudo Agent(...) spawn call in Step 6.5, "EnterPlanMode with the NLSpec content as the plan body", and Step 8's commented-out write placeholder. Not a 3: these gaps are minor and the concrete commands are copy-paste ready.	4 / 5
Workflow Clarity	The 8-step sequence is explicitly ordered with two hard validation gates (Step 5 synthesis-file check with exit-on-failure, Step 7 completeness scoring against six enumerated criteria), per-step error recovery in the "Error Handling" section, and clear feedback loops (validation fail -> report logs -> do not proceed -> no silent fallback). This matches the top anchor: clear sequence, explicit validation steps, feedback loops, and checklists.	5 / 5
Progressive Disclosure	The body is well-sectioned with headers, but it is a monolithic ~420-line file with no bundle files (no references/, scripts/, or assets/ exist) and no internal pointers — the 55-line NLSpec template, the adversarial-review prompt text, and the banner text are all inlined where reference files would keep SKILL.md lean. Not a 4: content that plausibly belongs in a separate file (the template and review prompts) is inlined with no navigation structure. Not a 2: sections are clearly headed and logically ordered rather than being a wall of text.	3 / 5
	Total	15 / 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 is concise, third-person, and has both a what and an explicit use-when clause, but it leans on the unexplained jargon term "NLSpec" and its trigger vocabulary is narrow. It reads more like a label than a description of concrete capabilities, which limits specificity and natural trigger matching.

Suggestions

Expand the what-clause with concrete outputs, e.g. "Generates structured NLSpec specifications (actors, behaviors, constraints, acceptance targets) synthesized from multi-AI research" — this raises specificity and unpacks the jargon.

Broaden trigger terms to natural user phrasings: "Use when the user asks to write a spec, spec out a system, define requirements, or produce a specification document."

Clarify what NLSpec means (natural-language specification) in the description itself so users who don't know the term can still match it.

Dimension	Reasoning	Score
Specificity	"NLSpec authoring" names the domain and one concrete action (authoring a structured specification from multi-AI research and consensus), which is adequate for a single-purpose skill but leaves the actual capability surface vague — NLSpec is jargon the description never unpacks (actors, behaviors, constraints, acceptance targets). Not a 4: it does not list several specific actions like the "extracts text, fills forms, converts pages" example. Not a 2: the action named is specific and outcome-oriented rather than generic processing.	3 / 5
Completeness	Both what ("NLSpec authoring ... structured specification from multi-AI research and consensus") and when ("use when you need a structured specification...") are explicitly present. Not a 5: the when-clause largely restates the what ("when you need a structured specification") rather than giving concrete trigger phrases like "use when the user asks to spec out a system or write requirements". Not a 3: the when-clause is explicit, not merely implied.	4 / 5
Trigger Term Quality	Trigger terms include "structured specification", "multi-AI research", and "consensus", plus the aliases spec/nlspec/specification in frontmatter, but common user phrasings like "write a spec", "requirements", "spec out", or "design document" are absent. Not a 4: keyword coverage is thin relative to the natural vocabulary users would use for specification work. Not a 2: the terms present are relevant to the domain rather than generic filler.	3 / 5
Distinctiveness Conflict Risk	The NLSpec/multi-AI-consensus framing carves out a distinct niche that is unlikely to fire for unrelated skills. Not a 5: "structured specification" overlaps with general planning/requirements skills, and a user asking for a plain spec without multi-AI framing could still reasonably trigger this. Not a 3: it is more distinctive than the "Works with document files" level of overlap.	4 / 5
	Total	14 / 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: 0093dab

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