skill-auditor

Name: skill-auditor
Author: rshankras

Security Community

Repo stars 362
Author updated Live
Author repo claude-code-apple-skills

Fluxly profile Facts only: domain, agents, trust score, runtime, permissions and network

Domain: Security
Compatible agents: Claude Code
Cursor
Cline
Codex
Windsurf
Gemini CLI

+20
Trust score: 88 / 100 · community maintained
Author / version / license: @rshankras · no license declared
Token usage: Lean
Setup complexity: Guided setup
External API key: Not required
Operating systems: macOS
Runtime requirements: No special requirements
Permissions: Read-only
Write / modify
Shell exec
Network behavior: Local-only
Install commands: 26 variants

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview skill-auditor-rshankras.preview

---
name: skill-auditor
description: Audits skills in this repo for consistency, API drift, and structural gaps. Produces a prioritiz…
category: security
runtime: no special runtime
---

# skill-auditor output preview

## PART A: Task fit
- Use case: 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..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “When This Skill Activates / Scope / Process” and do not present inference as author intent.

## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “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.”.
- **02** When the source has headings, the agent prioritizes “When This Skill Activates / Scope / Process” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.

## Running Rules
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options.

SKILL.md SKILL.md

---
name: skill-auditor
description: Audits skills in this repo for consistency, API drift, and structural gaps. Produces a prioritiz…
category: security
source: rshankras/claude-code-apple-skills
---

# skill-auditor

## When to use
- Audits skills in this repo for consistency, API drift, and structural gaps. Produces a prioritized report grouped by s…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.

## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.

## Execution rules
- Organize steps around “When This Skill Activates / Scope / Process” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.

## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies.

Evidence boundary and execution chain

The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.

skill "skill-auditor" {
  input      -> user goal + target files + boundaries + acceptance criteria
  context    -> When This Skill Activates / Scope / Process
  rules      -> SKILL.md triggers / order / output contract
  runtime    -> no special runtime | read files, write/modify files, run shell commands | mostly runs locally
  guardrails -> usually needs no extra API key + small-sample validation + diff/log review
  output     -> copyable result + checklist + next iteration
}

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Audits skills in this repo for consistency, API drift, and structural gaps. Produces a prioritized report grouped by severity (C…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “When This Skill Activates”, “Scope”, “Process”, “1. Enumerate”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name skill-auditor directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “When This Skill Activates / Scope / Process” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write / shell-exec; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

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:

No argument → audit all of skills/**/SKILL.md
Category path (e.g., generators/, ios/) → audit skills/<arg>/**/SKILL.md
Single file path (e.g., skills/liquid-glass/SKILL.md) → audit one file
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 15 lines of each SKILL.md. Parse:

Whether --- frontmatter block exists
name:, description:, allowed-tools: field values

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.
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-04-20, update per WWDC): iOS 26, macOS 26, Swift 6.x. Mentions of these with drift context are always clean.
Fix: Update the reference to iOS 26 / macOS 26 / Swift 6.x, or annotate as legacy context with one of the suppression keywords.

M-03 · Pre-@Observable pattern without deprecation callout. Uses @StateObject or ObservableObject without acknowledging that @Observable is the current pattern.

Detection: Grep for @StateObject|ObservableObject with line numbers; for each hit, secondary Grep of the same file for @Observable|deprecated|legacy|pre-@Observable|migration|old pattern within ±10 lines. No secondary match → M-03.
Fix: Either replace with @Observable + @State, or add a migration note explaining why the older pattern is shown.

M-04 · Oversized single-file skill. SKILL.md exceeds 400 lines and its directory contains no sibling .md files.

Detection: wc -l via Bash on each SKILL.md; if >400, check sibling file list via ls for any other .md. None → M-04.
Fix: Modularize — extract sections into patterns.md, templates.md, checklist.md, or examples.md per skill-creator conventions.

🟢 Low

L-01 · No ✅/❌ examples in prose. The file has no ✅ or ❌ markers anywhere.

Detection: Grep -L for ✅|❌.
Fix: Add at least one good/bad example pair.

L-02 · Description length out of range. description: is <20 or >300 characters.

Detection: from cached frontmatter parse.
Fix: Expand or shorten the description. Include a "use when…" clause to anchor activation.

L-03 · Ambiguous version mention. A version keyword matched stage 1 of the drift check but surrounding lines contained neither drift nor legacy context. User reviews manually.

Detection: fallthrough from M-02 stage-2 classification.
Fix: Add a drift or legacy keyword to disambiguate, or leave as-is if the context is clearly a one-off mention.

Aggregator vs Leaf Detection

A SKILL.md is an aggregator if any of the following hold:

It sits at depth 2 under the repo root — i.e., skills/<category>/SKILL.md
It contains the heading ## Available Modules or ## Available Skills
It links to ./<subdir>/SKILL.md or contains two or more references of the form skills/<category>/<subskill>/

Otherwise it is a leaf.

Relaxations for aggregators

Check	Behaviour
M-01 (activation section)	Still enforced — aggregators must describe activation
M-03 (pre-@Observable)	Suppressed — aggregators are prose, not code
M-04 (>400 lines)	Suppressed — aggregators are allowed to be long when enumerating modules
L-01 (no ✅/❌ examples)	Suppressed — aggregators don't carry patterns

Tag every finding in the report with (aggregator) or (leaf) so severity can be read at a glance.

Output Format

Print the report inline to the conversation using this template. Use exact headings — downstream tooling may grep them.

# Skill Audit Report — <YYYY-MM-DD> — <N> files scanned

## Summary
- 🔴 Critical: <count>
- 🟠 High: <count>
- 🟡 Medium: <count>
- 🟢 Low: <count>
- ✅ Files clean: <clean-count> / <N>

Scope: <all | category | single file>

## 🔴 Critical Findings
### C-01 · Missing frontmatter
- `skills/<path>/SKILL.md` (leaf) — **Fix:** Add YAML frontmatter with `name`, `description`, `allowed-tools`.

## 🟠 High Findings
### H-01 · Missing `allowed-tools` field
- `skills/liquid-glass/SKILL.md:1-4` (leaf) — **Fix:** Add `allowed-tools: [Read, Glob, Grep]`.
- `skills/macos/macos-tahoe-apis/SKILL.md:1-4` (leaf) — **Fix:** Same.

### H-02 · Broken supporting-file reference
- `skills/<path>/SKILL.md:<line>` — references `patterns.md`, not found. **Fix:** Create the file or remove the reference.

### H-03 · H1 title does not match `name:`
- `skills/<path>/SKILL.md` — `name: foo-bar`, H1 is `# Foo Bars`. **Fix:** Rename one to match.

## 🟡 Medium Findings
### M-01 · Missing "When This Skill Activates" section (<count>)
- `skills/design/liquid-glass/SKILL.md` (leaf)
- `skills/macos/coding-best-practices/SKILL.md` (leaf)
- [collapsed list of remaining offenders]
- **Fix:** Add section with 3–5 user trigger phrases.

### M-02 · Outdated version reference (<count>)
- `skills/<path>/SKILL.md:87` (leaf) — "latest iOS 17" in drift context. **Fix:** Update to iOS 26.

### M-03 · Pre-`@Observable` pattern without callout (<count>)
- `skills/<path>/SKILL.md:142` (leaf) — `@StateObject` without migration note. **Fix:** Replace with `@Observable` or add callout.

### M-04 · Oversized single-file skill (<count>)
- `skills/<path>/SKILL.md` — <NNN> lines, no sibling .md files. **Fix:** Modularize into `patterns.md` / `templates.md`.

## 🟢 Low Findings
### L-01 · No ✅/❌ examples
- `skills/<path>/SKILL.md` (leaf) — **Fix:** Add at least one good/bad example pair.

### L-02 · Description length out of range
- `skills/<path>/SKILL.md` — description is <N> chars. **Fix:** Expand/shorten to 20–300 chars.

### L-03 · Ambiguous version mention
- `skills/<path>/SKILL.md:<line>` — "iOS 18" with no drift/legacy context. **Fix:** Review manually.

## ✅ Clean Files
<collapsed list of files that passed all checks>

## Next Steps
- Review 🔴/🟠 findings first — they block skills from working as intended.
- Batch-fix 🟡 M-01 and M-02 mechanically — suggested find/replace scripts shown per-file.
- 🟢 findings are polish; address opportunistically.

Implementation Notes

Parallelize bulk Greps in a single tool-call batch where possible. Activation, frontmatter, @StateObject, and drift-stage-1 can all run at once.
Cache the frontmatter parse. Four checks read it; only parse once.
Resolve *.md references inside fenced code blocks carefully — they're examples, not references. Strip fenced blocks before running H-02's regex.
Progress pings — for full-repo scans (148 files), emit a short "scanning /…" before each phase so the user sees liveness.
Idempotence — the report body (everything below the ## Summary) should be deterministic for a given repo state. Only the date in the H1 varies across runs.
Never write files. This skill's allowed-tools lists Bash, but only for read-only ops (wc, ls). If you find yourself needing to write, stop and ask the user to invoke a fix flow separately.

Non-Goals

No auto-fix. The report includes one-line fix suggestions per finding; applying them is a separate user-initiated task.
No network calls. This auditor does not verify URL liveness or check Apple doc availability.
No Swift compilation. Code-block validity is beyond scope; patterns are matched textually.
No WWDC session cross-referencing. A future wwdc-to-skill-workflow skill owns that.

Maintenance

The drift heuristic hardcodes "known-current" version constants:

iOS 26, macOS 26, Swift 6.x (dated 2026-04-20)

Update these constants when Apple ships a new major platform version (usually post-WWDC each June). The stage-1 regex ranges (iOS 1[7-9]|2[0-5], macOS 1[3-9]|2[0-5]) must also be widened to include the newly-retired version.

Verification

After running the auditor on the full repo, counts should fall within this tolerance band (baseline taken 2026-04-20, 149 total SKILL.md files):

Finding	Expected
C-01 missing frontmatter	9 — legacy batch in `app-store/` (keyword-optimizer, app-description-writer, screenshot-planner, review-response-writer) and `generators/` (accessibility-generator, ci-cd-setup, deep-linking, localization-setup, push-notifications)
H-01 missing `allowed-tools`	9 — same set as C-01 (they lack frontmatter entirely)
H-02 broken supporting refs	0
H-03 H1 mismatch	flag outliers manually
M-01 missing activation section	28 — includes the 9 C-01 offenders (which use `## When to Use` instead) plus 19 newer skills missing the section entirely
M-02 version drift	~50 (±10) — stage-1 Grep returns ~228 raw hits across ~69 files; stage-2 keyword filtering narrows to this band
M-03 pre-`@Observable` no callout	~29 (±5)
M-04 oversized single-file	TBD — flag outliers

Known legacy pattern: `## When to Use`

The 9 C-01 offenders all use ## When to Use (non-canonical) rather than ## When This Skill Activates. The auditor flags this as M-01 correctly; the suggested fix is to rename the heading when adding frontmatter. Do not widen the M-01 regex to accept ## When to Use — the whole point is to normalize onto the canonical heading.

Smoke tests

Full-repo run — invoke with no arg. Counts must fall within tolerance above.
Scoped run — invoke with generators/. Only skills/generators/** paths appear.
Single-file run — invoke with skills/liquid-glass/SKILL.md. Report has exactly one H-01 finding.
Idempotence — re-run immediately. Report body is byte-identical; only the date in the H1 may differ.
Drift heuristic sanity — spot-check 5 M-02 hits and 5 suppressed legacy mentions. If any legacy mention is mis-flagged, extend the suppression keyword list and re-run.

References

/Users/ravishankar/Work/MyApps/claude-code-apple-skills/CLAUDE.md — normative source for frontmatter schema, naming, emoji convention
skills/shared/skill-creator/SKILL.md — companion meta-skill for creating new skills (this auditor only audits; it does not create)
skills/ios/SKILL.md — canonical aggregator example

Install command

One-click installPick a runner, click Copy, paste into your terminal, press enter

npx skills add rshankras/claude-code-apple-skills/skills/shared/skill-auditor -y

Open general install guide

View skill source

Works with

Claude Code
Cursor
Cline
Codex
Windsurf
Gemini
OpenCode
Roo Code
AAide
+Augment
GitHub Copilot
OpenClaw
KKiro
Junie
WWarp
Goose
Trae
Kilo Code
OpenHands
Amp
Zencoder
CContinue
AIAider
CodeBuddy
CodeGeeX
Replit Agent

Security audit

88 / 100

Community

未声明 license/许可。
未声明 version。
未限定 allowed-tools，默认拥有全部工具权限。

Metadata

Source: github
rshankras/claude-code-apple-skills
中文

Category & tags

Category Security