prompt-audit
Most AI-coding failures trace back to thin prompts. A prompt that takes 30 seconds to write and 2 minutes for Claude to "execute" produces code that takes 2 hours to fix. This skill catches that before it happens.
When to use
Use whenever the user is evaluating, drafting, or about to send a prompt for non-trivial coding work. Triggers include:
- "Is this prompt good?"
- "Audit / review / check my prompt"
- "Will Claude understand this?"
- "How do I improve this prompt?"
- The user pastes a prompt and asks anything about it
- You notice the user is about to send a vague prompt for a complex task — proactively offer to audit it
Don't audit:
- Single-line throwaway prompts the user is happy with
- Pure conversation / clarification messages (not actual task prompts)
The six essential elements
A good coding prompt for non-trivial work has all six. Missing any one drops the success rate noticeably.
| # | Element | What it answers | Why it matters |
|---|
| 1 | Goal | What problem are we solving? Who uses the result? | Without a goal, Claude optimizes the wrong thing |
| 2 | Scope | Which files / modules can change? Which can't? | Without scope, Claude touches things it shouldn't |
| 3 | Existing patterns | What in the codebase should we mimic? | Without patterns, Claude reinvents conventions inconsistently |
| 4 | Constraints | Performance, dependencies, compatibility | Without constraints, Claude makes choices the user won't accept |
| 5 | Verification | What tests prove this is correct? | Without verification, "done" is undefined |
| 6 | Done definition | When can we mark this complete? | Without done, Claude over-builds or under-builds |
Workflow
Step 1 — Parse the prompt
Read the prompt the user shared. Identify which of the 6 elements are present, partially present, or missing. Be honest — "we should follow good patterns" is not a real existing-pattern reference; an actual file path is.
Step 2 — Score each element
For each element, classify as:
- ✅ Clear — concrete, actionable, unambiguous
- ⚠️ Vague — present but too abstract to be useful
- ❌ Missing — not addressed at all
Step 3 — Diagnose with reasons
For each gap, explain to the user why this matters in the specific task at hand — not just generic best-practice scolding. Example:
"Your scope is missing — and because this prompt mentions auth/, Claude will likely modify shared auth middleware that 30+ other endpoints depend on. That's a core-code change that needs explicit human ownership."
Step 4 — Watch for over-constraint too
The opposite failure mode: a prompt that dictates every variable name, every line of pseudocode, every internal step. This makes the model worse, not better. If you see this, flag it:
"Your prompt over-constrains the implementation. The model performs best when given goals + constraints + patterns, then trusted to write the code. Treat the prompt like onboarding a junior — explain what matters, not what to type."
Step 5 — Produce a rewrite
Always produce an improved version, even if the original was decent. Use this structure:
[Goal]
<Who uses this, what done means>
[Scope]
- Can modify: <list>
- Must not modify: <list>
[Existing patterns]
- Mirror <specific file or module>
- Convention: <e.g., service.ts + route.ts + *.test.ts>
[Constraints]
- <Performance, dependencies, compat>
[Verification]
- 3 e2e tests: <happy + 2 errors, described at user level>
- Manual: <if applicable>
[Done]
- <Concrete checklist>
If the user's task isn't big enough to need all six, drop the unused ones rather than padding with placeholders.
Step 6 — Show before/after side by side
End the audit with a direct comparison so the user sees the gain. Example:
Before (6 words): "Add a user activity report endpoint."
After (~250 words): <full structured prompt>
Why the rewrite is better: scope is now explicit, existing pattern named, verification defined, done measurable.
Red flags worth calling out
When you spot any of these in the original prompt, surface them explicitly:
- Touches core code without acknowledging it. "Just add this to the auth middleware..."
- No verification at all. "It should work."
- Vague pronouns. "Make it better." "Fix this." (Better what? This what?)
- No file paths anywhere. Hard to ground without paths.
- Implies multiple PRs in one prompt. "Build the auth flow and the user dashboard and the reporting." Suggest splitting.
- Domain the user clearly doesn't know. Hard to PM a domain you don't understand. Ask: "How will you tell if this is right?"
- Asks the AI to write the spec. "Figure out what we should build." Not Claude's job — that's product work.
Output format
Use this structure for the audit:
## Audit summary
<1-2 sentences: overall verdict>
## Element check
| Element | Status | Notes |
|---|---|---|
| Goal | ✅ / ⚠️ / ❌ | <observation> |
| Scope | ✅ / ⚠️ / ❌ | <observation> |
| Existing patterns | ✅ / ⚠️ / ❌ | <observation> |
| Constraints | ✅ / ⚠️ / ❌ | <observation> |
| Verification | ✅ / ⚠️ / ❌ | <observation> |
| Done | ✅ / ⚠️ / ❌ | <observation> |
## Red flags
<bullet list, or "None">
## Improved version
<full rewrite>
## Why the rewrite is better
<2-3 specific gains>
Stopping condition
End the skill when:
- The user has the rewritten prompt
- Or the user pushes back: "It's fine as is." (Don't keep relitigating.)