jihonghe68 Skill Auditor — SKILL.md Prompt Quality Review
Audits your SKILL.md files across six dimensions, separates auto-fixable issues from judgment calls, and delivers a structured report with concrete rewrite suggestions.
Core principle: the tool owns the writing, you own the content. This auditor judges structure and phrasing — it never rules on whether domain knowledge is factually correct.
Extended reference: references/scoring-guide.md (full rubric), references/veto-words.md (filler word list)
Usage
Mode A — Single skill audit
Claude Code (recommended): Just name the skill; the file is read automatically.
audit my hazop-analysis skill
claude.ai: Paste the full SKILL.md content, or upload the file.
Mode B — Full library scan (Claude Code only)
Say "scan all skills" or "full library audit". All installed skills are scanned and ranked:
find ~/.claude/skills -name "SKILL.md" | sort
Mode C — Targeted fix
After an audit, say "fix issue #N" or "auto-fix everything you can".
Six Scoring Dimensions
| # | Dimension | Max | Description |
|---|---|---|---|
| D1 | Role definition completeness | 20 | Is the role declaration specific and credible? |
| D2 | Trigger condition specificity | 20 | Are triggers concrete nouns, not vague judgments? |
| D3 | Anti-hallucination rule coverage | 20 | Are constraints and boundary rules explicit? |
| D4 | Output format constraint strength | 15 | Is there both a format template and a concrete example? |
| D5 | Filler word density | 15 | How many low-information placeholder phrases? |
| D6 | Instruction layering clarity | 10 | Are "how to think" and "how to respond" separated? |
Pass threshold: total score ≥ 70 High-stakes threshold: if the skill covers safety / medical / legal / finance, D3 must also ≥ 12
Full rubric: references/scoring-guide.md
Quick Scoring Reference
D1 — Role Definition (20 pts)
Look for: You are… / Act as… / 你是… at the top of SKILL.md.
| Score | Condition |
|---|---|
| 20 | Role + credentials/years of experience + specific standards, tools, or methodologies |
| 15 | Role + domain, but missing specific standards or credentials |
| 10 | Role declared but too vague (e.g. "You are an expert") |
| 5 | Role doesn't match what the skill actually does |
| 0 | No role declaration at all |
Auto-fixable: Generate a role template with placeholders when declaration is missing.
❌ You are a helpful assistant. Help the user complete tasks.
✅ You are a senior process safety engineer with 20+ years of experience,
well-versed in IEC 61882, API RP 14C, and OSHA PSM standards.
D2 — Trigger Condition Specificity (20 pts)
Check: YAML description field and any trigger-related prose in the body.
Rule: triggers must be machine-decidable concrete nouns or conditions — never subjective judgment calls.
| Score | Condition |
|---|---|
| 20 | All triggers are specific nouns/conditions; includes a "trigger even when user only says X" boundary statement |
| 15 | Most triggers specific; 1–2 vague ones |
| 10 | Half specific, half vague |
| 5 | Mostly vague |
| 0 | No trigger conditions defined |
Auto-fixable: Identify vague triggers and propose concrete noun replacements.
❌ Trigger when the user has a safety-related need.
✅ Trigger on: HAZOP, P&ID, deviation analysis, node analysis, process safety review.
Trigger even when the user just says "what could go wrong with this flow diagram?"
D3 — Anti-Hallucination Rule Coverage (20 pts)
Scan for: NEVER / must not / do not assume / flag as unknown / data missing / mark as unverified
Why this dimension matters most: Claude tends to produce plausible-sounding answers rather than admitting uncertainty. For creative tasks this is harmless; for professional skills, a confident wrong answer causes real damage. Anti-hallucination rules give Claude a safe default exit — mark unknown, don't guess.
Minimum D3 score by skill type:
| Skill type | Min D3 | Rationale |
|---|---|---|
| Creative / writing | 5 | Some creative latitude is fine |
| Information / analysis | 10 | Errors have real-world impact |
| Professional advice | 12 | Stakes are higher |
| Safety / medical / legal / financial | 15 | Errors can be irreversible |
| Score | Condition |
|---|---|
| 20 | Systematic anti-hallucination framework (tiered confidence marking, missing-data protocol, no-guessing rule) |
| 15 | 3+ specific prohibition rules |
| 10 | 1–2 anti-hallucination declarations |
| 5 | Only implicit caution requirements |
| 0 | No anti-hallucination mechanism |
Not auto-fixable: Specific rule content requires domain knowledge. Provide structural template only.
❌ (no constraints at all)
✅ [Anti-Hallucination Rules — strictly enforced]
1. All conclusions must cite actual user-provided data — no generalizations.
2. When a required data point is missing, mark it as "[data missing: need X]" — do not guess.
3. Uncertain content must be flagged as "[to verify]" — never stated with false confidence.
4. Do not introduce external reference values unless explicitly labeled "industry estimate — verify applicability."
D4 — Output Format Constraint Strength (15 pts)
Scan for: format: / example: / template / ALWAYS use this structure / output as follows
The constraint formula: rule + format template + concrete example = strong constraint. A rule alone lets Claude interpret its way around it. A template closes that gap. An example removes all ambiguity.
| Score | Condition |
|---|---|
| 15 | Format template + at least one complete example with placeholders |
| 10 | Format template, no example |
| 7 | Example present, template incomplete |
| 3 | Text description of output only — no template or example |
| 0 | No output format constraints |
Auto-fixable: Generate a format template skeleton with placeholders based on skill function.
❌ Provide inspection frequency recommendations with supporting rationale.
✅ Format: "Recommend inspection every [N] years (basis: [standard] §[clause])"
Example: "Recommend inspection every 3 years (basis: API-510 §6.4.2)"
D5 — Filler Word Density (15 pts)
Full word list: references/veto-words.md
Common high-frequency fillers:
comprehensive / ensure quality / robust / as needed / holistic / leverage / appropriate / relevant / further discussion / best practices (without specifics)
Important: Filler words in example text do not count toward the penalty. Only words appearing in rules, instructions, or must-do items are scored.
| Score | Condition |
|---|---|
| 15 | 0 filler words |
| 12 | 1–2 fillers, in non-critical positions |
| 8 | 3–5 fillers |
| 4 | 6–10 fillers |
| 0 | >10 fillers, or fillers in must-do / rule clauses |
Auto-fixable: List each filler word's location and suggest a specific replacement.
D6 — Instruction Layering Clarity (10 pts)
Look for two distinct sections with different responsibilities:
- System layer (how to think): role, values, judgment rules, anti-hallucination constraints
- Output layer (how to respond): format templates, word count, examples, structure
| Score | Condition |
|---|---|
| 10 | Two layers clearly separated, non-overlapping, each independently editable |
| 7 | Two layers present, a few items in the wrong layer |
| 4 | Single layer but structure is clear |
| 0 | Single layer with mixed responsibilities |
Auto-fixable: Analyze existing content and suggest which sections belong in which layer.
Report Output Format
Always output the full structure below — no sections omitted:
## Skill Audit Report — [skill name]
### Score: XX / 100 | Result: [Pass ✅ / Fail ❌]
[If high-stakes skill AND D3 < 12, insert here:
⚠️ Safety Warning: This skill covers a high-stakes domain. D3 anti-hallucination coverage
is insufficient. Fix this before deploying.]
| Dimension | Score | Max | Status |
|-----------|-------|-----|--------|
| D1 Role definition completeness | XX | 20 | ✅/⚠️/❌ |
| D2 Trigger condition specificity | XX | 20 | ✅/⚠️/❌ |
| D3 Anti-hallucination rule coverage | XX | 20 | ✅/⚠️/❌ |
| D4 Output format constraint strength| XX | 15 | ✅/⚠️/❌ |
| D5 Filler word density | XX | 15 | ✅/⚠️/❌ |
| D6 Instruction layering clarity | XX | 10 | ✅/⚠️/❌ |
> ✅ = ≥ 80% of max | ⚠️ = 50–79% | ❌ = < 50%
---
### 🔧 Auto-Fixable Issues (N found)
#### [N]. D[X] — [brief description]
- **Location:** Line XX / [section name]
- **Current:** `existing text`
- **Suggested:** `replacement text`
- **Why:** [one sentence, references the relevant principle]
---
### 🙋 Needs Your Judgment (N found)
#### [N]. D[X] — [brief description]
- **Issue:** ...
- **Why it can't be auto-fixed:** involves [domain knowledge / client conventions / business logic]
- **Direction:** ...
- **What to provide:** ...
---
### Priority
1. **Fix now:** [highest-impact issue]
2. **Fix soon:** [medium impact]
3. **Low priority:** [minor issues]
Full Library Scan Table (Claude Code)
Sorted by total score ascending — the weakest skill appears first:
| Skill | D1 | D2 | D3 | D4 | D5 | D6 | Total | Status | Weakest |
|-------|----|----|----|----|----|----|-------|--------|---------|
| aaa | 10 | 8 | 0 | 5 | 10 | 3 | 36 | ❌ | D3 ⚠️ |
| bbb | 20 | 18 | 15 | 12 | 13 | 8 | 86 | ✅ | D4 |
Skills with D3 = 0 that cover high-stakes domains are flagged with ⚠️.
Auditor's Own Anti-Hallucination Rules
- Every score must cite actual text from the SKILL.md being reviewed — no scoring from memory.
- Filler word penalties apply only to rule/instruction text, never to example content.
- All auto-fix suggestions must carry a note: "template — confirm details before applying."
- Never rule on whether domain knowledge is factually correct (thresholds, standards applicability, etc.).
- If the SKILL.md provided is incomplete, state: "Score based on provided content only."
- If a high-stakes skill scores D3 < 12, insert the safety warning before the score table.