# Skills are distributed via plugins, not monolithic repo deployment

**Superseded by:** ADR-0015 (Microsoft APM replaces the hand-authored plugin/marketplace model
as this repo's authoring source of truth) and, for plugin-scope agent files specifically,
ADR-0016 (plugin-scope `.apm/agents/*.agent.md` drops provider-specific fields). Since issue
#90's conversion executed, plugin content is authored under `plugins/<name>/apm.yml` +
`.apm/{skills,agents,hooks}/` — not the flat `skills/`/`agents/` layout this ADR describes —
and `.claude-plugin/plugin.json`/`.github/plugin/plugin.json` were compiled output of `apm pack`,
not hand-authored — and as of ADR-0024 (2026-09-14) both are deleted, along with native
`claude plugin install` support; `apm install` is the only route. This ADR's content is kept
below as the historical record of the pre-APM decision; it is no longer the current model.

---

Skills (slash commands) are authored and distributed as part of **plugins** — each plugin contains its own `skills/` directory alongside agents and other artifacts. Plugins are installed via `claude plugin install <name>@holocron` rather than deployed from the repo's local tree. This decision decouples skill authoring cadence from core provider deployments and allows independent versioning per plugin.

## Context

Initially, skills were stored in a single `.agents/skills/` directory and deployed universally via `install.sh`. This created a coupling problem: shipping a new skill required shipping an entire repo release, and skill updates were pinned to provider version releases. As the skill library grew, independent skill shipping became essential.

## Consequences

- Skills are now co-located with their associated agents and infrastructure in `plugins/<name>/`. Logically related skills ship together; independent skills can ship on independent cadences.
- `claude plugin install` handles installation, versioning, and updates — no need for shell deployment logic in `install.sh`.
- Repositories that use skills from this project declare plugin dependencies in their `claude.plugin.json` manifest or install via the CLI.
- Providers that do not natively understand `claude plugin install` (hypothetically) would need a custom adapter to fetch from the Holocron marketplace — deferred concern, not yet needed.
- A skill in one plugin does not block a breaking change in another plugin.