jackchuka 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.authormatch)
Step 1: Setup
- Read
references/subagent-orchestration-best-practices.md— defines the rules - Read
references/agent-skill-analyzer.md— defines the per-skill analysis task - Glob
~/.claude/skills/*/SKILL.mdto discover skills. If a directory path is provided as argument, glob<path>/*/SKILL.mdinstead - Filter to skills where
metadata.authormatches the user (default:jackchuka). If skill names provided, filter to those instead - 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.
- 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:
- Merge findings across all skills
- Sort by severity: ERROR → WARN → INFO
- 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.