claude-skill-orchestration-audit

# Skill Orchestration Audit

Check skills against orchestration best practices in `references/subagent-orchestration-best-practices.md`.

## Arguments

- **Skill names**: filter to specific skills
- **--fix**: suggest and apply corrections interactively
- **Default**: scan all skills authored by the user (`metadata.author` match)

## Step 1: Setup

1. Read `references/subagent-orchestration-best-practices.md` — defines the rules
2. Read `references/agent-skill-analyzer.md` — defines the per-skill analysis task
3. Glob `~/.claude/skills/*/SKILL.md` to discover skills. If a directory path is provided as argument, glob `<path>/*/SKILL.md` instead
4. Filter to skills where `metadata.author` matches the user (default: `jackchuka`). If skill names provided, filter to those instead
5. Classify each skill into one of these categories:

| Category                 | Audit type              | Signal                                                                |
| ------------------------ | ----------------------- | --------------------------------------------------------------------- |
| Multi-source aggregation | Orchestration quality   | Already dispatches 2+ parallel agents against independent sources     |
| Multi-step workflow      | Latent parallelism scan | Sequential phases where some sub-tasks within a phase are independent |
| Single-source operation  | Skip                    | One tool/API, truly linear flow, no fan-out possible                  |
| Meta/utility             | Skip                    | Routers, reference libraries, formatters                              |

**How to detect latent parallelism in multi-step workflows:**

Look for phases that iterate over N independent items — even if written as sequential steps:

| Pattern | Example | Signal |
|---------|---------|--------|
| Per-item scaffolding | "scaffold X for each actor/flow/feature" | N independent CLI calls |
| Per-item implementation | "write one file per resolver/page/command" | N independent file writes to separate paths |
| Multi-source research | "search Odoo, Oracle, SAP" | N independent web fetches |
| Independent tracks | "implement commands" then "implement queries" | Parallel tracks after a shared dependency |

A skill is "multi-step workflow" (audit it) if any phase has 2+ items that don't depend on each other. If every phase is truly linear with no fan-out, classify as "single-source operation" and skip.

6. Set `SKILLS_TO_AUDIT` = all skills classified as "multi-source aggregation" or "multi-step workflow"

## Step 2: Dispatch Agents (parallelize if possible)

Launch one agent per skill in `SKILLS_TO_AUDIT`. Each agent receives:

- The skill's SKILL.md content
- The skill's `references/` directory listing (if any)
- Its classification from Step 1
- The check rules from `references/agent-skill-analyzer.md`

Each agent returns structured findings per the format in the reference file. If a skill's SKILL.md can't be read, skip gracefully.

## Step 3: Aggregate & Report

After all agents return:

1. Merge findings across all skills
2. Sort by severity: ERROR → WARN → INFO
3. Produce single consolidated report:

```
## Orchestration Audit

### Skills with existing orchestration

| Skill | Category | S1-4 | P1-4 | C1-3 | A1-3 | X1-4 | Issues |
|-------|----------|------|------|------|------|------|--------|

### Skills with latent parallelism opportunities

| Skill | Opportunity | Phase | Benefit | Issues |
|-------|-------------|-------|---------|--------|

### Findings

#### [skill-name]: [issue count] issues
- **[RULE]:[SEVERITY]** — [description]
  - Current: [what the skill does now]
  - Suggested: [what it should do]

### Top N Highest-Impact Improvements
Rank by benefit (high > medium > low) and usage frequency.

### Summary
N skills checked, M have orchestration, P have latent parallelism, X issues found (E errors, W warnings, I info)
```

## Fix (if --fix or user asks)

| Severity | Action                                            |
| -------- | ------------------------------------------------- |
| ERROR    | Show the fix, apply with Edit after user confirms |
| WARN     | Show suggestion, apply only if user agrees        |
| INFO     | Note for awareness, no auto-fix                   |

After fixing, re-run the check and show updated table.