Summary
apm install -g <pkg> deploys per-target primitives into user-scope directories (~/.claude/skills/, ...) and writes metadata under ~/.apm/. For instructions this is not enough: the harness loads them only through a root context file (CLAUDE.md, AGENTS.md, GEMINI.md) that apm compile generates, and apm compile has no user-scope mode.
Net effect: apm install -g silently installs instructions that no harness ever picks up.
Repro
Real-world example: Netcracker/qubership-ai-packages/agent-packages/apm-authoring ships both .apm/skills/ and .apm/instructions/.
apm install -g Netcracker/qubership-ai-packages --target claude
# skills land under ~/.claude/skills/ -> picked up by Claude Code
# instructions land under ~/.apm/apm_modules/.../instructions/ -> never reach ~/.claude/CLAUDE.md
ls ~/.claude/CLAUDE.md # missing
apm compile has no --global / -g flag (see src/apm_cli/commands/compile/cli.py). The obvious workaround cd ~/.apm && apm compile --target claude writes to ~/.apm/CLAUDE.md, which Claude Code does not read.
Proposal
- When
apm install -g finishes and at least one installed package carries instructions, run the compile pipeline with scope=USER so it reads ~/.apm/apm_modules/ and writes into each active target's user-scope root context path (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md, ...).
- Add a symmetric
--global / -g flag to apm compile.
- Honour
CLAUDE_CONFIG_DIR and the equivalent env vars that TargetProfile.for_scope(user_scope=True) already handles.
- Reuse the
<!-- Generated by APM CLI from .apm/ primitives --> marker rule so a hand-authored root context file is never overwritten without consent.
Packages that contain only skills, agents, commands, hooks, or MCP already work correctly under -g -- compile is not on the path for those primitives.
Summary
apm install -g <pkg>deploys per-target primitives into user-scope directories (~/.claude/skills/, ...) and writes metadata under~/.apm/. Forinstructionsthis is not enough: the harness loads them only through a root context file (CLAUDE.md,AGENTS.md,GEMINI.md) thatapm compilegenerates, andapm compilehas no user-scope mode.Net effect:
apm install -gsilently installs instructions that no harness ever picks up.Repro
Real-world example:
Netcracker/qubership-ai-packages/agent-packages/apm-authoringships both.apm/skills/and.apm/instructions/.apm compilehas no--global/-gflag (seesrc/apm_cli/commands/compile/cli.py). The obvious workaroundcd ~/.apm && apm compile --target claudewrites to~/.apm/CLAUDE.md, which Claude Code does not read.Proposal
apm install -gfinishes and at least one installed package carriesinstructions, run the compile pipeline withscope=USERso it reads~/.apm/apm_modules/and writes into each active target's user-scope root context path (~/.claude/CLAUDE.md,~/.codex/AGENTS.md,~/.gemini/GEMINI.md, ...).--global/-gflag toapm compile.CLAUDE_CONFIG_DIRand the equivalent env vars thatTargetProfile.for_scope(user_scope=True)already handles.<!-- Generated by APM CLI from .apm/ primitives -->marker rule so a hand-authored root context file is never overwritten without consent.Packages that contain only
skills,agents,commands,hooks, or MCP already work correctly under-g-- compile is not on the path for those primitives.