[FEATURE] Compile should deploy agents and skills to .claude/ for Claude Code target

[ryanfk]

Summary

apm compile --target claude currently only generates distributed CLAUDE.md files from instructions. It does not deploy agents or skills from apm_modules/ into .claude/agents/ or .claude/skills/. These primitives are left stranded in apm_modules/ and never reach Claude Code's native discovery directories.

Current behavior

apm install pkg   → fetches into apm_modules/     ✅
apm compile       → merges instructions → CLAUDE.md  ✅
                  → agents?  not deployed             ❌
                  → skills?  not deployed             ❌

After compile, .claude/ contains no agents or skills from installed packages. Claude Code never discovers them.

Desired behavior

apm compile --target claude should produce a complete, ready-to-use .claude/ directory:

apm_modules/.apm/agents/*.md         →  .claude/agents/
apm_modules/.apm/skills/*/SKILL.md   →  .claude/skills/
apm_modules/.apm/instructions/*.md   →  CLAUDE.md (distributed, already works)

One command. Everything deployed. Claude Code picks it up on next session.

Why this belongs in compile, not install

1. Install fetches. Compile deploys.

apm install should do one job: resolve dependencies and populate apm_modules/. This mirrors npm install populating node_modules/ without modifying the app's source tree.

apm compile is where apm_modules/ content gets transformed and placed for the target platform. This is the step that understands target-specific output layouts.

2. Different targets need different output layouts

The same .apm/ package contents need to land in different places depending on the target:

Source	--target vscode	--target claude
.apm/agents/	.github/agents/	.claude/agents/
.apm/skills/	.github/skills/	.claude/skills/
.apm/instructions/	AGENTS.md (distributed)	CLAUDE.md (distributed)

Target awareness is a compile-time concern. The package format (.apm/) is target-agnostic by design.

3. Claude Code's architecture requires discrete files, not merged markdown

Claude Code manages context through on-demand agent spawning. This is fundamentally different from tools that pre-load all instructions:

• Agents (.claude/agents/) are self-contained context capsules. Claude reads the description, spawns the agent into a fresh context window only when a request matches. The main thread stays lean.
• Skills (.claude/skills/) are specialized capabilities that Claude discovers and activates on demand.
• Instructions (CLAUDE.md) are lightweight, always-loaded guidance.

Agents and skills are discrete primitives — they should be placed as individual files, not merged into CLAUDE.md. The current compile treats everything as instructions to merge. It should recognize the different primitive types and handle each appropriately for the target.

4. Enables a clean rebuild cycle

apm compile --target claude --clean   # wipe and regenerate from apm_modules/

This makes .claude/ a derived artifact — fully reproducible from apm.yml + apm_modules/. Similar to how build output is regenerated from source and dependencies.

Reproduction steps

apm install dev.azure.com/org/project/shared-configs  # package with agents + skills
apm compile --target claude --verbose
ls .claude/agents/    # empty — agents not deployed
ls .claude/skills/    # empty — skills not deployed

Principle

Match the output format to how the target platform actually consumes it. Claude Code consumes agents as files in a directory, not as blocks in a markdown document. Compile should respect that.

[ryanfk]

Related: #93 — requests the same pattern for GitHub Copilot agentic workflows (.workflow.md as a primitive type deployed to .github/workflows/).

Both issues point to the same underlying gap: APM's compile step needs to be target-aware for all primitive types, not just instructions. Each target platform has its own set of consumable primitives and expected directory layouts:

Primitive	.apm/ source	--target claude	--target vscode
Instructions	.apm/instructions/	CLAUDE.md (distributed)	AGENTS.md (distributed)
Agents	.apm/agents/	.claude/agents/	.github/agents/
Skills	.apm/skills/	.claude/skills/	.github/skills/
Workflows	.apm/workflows/	n/a	.github/workflows/

Compile should handle the full primitive set for each target, placing discrete files where the platform expects them.

[danielmeppiel]

That's right - it should be apm install integrating the primitives into .claude in the same way it happens today for .github. Reason to put it into install is because I'd rather deprecate the compile command ASAP in favor of a configurable, single install command that just works. I'd argue that's better UX than having to tap into two different commands.

Please note that currently, commands and skills already deploy to .claude if that folder exists. So we are missing agents.

For reference:

• Subagents Claude spec: https://code.claude.com/docs/en/sub-agents
• Commands spec (akin to prompts, already integrated - now merged into Skills): For built-in commands like /help and /compact, see interactive mode.
  Custom slash commands have been merged into skills. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review and work the same way. Your existing .claude/commands/ files keep working. Skills add optional features: a directory for supporting files, frontmatter to control whether you or Claude invokes them, and the ability for Claude to load them automatically when relevant.
• Skills spec: https://code.claude.com/docs/en/skills

[danielmeppiel]

@ryanfk fixing this in #95 . Skills should already be working if the .claude folder exists in the repo where you run apm install. Does this PR work for you?