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.