Defame1297
061bb3d5b4
A five-agent review of718c79aandd2480b8found no skill, agent or hook regressions (39 skills before and after) and confirmed both hook removals are genuinely moot -- verified against the tree, not taken on the commit's word. It did find one functional regression (fixed separately) and this documentation drift. Counting errors, all from a git pathspec `*` crossing `/`: - 17 .bats files shipped to consumers is really 10; 17 counted tracked paths merely containing /tests/, one of them a template asset - "roughly 88s off every push" is ~92.4s; 88 omitted validate-plugins - "roughly 70% of each plugin remains live" holds only for kyberforge; the real spread is 44.3% (bin) to 70.6%, now a table - the pre-push enforcement row was half-corrected: 33 entries stood unstruck (now 27) and 14 -> 11 switched counting basis mid-sentence - the root .claude-plugin/plugin.json was described as "kept"; it has never been tracked gates.md said "Ten hooks" above a nine-row table (11 was decremented for one removal, not two), and "both need the claude CLI" for one remaining validator. Its pretty-format-json exclude rationale claimed six alternations expanding to sixteen files in a passage headed "Mind which number you are quoting" -- four alternations, two live files; the two dead ones are dropped from the pattern. check-useless-excludes could not catch this: it only flags an exclude matching nothing at all. ADR-0024 cited ADR-0006 for a patch-bump rule it does not contain and which ADR-0015 explicitly retired; stated apm's marketplace probe order backwards (.claude-plugin/ is the last candidate, not the first, so the earlier .github/plugin/ deletion only demoted resolution); undercounted apm's skill-deploying targets as seven when there are fifteen; and never recorded that validate-plugins was removed. The symlink hedge is resolved: apm_cli/security/gate.py's ignore_non_content() drops symlinks silently on deploy while apm_modules/ materialization dereferences them, so content survives that far and vanishes at install. Accepted with no replacement guard, per decision -- kyberforge/docs/hooks.md previously asserted a guard that had been deleted with its script. Four plugin READMEs still advertised `claude plugin install`; ADRs 0001, 0006, 0013, 0014, 0015 and 0019 described deleted machinery in the present tense, 0019 most consequentially as the live justification for the SessionStart hook's .apm/ path. CONTEXT.md's "apm package" entry forbade "plugin" while using it in its own body, and "Output profile" lost the antecedent for "one catalogue serves both". run-tests.sh gains the .claude/skills/ exclusion run-bats.sh already had. Latent today -- no test-*.sh lives under any .apm/skills/*/tests/ -- but apm now deploys those directories, so one would be discovered twice. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
28 lines
2.4 KiB
Markdown
28 lines
2.4 KiB
Markdown
# 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.
|