# Skill Loading Strategy

Open Orchestra should keep primary agent instruction files small. AGENTS.md, CLAUDE.md, Cursor rules, and ORCHESTRA.md should act as an entry point, not as the full operating manual for every capability.

## Goal

Load detailed capability instructions only when the current task needs them, while keeping core governance rules always available.

## Core Pattern

Use a two-layer model:

- **Core instructions:** short, always-loaded rules for safety, user alignment, engineering standards, gates, and how to select skills.
- **Skills:** focused sub-files with task-specific procedures, examples, scripts, templates, and evidence rules.

The main files should include a compact Skill Index instead of embedding every procedure inline.

## Skill Manifest

Each skill should expose metadata that allows a parent agent or middleware to decide whether to load it.

```json
{
  "id": "static-analysis",
  "name": "Static Analysis",
  "summary": "Run and interpret local quality, type, dependency, secret, and security checks.",
  "triggers": ["lint", "typecheck", "secret", "sast", "precommit", "dependency"],
  "roles": ["developer", "tech_lead", "qa", "sdet", "security", "devops"],
  "capabilities": ["quality-gate", "security-review", "commit-readiness"],
  "riskAreas": ["security", "release", "maintainability"],
  "entry": "skills/static-analysis/SKILL.md",
  "assets": ["skills/static-analysis/checklist.md"],
  "evidence": ["command", "report"],
  "sourceGroups": ["codebase", "quality-security", "agent-memory"],
  "loadBudget": "normal"
}
```

## Source Selection

Before loading full skill instructions, the parent agent should select authoritative source groups for the task. The source catalog lives in `.agent-workflow/source-of-truth.json` and is documented in [source-of-truth-and-agent-learning.md](source-of-truth-and-agent-learning.md).

Skill manifests should be able to declare `sourceGroups` so the orchestrator can load the right local files, docs, official vendor references, and prior lessons without pulling unrelated context.

## Loading Flow

1. Parse the task brief into goal, touched paths, impacted systems, requested outputs, risk areas, and likely roles.
2. Activate roles from the role catalog.
3. Match task signals against skill manifests by triggers, paths, runtime phase, requested evidence, and risk areas.
4. Use roles and capabilities as eligibility and ranking signals, not as automatic activation. A role may be allowed to use a skill without loading it for every task owned by that role.
5. Load only the selected skill summaries first.
6. Load the full `SKILL.md` only when the skill is needed for execution or review.
7. Load matching source-of-truth entries and recent relevant lessons for the selected skills.
8. Load skill assets, templates, scripts, or examples only at the point of use.
9. Record selected skills and source groups in task context, handoffs, evidence, and final summary.

## Runtime Activation

Skill planning separates availability from activation:

- **Available:** the role and capability catalog says a profile is allowed to use a skill.
- **Activated:** the current task, phase, risks, acceptance criteria, evidence needs, touched paths, or explicit user request require that skill now.

For example, Architect can use `qa-evidence-pack` to validate ADRs, diagrams, contracts, and architecture decisions, but it should only load that skill when the task asks for QA evidence, acceptance coverage, integration verification, visual evidence, or release evidence. The same rule applies to every profile: QA, Developer, DevOps, SRE, PO, BA, Release, and specialist roles should receive only the skills needed for the active runtime context.

## Built-in Skill Candidates

- `prompt-registry`: read and update `.generated-prompts/` registers for substantial AI-generated artifacts.
- `diagram-export`: generate, validate, and export architecture or workflow diagrams.
- `static-analysis`: run local quality, typing, SAST, dependency, and secret checks.
- `collection-standards`: centralize repeated collections and keep collection processing linear or explicitly bounded across product code, QA automation, and DevOps scripts.
- `pr-review`: produce review findings, PR summary, risks, rollout notes, and missing-test gaps.
- `playwright-evidence`: plan browser automation and attach screenshots, traces, videos, and reports.
- `backlog-sync`: keep GitHub issues, local stories, and workflow tasks aligned.
- `doc-sync`: keep architecture docs, changelog, onboarding, runbooks, site copy, and prompt registers aligned with delivered changes.
- `release-readiness`: validate gates, rollback, observability, support, and customer-impact evidence.
- `model-evaluation`: run prompt/model/provider-routing evaluations and compare outputs.
- `source-of-truth`: select authoritative project, vendor, and workflow sources before acting.
- `agent-learning`: record reusable failure lessons and promote repeated lessons into skills or rules.

## Fallback for LLMs Without Native Skills

If an LLM platform cannot load skills dynamically, Open Orchestra should provide middleware behavior:

- A parent orchestrator reads the manifest and selects skills.
- The orchestrator injects only the selected skill text into the child agent prompt.
- The orchestrator keeps full skill content out of the base system prompt.
- The loaded skill IDs are written to `.agent-workflow/` events and handoff artifacts.

This keeps the project portable across Cursor, Claude, Codex, VS Code, GitHub Actions, and future web clients.

## Main File Budget

Primary MD files should stay bounded:

- Keep role and skill catalogs as indexes with links.
- Move long procedures into skills or docs.
- Prefer activation criteria over exhaustive instructions.
- Keep examples inside the skill that owns them.
- Review file size when a main MD crosses a practical context threshold.

## Implemented CLI Surface

- `orchestra skills list` lists the canonical built-in skill catalog.
- `orchestra skills plan --task <id>` selects skills from runtime task signals, paths, risks, acceptance/evidence needs, and role/capability eligibility.
- `orchestra skills advise --prompt <text> [--role <role>] [--phase <phase>] [--risks <csv>] [--evidence <csv>] [--json]` selects skills from advisory or prompt-only runtime signals without requiring a registered task first.
- `orchestra skills render --target generic|claude|cursor|codex|vscode --task <id>` renders selected skills for a runtime or IDE.
- `orchestra skills render --target <target> --skills <csv>` renders explicit skills when no task exists.
- `orchestra skills validate` validates canonical skills against portable `manifest.json` and `SKILL.md` files.
- `orchestra sources list` exposes the source-of-truth catalog.
- `orchestra lessons list/add/promote` manages local agent learning and promotes repeated lessons into reviewable artifacts.
- `orchestra doc-sync audit [--task <id>] [--strict]` checks changed documentation, changelog, architecture, diagram, and public-site surfaces for prompt registry coverage and suggests `lessons assist` when repeated documentation rework should become a reusable lesson.

The CLI render path is the universal fallback for environments without native skill support.

## Generated Markdown Update Policy

Generated `.md`, `.mdc`, and agent instruction files should be managed through explicit ownership rules instead of blind rewrites.

- Use generated block markers such as `<!-- open-orchestra:start skill-index -->` and `<!-- open-orchestra:end skill-index -->` for sections the CLI owns.
- Keep user-authored sections outside managed blocks and never overwrite them during generation.
- Store generator metadata: generator name, version, source manifest, target file, managed block id, and last rendered hash.
- Default to idempotent updates: rerunning the generator without source changes should produce no diff.
- Provide `--dry-run` and `--check` modes before writing generated docs.
- If a generated section was manually edited, detect drift and require explicit `--force` or emit a conflict.
- Promote stable runtime lessons or prompts into versioned docs/rules/skills only through reviewed generated blocks.

This keeps Claude, Cursor, Codex, VS Code, and generic CLI outputs synchronized without turning primary instruction files into unbounded generated blobs.