# Skill Loading and Injection (Copilot CLI orchestrator)

Two mechanisms decide what a sub-agent knows: trigger-based dynamic loading (opt-in)
and the skills embedded in each agent persona, plus the task context the orchestrator
adds to every dispatch.

## Dynamic skill loading  -  trigger-based injection (opt-in)

**Gated by `prefs.global.dynamicSkillLoading` (default `false`).** When enabled, the orchestrator moves from eager-loading all 206 skills on every session to injecting only the skills that match the current task context. The match signal comes from these sources in descending weight:

1. `trigger-paths` globs in SKILL.md frontmatter vs. Phase 1 touched files (heaviest, +30 max)
2. `trigger-keywords` in SKILL.md frontmatter vs. task text (mid, +30 max)
3. `description` keyword overlap with task text (lightest fallback, +15 max)
4. Platform match vs. Phase 1 detected stack (+10)

**Runtime contract:**

```bash
# After Phase 1 produces analysis.json with {stack.primary, touchedAreas[].path}
task_text="$(jq -r '.summary' analysis.json)"
touched=$(jq -r '.touchedAreas | map(.path) | join(",")' analysis.json)
stack=$(jq -r '.stack.primary' analysis.json)

matched_skills=$(node "$HOME/.claude/scripts/match-skills.mjs" \
  "$task_text" \
  --touched-files "$touched" \
  --stack "$stack" \
  --limit 12 \
  --json)

# Inject only matched skills[] into subagent prompts for Phase 1-3.
# Skills not in the matched list are not loaded  -  saves ~10K-30K tokens
# per subagent dispatch on small tasks.
```

**Fallback:** every install ships `.skills-index.json` beside the skills. If it is absent anyway (a checkout before `build-skills-index.mjs` runs), the orchestrator eager-loads every skill  -  dynamic loading never blocks the happy path.

**--index-only installs:** `node install.js --index-only` writes only the index, not the 206 SKILL.md payloads. Intended for CI pipelines that fetch skill bodies on demand, and disk-constrained users who accept the dynamic-load contract.

When `dynamicSkillLoading=true` AND the target install is index-only, subagent prompts must include the matched skills' bodies inline (read from the pipeline source or a cached copy). The orchestrator resolves this by reading `{PIPELINE_SRC}/pipeline/skills/{relativePath}`  -  the pipeline source repo is always the source of truth; the install dir is a cache.

**Telemetry:** when `MULTI_AGENT_OTEL_SPANS=1`, emit `phase.skills.match` span with `{taskId, matchedCount, topN=[name,score]}` so post-hoc analysis can tune trigger-keywords / trigger-paths in SKILL.md frontmatter.

## Skill Injection Strategy

Sub-agents have embedded skills in their `.agent.md` files. Each agent is pre-loaded with domain-specific knowledge:

| Agent | Embedded Skills | When Activated |
|-------|----------------|----------------|
| **code-reviewer** | Code Review Excellence, Security Audit, Performance Review, TDD Verification, Error Detective | Phase 3: Review |
| **ios-architect** | Spec-Driven Architecture, Context Management, Multi-Agent Coordination, API Design, Performance Architecture, Design System Governance | Phase 1: Plan |
| **security-auditor** | iOS Security Deep Dive, App Store Review Gates, Third-Party SDK Risk, Error Detective (Security) | Phase 3: Review |

### Phase → Agent → Skills Flow

```
Phase 1: Plan  -  analysis half
  ├─ explore agents (no skills needed  -  pure file reading)
  └─ security-auditor agent
       └─ Skills: iOS Security Deep Dive, App Store Review Gates, SDK Risk

Phase 1: Plan  -  planning half
  └─ ios-architect agent
       └─ Skills: Spec-Driven Architecture, API Design, Performance Architecture

Phase 2: Dev
  └─ Ana agent (reads copilot-instructions.md directly)
       └─ TDD, token rules, code style  -  from global instructions

Phase 3: Review (parallel + triage)
  Claude Code  (3 parallel):
    ├─ code-reviewer (claude-opus)   → all 5 review skills
    └─ code-reviewer (claude-sonnet) → all 5 review skills
  Copilot CLI  (3 parallel):
    ├─ code-reviewer (gpt-5.4)       → all 5 review skills
    ├─ code-reviewer (claude-opus)   → all 5 review skills
    └─ code-reviewer (claude-sonnet) → all 5 review skills
  Triage (both): claude-opus over merged findings
```

### Context-Aware Skill Injection

When calling sub-agents, the ana agent SHOULD add task-specific context to the prompt:

```
For code-reviewer in Phase 3:
  "Review this diff for PROJ-{id}. Focus areas based on analysis:
   - {files changed summary from Phase 1}
   - {architecture decisions from Phase 1}
   - {specific risk areas identified}"

For ios-architect in Phase 1:
  "Evaluate architecture for PROJ-{id}. Context:
   - {task description from Jira/GitHub}
   - {affected modules from Phase 1 analysis}
   - {existing patterns found by explore agents}"
```

This ensures sub-agents get both their embedded skills AND task-specific context.