# Audit Skills

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-mostafa-drz-claude-skills-audit-skills`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mostafa-drz](https://agentstack.voostack.com/s/mostafa-drz)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mostafa-drz](https://github.com/mostafa-drz)
- **Source:** https://github.com/mostafa-drz/claude-skills/tree/main/code/audit-skills

## Install

```sh
agentstack add skill-mostafa-drz-claude-skills-audit-skills
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Audit Skills

Audit personal Claude skills for consistency, best practices, and up-to-date standards.

## Command routing

Check `$ARGUMENTS`:

- **`help`** → display help then stop
- **`--fix [skill-name]`** → auto-fix issues (see Fix mode)
- **`--verbose [skill-name]`** → show full details for every check (not just failures)
- **``** → audit a single skill
- **empty** → audit all skills

### Help

```
Doctor — Audit personal Claude skills for health and consistency

Usage:
  /audit-skills                      Audit all personal skills
  /audit-skills          Audit a single skill
  /audit-skills --fix                Auto-fix all skills
  /audit-skills --fix    Auto-fix a specific skill
  /audit-skills --verbose            Full detail for every check
  /audit-skills help                 This help

Checks performed:
  Manifest    Does the skill follow SKILLS_GUIDE.md conventions?
  Frontmatter Are all required/recommended fields present and correct?
  Content     Is the skill under 500 lines? Are references bundled?
  Tools       Are allowed-tools minimal? Any duplicates? Any contradictions?
  UX          Does it have help/config/reset? First-time detection? Memory?
  Docs        Is the description third-person with trigger keywords?
  Security    Does disable-model-invocation match the side-effect profile?
  Upstream    Does it follow latest official Claude skills documentation?

Output:
  [PASS] Check passed
  [WARN] Non-critical suggestion
  [FAIL] Violates manifest or best practice
  [INFO] Informational note

Example output:
  /slack-to-ticket
    [PASS] Third-person description
    [PASS] disable-model-invocation: true (has side effects)
    [WARN] SKILL.md is 120 lines — fine, but has inline examples that could be bundled
    [FAIL] Missing help subcommand
    [PASS] Preferences memory pattern present
```

## Step 1: Load references

### Local manifest

Read `~/.claude/skills/SKILLS_GUIDE.md` — this is the source of truth for local conventions.

### Latest upstream docs

Search the web for the latest Claude Code skills documentation:

ultrathink

Search for:
- `site:code.claude.com skills` — official skill format docs
- `site:platform.claude.com agent-skills best-practices` — authoring best practices
- `claude code skills 2026` — any new features or changes

Fetch and read the top results. Extract:
- Any NEW frontmatter fields not in our manifest
- Any CHANGED best practices (naming, descriptions, tool restrictions)
- Any DEPRECATED patterns we're still using
- Any NEW features we should adopt

Compile a checklist of **upstream checks** in addition to the manifest checks.

If web search is unavailable, proceed with manifest-only checks and note: "Could not fetch upstream docs — manifest checks only."

## Step 2: Discover skills

```
~/.claude/skills/*/SKILL.md
```

List all found skills. If a specific skill-name was given in `$ARGUMENTS`, filter to just that one.

## Step 3: Audit each skill

For each skill, run every check below. Track results as PASS/WARN/FAIL/INFO.

### Frontmatter checks

| Check | PASS | FAIL |
|---|---|---|
| `name` present | Has name | Missing |
| `description` present | Has description | Missing |
| `description` is third-person | Starts with verb in third person ("Creates", "Analyzes") | Imperative/second person ("Create", "Analyze") |
| `description` has trigger keywords | Contains "Use when" or similar usage hint | No usage context |
| `description` length | ≤1024 chars | Over 1024 |
| `argument-hint` present | Has hint | WARN: missing (optional but recommended) |
| `disable-model-invocation` | `true` if skill has side effects (check allowed-tools for Write, Edit, Bash, MCP create/update tools) | Missing when side effects present |
| `allowed-tools` present | Listed | WARN: missing (broad permissions) |

### Tool checks

| Check | PASS | FAIL |
|---|---|---|
| No duplicate MCP tools | Single prefix per service | Both `mcp__linear-server__*` and `mcp__claude_ai_Linear__*` |
| MCP tools use canonical prefix | Uses `mcp__claude_ai_Linear__*` | Uses `mcp__linear-server__*` |
| No contradictory tools | Read-only skills don't have Write/Edit | Read-only principle violated |
| Minimal tools | Only tools actually referenced in body | Tools listed but never used |

### Content checks

| Check | PASS | FAIL |
|---|---|---|
| Under 500 lines | ≤500 | WARN: over 500 |
| No redundant instructions | Doesn't tell Claude how to use JSON, git basics, etc. | WARN: generic instructions |
| Uses numbered checklists for workflows | Steps are numbered | WARN: prose-only workflow |
| References bundled files if >100 lines of examples | Examples in separate files | WARN: large inline examples |

### UX checks (from manifest conventions)

| Check | PASS | FAIL |
|---|---|---|
| `help` subcommand | Body handles `$ARGUMENTS` = "help" | Missing |
| `config` subcommand | Body handles `$ARGUMENTS` = "config" | Missing |
| `reset` subcommand | Body handles `$ARGUMENTS` = "reset" | Missing |
| First-time detection | Checks for preferences file existence | Missing |
| Preferences memory | References `preferences.md` file | Missing |
| Dynamic context injection | Uses `!`backtick`` preprocessing | WARN: missing where applicable |

### Upstream checks (from fetched docs)

Apply any new checks discovered in Step 1. Common ones:

| Check | PASS | FAIL |
|---|---|---|
| `context: fork` for self-contained skills | Set when skill doesn't need conversation history | WARN: could benefit from fork |
| `model` field for reasoning-heavy skills | Set for complex analysis skills | INFO: could benefit from model override |
| Positional args `$0`, `$1` | Used for structured inputs | INFO: could use positional args |
| Skill directory structure | Has SKILL.md + optional reference/examples | Non-standard structure |

### Inventory check (only on full audit)

- Compare discovered skills against `SKILLS_GUIDE.md` inventory table
- Report any skills not in the inventory (WARN)
- Report any inventory entries with no matching skill (WARN)

## Step 4: Present results

### Per-skill report

```
/skill-name
  [PASS] 8 checks passed
  [WARN] 2 warnings
  [FAIL] 1 failure

  Failures:
    - disable-model-invocation missing (skill creates Linear issues)

  Warnings:
    - No dynamic context injection (could pre-fetch git branch)
    - SKILL.md is 180 lines with inline examples (consider bundling)
```

### Summary (full audit only)

```
Doctor Summary — {date}

Skills audited: {N}
  [PASS] {N} fully healthy
  [WARN] {N} with warnings
  [FAIL] {N} with failures

Top issues:
  1. {most common failure across skills}
  2. {second most common}

Upstream updates:
  {Any new features/changes from official docs worth adopting}
  (or "All skills are up-to-date with latest docs")

Inventory:
  {N} skills in SKILLS_GUIDE.md
  {N} skill directories found
  {discrepancies if any}
```

## Step 5: Offer fixes (if `--fix` flag)

If `--fix` was passed:

1. For each FAIL, propose a specific edit
2. For each WARN, propose a fix (optional)
3. Use **`AskUserQuestion`** (multiSelect: true):
   - One option per proposed fix
   - "Apply all fixes"
   - "Skip all"
4. Apply approved fixes using Edit tool
5. Update `SKILLS_GUIDE.md` inventory if new skills were found
6. Report what was changed

Without `--fix`: just report findings.

## Step 6: Save audit results

Write a timestamped audit log to:
```
~/.claude/skills/audit-skills/last-audit.md
```

Format:
```markdown
# Skill Audit — {date}

## Summary
- Skills: {N}
- Pass: {N}, Warn: {N}, Fail: {N}

## Per-skill results
{compact results}

## Upstream notes
{anything new from docs}
```

This allows comparing across audits to track improvement.

## Principles

- **Non-destructive by default**: Only report, never modify without `--fix` and user confirmation.
- **Manifest is local truth**: SKILLS_GUIDE.md defines what "good" means for this user.
- **Upstream is advisory**: New features from official docs are INFO/WARN, not FAIL (unless the user's manifest adopts them).
- **Be specific**: Every FAIL/WARN includes exactly what's wrong and how to fix it.
- **Fast**: Don't re-read files unnecessarily. Parse frontmatter first, skip deep content checks if frontmatter fails.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mostafa-drz](https://github.com/mostafa-drz)
- **Source:** [mostafa-drz/claude-skills](https://github.com/mostafa-drz/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mostafa-drz-claude-skills-audit-skills
- Seller: https://agentstack.voostack.com/s/mostafa-drz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.