From flow
Analyze and improve Claude Code skills. Use when creating new skills, reviewing existing skills, or when a skill isn't working as expected. Teaches skill design strategy, not just checklist compliance.
How this skill is triggered — by the user, by Claude, or both
Slash command
/flow:improve-skillThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Skills are teaching documents that shape how Claude approaches problems. A well-designed skill doesn't just list steps—it transfers understanding.
Skills are teaching documents that shape how Claude approaches problems. A well-designed skill doesn't just list steps—it transfers understanding.
These are ordered by impact. Fix them in order.
The description field isn't metadata—it's how Claude decides whether to auto-invoke your skill.
What happens without it: Claude never uses the skill unless you type /skill-name.
What happens with a weak one: Claude uses it at wrong times or ignores it when relevant.
A good description answers three questions:
# WEAK - Claude doesn't know when to use it
description: Analyzes code quality
# STRONG - Clear triggers
description: Review code for slop and over-engineering. Use when code feels bloated, reviewing AI-generated code, or before commits.
Test: Read your description. Would Claude know to invoke this skill if a user said "this feels bloated"?
The dynamic context syntax (exclamation mark + backtick-wrapped command) runs shell commands before Claude sees the skill content.
Without it: Claude's first action is gathering context (reading files, checking git status). Wastes turns.
With it: Claude begins with situational awareness. Can start analyzing immediately.
## Current State
Git status: !‹git status --short 2>/dev/null | head -20›
Recent changes: !‹git diff --stat HEAD~1 2>/dev/null | tail -10›
(In actual skills, use exclamation mark + backtick-wrapped command instead of angle brackets.)
Strategic question: What context does Claude need to start working, not just start asking?
SKILL.md should contain workflow (what to do). Supporting files should contain reference (what to know).
The split isn't about line count. It's about role:
| File | Contains | Loaded |
|---|---|---|
| SKILL.md | Steps, decisions, flow | Always |
| reference.md | Checklists, rules, patterns | When Claude needs detail |
| examples.md | Before/after, edge cases | When Claude needs clarity |
Anti-pattern: 800-line SKILL.md with everything inline. Claude loads all of it every time, even for simple invocations.
Pattern: 100-line SKILL.md that says "See red-flags.md for complete checklist" and Claude loads it only when doing detailed analysis.
Specifying allowed-tools removes permission prompts from the workflow.
Without it: "Can I run git diff?" "Can I read this file?" "Can I run tests?" — friction on every action.
With it: Claude flows through the workflow without interruption.
# Analysis skill (read-only)
allowed-tools: Read, Grep, Glob, Bash(git diff *), Bash(git status *)
# Modification skill (needs write + test)
allowed-tools: Read, Write, Edit, Bash(git add *), Bash(npm test *)
Scope narrowly: Bash(git *) not Bash(*). Permissions should match the skill's actual needs.
A skill that works but doesn't explain its reasoning will degrade over time:
Include the why:
# BAD - Just steps
## Step 3
Score each function using the decision framework.
# GOOD - Steps with reasoning
## Step 3: Score with Decision Framework
For every function, class, parameter, and abstraction, score it.
Only code scoring > 0 belongs.
**Why this works:** Forces explicit justification. "Best practice" and
"might need it later" are the most common sources of bloat—they score
negative to counteract this bias.
When a skill isn't working, diagnose in order:
| Symptom | Likely Cause | Fix |
|---|---|---|
| Claude never auto-invokes | Missing/weak description | Rewrite description with triggers |
| Claude invokes at wrong times | Description too broad | Add specific trigger scenarios |
| Claude asks permission constantly | Missing allowed-tools | Add scoped tool permissions |
| Skill feels slow to start | No dynamic context | Add dynamic context commands |
| Claude misses edge cases | No reference material | Split checklist to supporting file |
| Inconsistent behavior | No reasoning in skill | Add "why" to key decisions |
If $ARGUMENTS provided: Find that skill
Otherwise: List available skills
Use Glob to list personal skills at ~/.claude/skills/*/SKILL.md
Read SKILL.md and answer:
Work through the five levers in order. Stop at the first broken one—that's your highest-leverage fix.
## Skill Analysis: [name]
### Current State
[Scores for each dimension]
### Highest-Leverage Fix
[The one thing that would most improve this skill]
### Additional Improvements
[Other issues, in priority order]
### Rewritten Frontmatter
[If applicable]
On "fix it" / "apply":
cp SKILL.md SKILL.md.baknpx claudepluginhub kurioscreative/skills --plugin flowCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.