/skill-auditor

name: skill-auditor
description: Audits skills in this repo for consistency, API drift, and structural gaps. Produces a prioritized report grouped by severity (Critical/High/Medium/Low). Use when asked to "audit skills", "check the skill repo for drift", or when planning bulk skill cleanup. Read-only — does not apply fixes.
allowed-tools: [Read, Glob, Grep, Bash]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Skill Auditor

Audits every `SKILL.md` in `skills/` for frontmatter correctness, structural completeness, API/version drift, and cross-file reference integrity. Produces a prioritized markdown report. Read-only — never applies fixes.

When This Skill Activates

Use this skill when the user:

• Says "audit skills", "audit my skills", "run the skill auditor"
• Asks to "check the skill repo for drift", "review skills for consistency"
• Says "find broken skills", "validate skill frontmatter"
• Is planning a bulk cleanup of the skill repo
• References a specific category to audit (e.g., "audit the generators/ skills")

**Does NOT activate** for: creating new skills (use `skill-creator`), applying fixes (follow-up flow after this auditor reports), or auditing Swift code inside skills (use `ios/coding-best-practices` or `macos/coding-best-practices`).

Scope

Resolve the invocation argument in this order:

1. **No argument** → audit all of `skills/**/SKILL.md` 2. **Category path** (e.g., `generators/`, `ios/`) → audit `skills/<arg>/**/SKILL.md` 3. **Single file path** (e.g., `skills/liquid-glass/SKILL.md`) → audit one file 4. **Fuzzy match** → if arg doesn't resolve, try `skills/<arg>/SKILL.md`; fall back to asking the user

Process

1. Enumerate

Use `Glob` with pattern `skills/**/SKILL.md` from the repo root. Filter by scope if an argument was passed. Record the canonical file list — every subsequent step operates on this list.

2. Parse Frontmatter (Cached)

Read the first 20 lines of each `SKILL.md`. Parse:

• Whether `---` frontmatter block exists
• `name:`, `description:`, `allowed-tools:` field values
• Freshness keys: `last_verified:`, `review_by:` (dates, required — enforced

by `scripts/check-frontmatter.sh`), optional `os_version:`. Overdue `review_by` dates are the stale-skills workflow's job, not a finding here.

Cache this result. Checks C-01, H-01, H-03, L-02 all read from this cache — do not re-read.

3. Run Checks

Execute bulk `Grep` passes in parallel (single tool-call batch) wherever possible. Per-file operations come after. The 11 checks are in the table below; the order is as-listed.

4. Classify Aggregator vs Leaf

For each file, mark it as **aggregator** or **leaf** using the rules in the "Aggregator Detection" section below. Some checks relax for aggregators.

5. Rank and Emit

Group findings by severity (🔴 → 🟢), sort within each group by file path, print the report inline using the template in "Output Format".

Checks

🔴 Critical

**C-01 · Missing frontmatter.** The file has no leading `---` YAML block.

• **Detection**: multiline `Grep` for `\A---\n[\s\S]*?\n---` across all SKILL.md. Files with no match → C-01.
• **Fix**: Add YAML frontmatter with `name`, `description`, `allowed-tools`.

🟠 High

**H-01 · Missing `allowed-tools` field.** Frontmatter exists but `allowed-tools:` key is absent.

• **Detection**: from cached frontmatter parse.
• **Fix**: Add `allowed-tools: [Read, Glob, Grep]` (adjust based on what the skill actually does).

**H-02 · Broken supporting-file reference.** The SKILL.md references a `*.md` file that does not exist on disk in the same directory.

• **Detection**: `Grep` each SKILL.md for `[a-z0-9][a-z0-9-]*\.md` matches; resolve each relative to the SKILL.md's directory; `ls` to confirm. Missing files → H-02. Ignore matches inside fenced code blocks. Also resolve `rules/swiftlint.yml` references the same way (fragment fixtures themselves are CI's job — `scripts/check-lint-fragments.sh`).
• **Fix**: Create the file or remove the reference.

**H-03 · H1 title does not match `name:`.** The first `#` heading after the frontmatter, slugified (lowercase, spaces → `-`), differs from the `name:` field.

• **Detection**: from cached frontmatter parse + per-file line-after-frontmatter.
• **Fix**: Rename the H1 or the `name:` to match.

🟡 Medium

**M-01 · Missing "When This Skill Activates" section.** No `## When This Skill Activates` heading anywhere in the file.

• **Detection**: `Grep -L` for `^## When This Skill Activates` across all SKILL.md.
• **Fix**: Add section with 3–5 user trigger phrases. See `shared/skill-creator/SKILL.md` for the canonical format.

**M-02 · Outdated version reference (drift).** Mentions iOS 17–25, macOS 13–25, or Swift 5.x with **drift context** (treated as current/latest/target).

• **Detection (two-stage)**:

1. **Stage 1** — `Grep` for `\biOS (1[7-9]|2[0-5])\b|\bSwift 5\.\d+\b|\bmacOS (1[3-9]|2[0-5])\b`, capturing line numbers. 2. **Stage 2** — for each hit, examine ±2 surrounding lines. Classify:

• **Flag M-02** if surrounding lines contain: `latest`, `newest`, `current`, `target`, `deployment target`, `requires`, `minimum`, `as of`, `new in`, `now supports`, `today`
• **Suppress** if surrounding lines contain: `legacy`, `pre-`, `prior to`, `before`, `deprecated`, `old`, `migrate from`, `backport`, `fallback`, `if available`, `#available`, or the version mention has a trailing `+` (e.g., `iOS 17+`)
• **Neither** → L-03 (ambiguous)
• **Known-current constants** (dated 2026-07-11, update per WWDC): iOS 27, macOS 27 (announced WWDC26; iOS 26 / macOS 26 are within the one-generation grace), Swift 6.x. Normative source: `scripts/versions.env`. Mentions of these with drift context are always clean.
• **Fix**: Update the reference to the current generation (see `scripts/versions.env`), or annotate as legacy context with one of the suppression keywords.

**M-03 · Pre-`@Observable` pattern without deprecation callout.** Use