Files

Defame1297 82b7bbcf5c docs: close the PR #135 documentation review findings

Group 3 of the validated PR #135 review fixes. Every figure and commit
citation below was re-verified at HEAD before being written.

ADR and architecture:
- #7 ADR-0025 cited 61b0b9c, which no published branch reaches. Repointed
  to 620f20b (identical parent tree, reachable from the PR branch), with a
  note that neither is reachable from origin/main. The parser-drift
  paragraph now credits 598a7c3 (the reachable PR #129 squash) and keeps
  484357a only as a pre-squash parenthetical.
- #8 architecture.md dropped the pointer at the LESSONS.md entry this
  branch deleted.
- #9 architecture.md's ADR entry points now name ADR-0015 (the one
  compiler) and ADR-0024, and list ADR-0024 as superseding ADR-0017.
- #10 ADR-0024 section 4 rewritten: the standing patch-bump rule is
  apm-workflow's configure.md, not ADR-0006's, and this change does not
  trigger it. ADR-0015:93 carries a correction for the misattribution.
- N5 ADR-0021 gained a Correction note for the deleted
  scripts/check-manifests.sh (e647f14).

gates.md:
- #11a the four ADR-0020 constants live in lib-checks-skill.sh:313-316 and
  lib-checks-agent.sh:164-165, not in validate.sh.
- #11b the pretty-format-json exclude is two alternations expanding to
  three tracked files, including .claude/apm-hooks.json.
- #11c the ADR-0020 contract suite runs 28 -> 27 -> 29 (620f20b,
  4de5b6b, ef27c97), 29 at HEAD; the unverifiable 25 is dropped.
- #11d the boundary resolver is one copy since ef27c97.
- #12 apm-audit-ci documents the 10 root checks and the 1 plugin check
  apm 0.28.0 actually runs, that content-integrity IS the hidden-Unicode
  scan, that manifest-parse is not a named check, and that the hook needs
  a completed apm install. The offline claim is qualified accordingly.
- N9 gates.md:142-146 verified to still match the hook description.

AGENTS.md:
- #12 the no-network session rule is qualified to a populated
  apm_modules/.

Audit note:
- A1 hook counts corrected to 27/9 -> 26/8 -> 27/9 -> 26/8 (26 and 8 at
  HEAD) and the dangling pointer dropped.
- A2 skill-size-check.sh is 509 lines with the resolver sourced, not 1,522
  embedded; citations repointed to skill-size-check.sh:323-335 and
  lib-checks-skill.sh:235-283 (fail() at :265 and :280), and that library
  is 627 lines.
- A3 consumers receive 15 test files across 5 skills; 16 tracked test
  paths repo-wide.
- A4 the "do not run apm update on this branch" instruction is marked
  superseded, with the branch-aware guidance in its place.
- Finding 31's "true orphans" claim corrected for HOTL and Sycophancy,
  both still used in core/ai-constitution.md.

Same class, found during group 2:
- skill-author's deployment-modes.md no longer points at .mcp.json
  configs (deleted in c96ca9c); metadata.version 1.0.2 -> 1.0.3.
- git-orchestrate's context contract clarifies that
  user_config_overrides is caller-supplied session state, not a config
  read. The field name is unchanged.
- B3 root apm.yml's executables.allow comment: grants are version-blind
  in apm 0.28.0, so the #2.0.0 suffix is cosmetic to apm and a bump does
  not break the hook; the suffix stays because
  check-executables-allow-sync.sh requires it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NwD8Egs5r4ndqeFLmhusX2

2026-09-19 21:30:29 +00:00

3.5 KiB

Raw Blame History

source_keys

agentskills-spec

Deployment Modes

Skills deploy standalone, or as part of an APM package (an apm.yml-governed .apm/ tree, compiled via apm compile). Some consumers also receive a package through a host's plugin install, which copies it into a cache. All modes 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 (host plugin install)

When a host installs a plugin, it copies the plugin directory 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/<plugin>/.apm/skills/other/     # 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 — 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. /factory-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.

3.5 KiB Raw Blame History