prompt-audit

name

prompt-audit

description

Audits system-level prompts (system prompts, CLAUDE.md files, project instructions, custom style/preferences) against a curated directive library and surface-specific best practices, producing a scored gap report with ranked, copy-ready fixes. Use whenever the user invokes `/prompt-audit`, or asks to "audit," "review," "improve," "optimize," "critique," or "grade" a system prompt, CLAUDE.md, project instructions, custom instructions, agent instructions, or any persistent instruction set. Also trigger when a user pastes a system-level prompt and asks what's wrong with it or how to make it better, even without saying "audit." On request it also outputs a rewritten version with best practices applied — offer this when the user says "fix," "rewrite," "apply the changes," or wants the improved prompt itself. For persistent prompts, NOT one-off task prompts.

Prompt Audit

Audit a system-level prompt and return a scored, actionable report. This skill diagnoses and recommends by default. It does NOT compose a prompt from scratch. On request, it produces a rewritten version with the audit's findings applied — but the audit is the primary deliverable; the rewrite is opt-in and never fabricates project-specific facts the original didn't supply.

What counts as a system-level prompt

In scope: API/system prompts, CLAUDE.md files, claude.ai Project instructions, custom style/preferences, agent/subagent instructions. These are persistent, govern many interactions, and have surface-specific best practices.

Out of scope: one-off task prompts ("write me an email about X"). If the user hands you one of those, say so and offer to help directly instead of auditing.

Workflow

Step 1 — Get the prompt and detect the surface

If the prompt wasn't provided, ask for it. Then determine which of the four surfaces it targets, using the detection heuristics in references/surface-best-practices.md:

• API system prompt
• CLAUDE.md
• Project instructions
• Style / preferences

If the surface is genuinely ambiguous and the recommendations would diverge, ask one question. Otherwise infer it and state your inference in the report so the user can correct it. Also detect or ask whether the target model is Claude or another model — it changes which directives transfer (see the model-agnostic notes in the directive library).

Report density: If the prompt is large (roughly 40+ lines or a dense API system prompt), the full scorecard can run 15+ rows and overwhelm the signal. Before producing the report, ask the user which they want:

• Focused — scorecard capped at the ~8 highest-impact relevant directives, the rest folded into prose
• Full — every relevant directive as its own row

For short prompts (a style block, a lean CLAUDE.md) skip the question — just show all relevant rows, there won't be many. Only ask when length would actually make the table unwieldy.

Step 2 — Score against the directive library

Read references/directive-library.md. For each of the 18 directives, classify the prompt's coverage:

• Present — the prompt addresses this behavior with enough specificity to be reliable
• Weak — gestures at it but too vague, or under-scoped (a literal reader would mis-apply it)
• Missing — absent

Weight each directive's Impact score against the prompt's apparent purpose. A tool-heavy agent prompt weights #8 (tool policy) and #11 (stop conditions) up; a writing-style preference block weights those down and #2/#12 up. Don't penalize a style block for lacking safety boundaries that belong in a higher layer.

Step 3 — Score formatting against the surface

Read references/surface-best-practices.md for the detected surface. Check the prompt's structure, format, length economics, and surface-specific traps (CLAUDE.md bloat, Project persistence-trap, style-layer scope creep, API document placement). Note any category errors — e.g. XML blocks in a CLAUDE.md, architecture in a style block.

Step 4 — Produce the report

Use this exact structure:

# Prompt Audit: <short label>

**Surface:** <detected surface> · **Target model:** <Claude | model-agnostic>
**Overall:** <score>/100 — <one-line verdict>

## Scorecard
<table: Directive | Status (Present/Weak/Missing) | Impact | Note>
Only list directives relevant to this prompt's purpose. Don't pad with N/A rows.

## Top 10 Recommendations
Ranked by weighted impact. For each:
**N. <Directive name>** — <Present/Weak/Missing>
<One sentence: what's wrong and why it matters.>
> <Copy-ready text to add or change, rendered in the target surface's idiom.>

## Formatting & Structure
<Surface-specific findings: order, format fit, length, traps. Bullet form.>

## What's working
<2-4 bullets on what the prompt already does well. Don't skip this — it tells the user what NOT to touch.>

## Cuts
<Anything to remove: bloat, dead prohibitions, misplaced-layer content, redundancy. Omit the section if nothing to cut.>

End the report by offering the rewrite: "Want the rewritten version with all of this applied?" Don't produce it unless asked (or unless the user requested it up front) — the audit is the deliverable; the rewrite is opt-in.

Step 5 — Rewrite (only if requested)

Produce a recommended version of the prompt with the audit's findings applied. This is the recommendations executed, not a from-scratch rewrite. Rules:

• Preserve what scored Present. Keep the user's working content; don't rewrite for the sake of it. Their voice and correct conventions survive.
• Fix Weak and Missing. Apply each top recommendation in the target surface's idiom (XML for API, terse markdown for CLAUDE.md, standing-role prose for Project, behavioral modifier for style).
• Execute the Cuts. Remove the bloat and dead prohibitions the audit flagged.
• Never fabricate project-specific facts. This is the hard rule. If the original didn't supply a build command, file path, schema, escalation threshold, or any other project-specific value, insert a <PLACEHOLDER: describe what goes here> token rather than inventing one. A confident wrong command is worse than an honest gap.
• Respect surface length economics. A rewritten CLAUDE.md must stay lean — don't let applying directives bloat the file the audit just praised for being short. If a directive's best home is a different layer (e.g. safety belongs above a style block), say so instead of cramming it in.

Output structure:

## Rewritten <surface>

<the full rewritten prompt in a code block, ready to copy>

**Placeholders to fill:** <list each PLACEHOLDER and what it needs, or "none" if the original supplied everything>
**What changed:** <3-6 bullets mapping changes back to the recommendations>
**Left intact:** <what you deliberately kept and why>

After the rewrite, note that it's worth re-auditing once placeholders are filled, since fabrication-free scaffolding can't be fully scored until the real values are in.

Scoring rubric

Start at 100. Deduct by weighted impact of gaps:

• Each Missing Impact-5 directive (relevant to purpose): −12
• Each Missing Impact-4: −8
• Each Missing Impact-3: −4
• Weak directives: half the above
• Formatting category errors (e.g. XML in CLAUDE.md, CLAUDE.md bloat): −5 to −15 by severity
• Floor at 0. A prompt can't score above 90 if it's missing any Impact-5 directive relevant to its purpose.

Report the number but lead the verdict with substance — the score is a hook, the recommendations are the value.

Rules

• Recommendations must be copy-ready and rendered in the target surface's idiom. An XML block for a CLAUDE.md is a category error. A terse markdown rule for an API prompt that wanted a full template is under-delivering.
• Rank by weighted impact, not by directive number. The top recommendation should be the single highest-leverage change.
• Don't manufacture gaps to fill the top-10. If a prompt is genuinely tight, return fewer recommendations and say so. A 5-item list on a strong prompt beats a padded 10.
• Quote the user's own prompt when pointing at a specific weakness, so the finding is concrete.
• Lead with the answer. The verdict line and top recommendation come before any methodology.
• For non-Claude targets, flag Claude-specific tactics (XML weighting, position weighting, prefill, effort parameter, the literalism guard) that don't transfer, per the directive library's model-agnostic notes.

Reference files

• references/directive-library.md — the 18 directives: what, why, failure prevented, test, per-surface rendering, and model-agnostic transfer notes. Read in Step 2.
• references/surface-best-practices.md — per-surface format, length economics, structure order, and traps. Read in Step 1 (detection) and Step 3 (formatting score).