# Skill Best Practices

> Audit installed Claude Code skills against best practices and output ranked suggestions. Use when you want to check skill quality, review a skill for issues, audit all personal skills, lint skills, or improve skill structure. Accepts an optional skill name or "all" (default).

- Skill: `az9713/skill-best-practices` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add az9713/skill-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/az9713/skill-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: az9713 (https://skillmd.com/u/az9713)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/az9713/skill-best-practices

---


# Skill Best Practices Auditor

Audit personal Claude Code skills against a 25-check best practices checklist. **READ-ONLY** — outputs findings to terminal only. Never modifies any files.

## Constraints

- **Read-only.** Do not create, edit, or delete any files.
- **Terminal output only.** All results are printed inline.
- **Skip self.** When auditing "all", skip `skill-best-practices` to avoid feedback loops.
- **Skip non-skill directories.** Only audit directories containing a `SKILL.md` file.

## Execution Steps

### Step 1: Determine Scope

Parse `$ARGUMENTS` to decide what to audit:
- If empty or `all` → audit every skill in `~/.claude/skills/`
- If a skill name is given → audit only that skill directory
- If the name doesn't match a directory, search for partial matches and report an error if none found

### Step 2: Gather Data Per Skill

For each skill directory in scope:

1. Check if `SKILL.md` exists (C01). If not, report Critical failure and skip remaining checks for this skill.
2. Read `SKILL.md` in full.
3. Parse YAML frontmatter — extract all key-value pairs.
4. Count total lines in SKILL.md.
5. List all files and directories in the skill folder (non-recursive first, then recursive for depth checks).
6. If `references/` exists, list its contents and count lines per file.

### Step 3: Run Checklist

Load the checklist from `references/checklist.md` in this skill's directory.

Run each of the 25 checks against the gathered data. For each check, record:
- **ID** (e.g., C01, H03, M09)
- **Status:** PASS or FAIL
- **Detail:** Brief explanation (1 line). On FAIL, include the fix recommendation from the checklist.

Apply checks in order: Critical → High → Medium → Low.

For heuristic checks (M07, M08, M09, L01, L03), use best judgment. If uncertain, mark as PASS with a note.

### Step 4: Produce Report

Generate output following the format below. Print it directly to the terminal.

## Output Format

### Per-Skill Section

For each audited skill, output:

```
## [skill-name]

### Critical
- C01 PASS — SKILL.md exists
- C02 FAIL — No YAML frontmatter found
  → Fix: Add YAML frontmatter between --- delimiters at the top of SKILL.md.

### High
- H01 PASS — Description contains trigger phrases
...

### Medium
...

### Low
...

### Passed (X/25)
C01, C03, C04, H01, H02, ...
```

Group findings by criticality. Show FAIL items with their fix recommendation (prefixed with →). List all passed check IDs in a single collapsed line at the end.

Only show criticality sections that have at least one finding (PASS or FAIL).

### Summary Table

After all per-skill sections, output a summary:

```
## Summary

| Skill | Critical | High | Medium | Low | Passed | Score% |
|-------|----------|------|--------|-----|--------|--------|
| my-skill | 0 | 1 | 2 | 0 | 22/25 | 90% |
| other-skill | 1 | 0 | 3 | 1 | 20/25 | 78% |
```

Score% is calculated using the weights from `references/checklist.md`:
- Critical = 8 pts, High = 4 pts, Medium = 2 pts, Low = 1 pt
- Total possible = 81 pts
- Score% = (earned / 81) × 100, rounded to nearest integer

### Final Stats

```
## Stats

- Skills audited: 14
- Average score: 85%
- Most common issue: M01 (no allowed-tools restriction) — 9 skills
- Top recommendation: Add allowed-tools to frontmatter to restrict tool access.
```

Report the single most frequently failed check across all audited skills, with its count and fix.

## Edge Cases

- If a skill directory has no SKILL.md, report only C01 FAIL, skip all other checks, and score 0%.
- If frontmatter is missing, C02 FAIL implies C03 and C04 also FAIL. Still report all three.
- If `$ARGUMENTS` names a skill that doesn't exist, print an error and list available skills.
- For "all" mode, process skills alphabetically by directory name.