Defame1297
5e232503c4
Why: ADR-0015 established that Microsoft APM (apm.yml + .apm/) should replace this repo's hand-authored plugin.json/marketplace.json model, with those files becoming compiled output of `apm pack` instead of files edited by hand via the (now-retired) plugin-author/marketplace-author skills. Issue #90 was the deferred execution of that decision, gated on #88 (apm tooling) and #89 (apm-native agent-author/skill-author routing). Implementation notes: - All six plugins (bin, core, git, gitea, kyberforge, lint) now carry apm.yml + .apm/{skills,agents,hooks} as their authoring source. Skills moved with a plain git mv (content-identical across targets). Agents were re-authored, not moved: per ADR-0016, .apm/agents/*.agent.md compiles verbatim to both Claude and Copilot, so plugin-scope agents now carry only name/description/model/source_keys -- no tools: field, no Claude-only knobs (isolation, maxTurns, effort, memory, permissionMode). - Root apm.yml registers all 7 marketplace packages (6 local plus mattpocock-skills as a remote entry) under versioning: per_package, matching this repo's existing independent-plugin-versioning practice. - .claude-plugin/marketplace.json and every plugin's plugin.json are now apm-pack-compiled output, verified against the prior hand-maintained content: same names/descriptions/versions/licenses/authors, only cosmetic serialization differences (JSON key order, owner email vs. url, Unicode escaping). - plugin-author and marketplace-author are retired now that apm-based authoring fully replaces their job; kyberforge bumped 1.3.1 -> 1.4.0 for that removal, and the root marketplace catalog bumped 0.3.1 -> 0.3.2 to match, per the version-bump convention now documented in apm-workflow's reference docs instead of a dedicated script (apm has no native version-bump automation). - Fixed hardcoded pre-.apm/ path assumptions across .pre-commit-config.yaml, .pre-commit-hooks.yaml, scripts/check-scope-walkup-sync.sh, scripts/sync-vale-styles.sh, scripts/check-vale-style-sync.sh, six plugins' root plugin.json (stale skills/hooks/agents pointer fields that check-manifests.sh validates), and several tests/*.bats and tests/*.sh fixtures -- including a bats REPO_ROOT relative-path depth bug (10 files, one extra .apm/ directory level to walk up) and a vale probe-path isolation regression introduced mid-fix. - Corrected empirically-wrong assumptions surfaced this session in apm-workflow/apm-install's own reference docs: `apm marketplace package add` does not accept local paths (only owner/repo remote shorthand -- local packages are registered by editing apm.yml's marketplace.packages[] directly); `apm compile` is a consumer-side AGENTS.md/CLAUDE.md generator, not the plugin.json producer, and hard-fails on skill/agent-only packages without --clean; `apm plugin init <name>` nests a stray subdirectory when run with a positional name arg from inside a same-named directory; no native Copilot marketplace output profile exists; .mcp.json is merged into the compiled plugin.json content-aware and target-scoped, with no dependencies.mcp entry needed for simple passthrough; pipx is the correct pip fallback on externally-managed Python environments. - Renamed agent-author's copilot.agent.md template asset to copilot.agent.md.template so apm compile's recursive *.agent.md glob stops misparsing the placeholder template as a real agent primitive. Impact: plugin.json and marketplace.json are compiled artifacts from here on -- editing them by hand is no longer the workflow; edit apm.yml/.apm/ and run apm pack. CONTEXT.md's Plugin/Plugin marketplace glossary entries reflect this. ADR-0001 is marked superseded, ADR-0006 moot, and ADR-0010 updated for the new .apm/agents/ path (project/user scope unaffected, per ADR-0016). Full local verification: claude plugin validate --strict on all 6 plugins, apm audit --ci, apm marketplace check, check-manifests.sh, and the full test suite (165/165 bats, 13/13 shell scripts) all pass clean. Fixes: #90 Refs: #88, #89 ADR: 0015 ADR: 0016 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ub96PyaSRD9BHPktotj1pC
3.4 KiB
source_keys
| source_keys | |
|---|---|
|
Deployment Modes
Skills deploy standalone, or as part of a package — either a legacy plugin-mode cache install or an APM (apm.yml-governed .apm/ tree, compiled via apm compile). All resolve relative paths from the skill root — the SKILL.md body works the same in any of them. Differences only arise when referencing files outside the skill directory.
Cache isolation (plugin mode)
When a plugin is installed, its directory is copied to a cache. Only the plugin's own files are copied. Any path that leaves the skill directory breaks post-install:
../other-skill/validate.sh # breaks
plugins/kyberforge/skills/other-skill/ # breaks
../../shared/utils.sh # breaks
Fix: duplicate the file into the skill's own scripts/ or assets/. There is no plugin-level shared/ mechanism — the spec defines no cross-skill sharing, and ../ paths are broken by construction.
Compiled output (APM package mode)
For a package (an apm.yml-governed .apm/ source tree), the deployable artifact is generated by apm compile per target harness — not produced by copying the raw .apm/ directory wholesale the way a plugin cache install copies a plugin directory. The same self-containment rule still applies at the skill level: file references inside .apm/skills/<name>/ must not reach outside that skill's own directory.
../other-skill/validate.sh # breaks
.apm/skills/other-skill/ # breaks
../../shared/utils.sh # breaks
Fix: duplicate the file into the skill's own scripts/ or assets/, same as plugin mode. apm.yml's includes: list (when explicit, not auto) controls what gets published from the package, but it is not a cross-skill sharing mechanism — each skill directory must still stand alone.
Env vars (plugin mode only)
These variables are injected when the plugin is loaded from an install cache. They are not available in standalone mode.
| Variable | Value |
|---|---|
${CLAUDE_PLUGIN_ROOT} |
Absolute path to the plugin's install directory. Changes on update. |
${CLAUDE_PLUGIN_DATA} |
Persistent directory that survives updates. Use for node_modules, generated state, caches. |
Use ${CLAUDE_PLUGIN_ROOT} only in hook commands and .mcp.json configs — not in SKILL.md body text, since standalone deployments won't have it.
Standalone mode
Deployed directly to ~/.agents/skills/<name>/. No plugin context, no env vars injected. All file references must resolve within the skill directory. Skill invocations (e.g. /skill-audit) work if the called skill is also installed.
Cross-tool portability
SKILL.md is portable — the same file works in Claude Code and Copilot CLI, whether deployed standalone or compiled from an APM package. apm.yml is the source manifest: it is itself tool-agnostic (one file describes the package regardless of target), but apm compile produces per-target compiled output — a Claude Code plugin tree, a Copilot CLI tree, etc. — from it. Legacy hand-authored manifest files (plugin.json, hooks.json) are tool-specific and authored separately per tool; they sit outside the apm.yml-based flow.
Shared assets between skills
If two skills in the same plugin need the same file, duplicate it into each skill's assets/ or scripts/. Add a comment in both copies noting the mirror relationship so they stay in sync when the spec changes.