# Skill Auditor

> SKILL.md prompt quality auditor. Use this skill whenever a user wants to review, diagnose, or improve any SKILL.md file. Trigger on: audit skill, check prompt quality, skill quality, SKILL.md review, prompt issues, review my skill, skill auditor, optimize skill prompt, scan all skills, full library scan. Trigger even when the user just says "take a look at this skill" or "is my skill well written". Outputs a structured quality report, auto-fixes what it can, and flags the rest for human review.

- Skill: `jihonghe68/skill-auditor-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jihonghe68/skill-auditor-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jihonghe68/skill-auditor-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: jihonghe68 (https://skillmd.com/u/jihonghe68)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jihonghe68/skill-auditor-2

---


# 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:
```bash
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:

```markdown
## 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:

```markdown
| 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

1. Every score must cite actual text from the SKILL.md being reviewed — no scoring from memory.
2. Filler word penalties apply only to rule/instruction text, never to example content.
3. All auto-fix suggestions must carry a note: "template — confirm details before applying."
4. Never rule on whether domain knowledge is factually correct (thresholds, standards applicability, etc.).
5. If the SKILL.md provided is incomplete, state: "Score based on provided content only."
6. If a high-stakes skill scores D3 < 12, insert the safety warning before the score table.