Feedback on your flow skill

[RichardHightower]

I took a look at your flow skill and wanted to share some thoughts.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 71/100, solid C grade territory. This is based on Anthropic's best practices for skill design. Your strongest area is the Progressive Disclosure Architecture (27/30) — the 9-mode system with intelligent keyword routing is chef's kiss. But you're getting zero points on Spec Compliance (0/15) because of a broken frontmatter block, which is completely fixable and worth +15 points alone.

What's Working Well

• Smart mode architecture - The layering is excellent. You've got 9 specialized modes triggered by keywords like 'taint', 'state machine', 'concurrency', and each one delegates to its own file. That's efficient token usage.
• Rich mode coverage - 14 distinct analysis modes (taint analysis, state machines, dead code detection, etc.) actually solve real problems. The utility score of 17/20 reflects that.
• Clear output templates - Your ASCII diagrams and structured output formats for each mode give users concrete examples they can follow.
• Keyword detection tables - The trigger terms are well-organized and make discoverability straightforward.

The Big One: Fix Your Frontmatter

This is the main thing holding you back. Your SKILL.md frontmatter is malformed YAML and parsing is failing. Look at lines 1-7 — it cuts off mid-way through argument-hint.

Fix: Complete your frontmatter block properly. It should look like:

---
name: flow
description: Trace code execution flows and analyze business logic. Use when asked to "flow", "trace execution", "state machine", "taint analysis", "who calls", or "dead code".
model: opus
allowed-tools: Bash, Glob, Grep, Read, Write
argument-hint: [flow description or entry point, optional mode keyword]
---

Why this matters: Valid frontmatter is non-negotiable. It's how Claude Code discovers and invokes skills. This one fix alone gets you +15 points and brings Spec Compliance from 0/15 to 15/15.

Other Things Worth Fixing

1. Description needs more specificity - Your description should mention the key capabilities (taint analysis, state machines, concurrency detection). Right now it's vague. This helps discoverability and gets you +2 points on ease of use.

2. Mode files are missing TOCs - Files like flow-modes/mode-04-state-machine.md exceed 100 lines but have no table of contents. Add a quick "## Contents" section with 4-5 links to main subsections. That's +1 point.

3. Add error handling guidance - What happens if the entry point isn't found? If grep returns no results? Add a fallback section to help users. Adds +1 point and improves utility.

4. Consolidate redundant examples - Mode 4 has three nearly-identical ASCII diagrams. One well-annotated example is cleaner than three variations. Small win on writing style (+1 point).

Quick Wins

• Fix frontmatter first (+15 points) — this is the blocker
• Expand the description (+2 points) — mention your key modes and triggers
• Add TOC to longer mode files (+1 point) — easy win for navigation
• Single consolidated example (+1 point) — clean up redundant diagrams
• Error handling section (+1 point) — real user value

You're looking at roughly +20 points if you hit these. That gets you to 91/100 and solidly into A territory. The architecture is already there — this is just polish and spec compliance.

---

Checkout your skill here: [SkillzWave.ai](https://skillzwave.ai) | [SpillWave](https://spillwave.com) We have an agentic skill installer that install skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.