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
2.4 KiB
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 installhandles installation, versioning, and updates — no need for shell deployment logic ininstall.sh.- Repositories that use skills from this project declare plugin dependencies in their
claude.plugin.jsonmanifest 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.