audit-skills

# audit-skills

Scans all `src/skills/*/SKILL.md` files and reports compliance with OrchestKit authoring standards. Each category has individual files in `rules/` and `references/` loaded on-demand.

## Quick Reference

| Category | File | Impact | When to Use |
|----------|------|--------|-------------|
| Audit Checks | `${CLAUDE_SKILL_DIR}/rules/audit-checks.md` | HIGH | What to validate per skill |
| Status Rules | `${CLAUDE_SKILL_DIR}/rules/audit-status.md` | MEDIUM | PASS/WARN/FAIL classification |
| Output Format | `${CLAUDE_SKILL_DIR}/references/output-format.md` | MEDIUM | Table layout and column definitions |
| Edge Cases | `${CLAUDE_SKILL_DIR}/references/edge-cases.md` | LOW | Manifest "all", orchestration skills |

**Total: 2 rules across 2 categories**

## CRITICAL: Task Management is MANDATORY (CC 2.1.16)

**BEFORE doing ANYTHING else, create tasks to track progress:**

```python
# 1. Create main task IMMEDIATELY
TaskCreate(
  subject="Audit Skills: full scan",
  description="Auditing all OrchestKit skills for quality and compliance",
  activeForm="Auditing skill quality"
)

# 2. Create subtasks for each audit phase
TaskCreate(subject="Discover skills", activeForm="Globbing SKILL.md files")
TaskCreate(subject="Run audit checks", activeForm="Checking each skill")
TaskCreate(subject="Classify & render", activeForm="Classifying results and rendering report")

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])
TaskUpdate(taskId="4", addBlockedBy=["3"])

# 4. Before starting each task, verify it's unblocked
task = TaskGet(taskId="2")  # Verify blockedBy is empty

# 5. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done
```

## Workflow

1. **Discover** — Glob `src/skills/*/SKILL.md` to get full skill list
2. **Check each skill** — Run all checks from `Read("${CLAUDE_SKILL_DIR}/rules/audit-checks.md")` in parallel
3. **Classify** — Apply status rules from `Read("${CLAUDE_SKILL_DIR}/rules/audit-status.md")`
4. **Render** — Output table using format from `Read("${CLAUDE_SKILL_DIR}/references/output-format.md")`
5. **Totals** — Show `X pass, Y warn, Z fail` at bottom

## Quick Start

```bash
bash src/skills/audit-skills/scripts/run-audit.sh
```

Or invoke manually — Claude scans `src/skills/`, applies checks, and renders the summary table.

> **CC 2.1.152+:** After fixing SKILL.md files surfaced by the audit, run `/reload-skills` to re-scan skill directories and pick up the changes in-session (no restart). For plugin-packaged skills, rebuild + `/reload-plugins` instead.

## Key Decisions

| Decision | Recommendation |
|----------|----------------|
| Manifest check | `"skills": "all"` in ork.json means ALL skills qualify — mark YES |
| 0 rules + refs | WARN only — some orchestration skills are legitimately rules-free |
| Broken refs | WARN (not FAIL) — file may exist under a different path |

## Related Skills

- `ork:skill-evolution` — Guidance on iterating and improving skills
- `ork:quality-gates` — Broader codebase quality checks