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:

How to detect latent parallelism in multi-step workflows:

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

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)

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