Compile your package

apm compile reads your instructions primitives from .apm/ (plus any unpacked under apm_modules/) and writes the per-harness root context files each agent harness reads at startup. It does not fetch packages, does not resolve dependencies, does not write the lockfile, and does not deploy other primitive types.

Compile is bounded to the active Git checkout. It does not discover instructions inside a nested Git repository or linked worktree, even when includes: auto is set, and it does not write or clean generated files there. Run apm compile from the nested checkout when you want to compile it.

When you actually need it

Compile is optional for the copilot target – GitHub Copilot natively reads .github/instructions/*.instructions.md (with their applyTo: frontmatter) that apm install already deploys, so the aggregated AGENTS.md / copilot-instructions.md it produces are a nice-to-have, not a requirement.

Compile is recommended for every other target (claude, cursor, codex, gemini, grok-build, antigravity, opencode, windsurf, kiro) – those harnesses load instructions through the root context file (CLAUDE.md, AGENTS.md, GEMINI.md) or a harness-specific rules folder that compile generates. Kiro receives .kiro/steering/ files; its AGENTS.md output remains the cross-harness fallback. Without compile, your instructions are on disk but the harness will not pick them up.

apm compile

Concretely, that command rolls your instructions/*.instructions.md (see Instructions) into the native rules surface each target expects:

• AGENTS.md – the cross-harness root context file. Copilot, Codex, Grok Build, OpenCode, and Windsurf read it directly; Kiro primarily uses the .kiro/steering/ files that compile also emits.
• CLAUDE.md – Claude Code’s root context file.
• GEMINI.md – Gemini CLI’s root context file.
• per-harness rules trees that mirror each instruction’s applyTo: glob: .github/instructions/, .claude/rules/, .cursor/rules/*.mdc, .windsurf/rules/, .kiro/steering/.

Other primitive types – prompts, skills, agents, hooks, commands – are NOT compiled by this command. They are deployed by apm install directly into the harness directories that consume them (.github/prompts/, .agents/skills/, .claude/commands/, etc.). For the full reach map, see Primitives and targets. For the place compile takes in the broader flow, see Lifecycle.

The authoring loop

edit .apm/instructions/  ->  apm compile  ->  inspect AGENTS.md  ->  repeat

You will run this loop while writing or refining instructions. Three flags speed it up:

apm compile --watch              # re-run on every change
apm compile --validate           # check frontmatter and structure; emit nothing
apm compile --dry-run            # print placement decisions without writing files

--validate is the fastest signal that an instruction parses. --dry-run shows you exactly which root-context tree (AGENTS.md, CLAUDE.md, …) would be written where. --watch is the tight inner loop while you edit prose.

To preview a script that wraps a .prompt.md file, use apm preview instead. apm compile builds the root context files; apm preview shows the rewritten command line your script will execute.

Pick a target

By default apm compile detects targets from your workspace (see detection cascade below). Override it with --target (-t):

apm compile --target claude
apm compile --target copilot,cursor          # comma-separated
apm compile --all                            # default stable target set

Canonical targets are copilot, claude, grok-build, cursor, opencode, codex, gemini, antigravity, windsurf, kiro, agent-skills, and hermes. The all selector is not a target; it expands to every canonical target except the explicit-only antigravity, agent-skills, and hermes targets. Compiling for agent-skills is a successful no-op because apm install deploys skills.

The accepted intellij entry is MCP-only, not a canonical target, and excluded from all. Compile uses the Copilot profile for its file primitives and produces AGENTS.md; IntelliJ-specific integration remains MCP-only. Unknown slugs are rejected before any work runs.

Experimental targets (openclaw, copilot-cowork, copilot-app, grok-cloud) are deployment targets for apm install --target <flag> once enabled via apm experimental enable <flag>, and are excluded from --all. apm compile does not emit harness-specific output for them. Stable explicit-only Hermes and the other agents-family harnesses read the standard AGENTS.md your normal apm compile flow already produces. See Hermes Agent.

Detection cascade

When you omit --target, APM resolves which targets to build in this order:

1. Explicit --target <slug> flag.
2. The targets: field in your apm.yml.
3. Auto-detect from the documented filesystem signals.
4. Fallback: minimal – writes a single AGENTS.md and skips per- harness rules folders.

Pin targets: in apm.yml if you want the same compile output on every machine. Full rules and the per-target output map live in Primitives and targets.

Where instructions land

Per target, with the rules shape on disk after compile:

Target	Root context file	Per-rule output	Compile required?
copilot	AGENTS.md	.github/instructions/<name>.instructions.md (preserves applyTo)	No – Copilot reads the per-rule files natively; deduplicates with .github/instructions/ (see below)
claude	CLAUDE.md	.claude/rules/<name>.md	Yes – deduplicates with .claude/rules/ (see below)
grok-build	AGENTS.md (folded)	.grok/rules/*.md	Yes – folded into AGENTS.md
cursor	–	.cursor/rules/<name>.mdc	Yes – .mdc is Cursor’s rules format
codex	AGENTS.md (folded)	none – compile-only, no per-file deploy	Yes – folded into AGENTS.md
gemini	GEMINI.md (folded)	none – compile-only, no per-file deploy	Yes – folded into GEMINI.md
antigravity	AGENTS.md (folded)	.agents/rules/<name>.md	Yes – folded into AGENTS.md
opencode	AGENTS.md (folded)	none – compile-only, no per-file deploy	Yes – folded into AGENTS.md
windsurf	–	.windsurf/rules/<name>.md	Yes – compiled to Windsurf rules
kiro	AGENTS.md (fallback)	.kiro/steering/<name>.md	Yes – compiled to Kiro steering

compile vs install

You want to…	Run
Iterate on instructions in .apm/instructions/	apm compile
Deploy prompts, skills, agents, hooks, commands, MCP	apm install (see Install packages)
Add a dependency or refresh apm_modules/	apm install
Verify deployed bytes match the lockfile	apm audit

apm install deploys individual primitives but does not generate aggregate context files. On a clean checkout, run apm install && apm compile when you need AGENTS.md, CLAUDE.md, or GEMINI.md. Run apm compile by itself when iterating on instructions without install’s dependency side effects.

Copilot deduplication

When .github/instructions/ is already populated with .instructions.md files (deployed by apm install --target copilot), apm compile --target copilot omits AGENTS.md entirely when the only content it would carry is the instructions section – Copilot already reads .github/instructions/ directly, so an instructions-only AGENTS.md would be redundant. AGENTS.md is still written when it carries non-instruction content such as a constitution. If .github/instructions/ is later cleared, re-running apm compile restores AGENTS.md with the full instructions section.

This deduplication is target-aware: it only activates when the sole AGENTS.md consumer is Copilot. When compiling for targets that do not read .github/instructions/ (Codex, OpenCode, Windsurf, etc.), instructions are always included in AGENTS.md regardless of whether .github/instructions/ exists. To opt out of deduplication even for Copilot-only compiles, pass --force-instructions (alias: --no-dedup):

apm compile --target copilot --force-instructions

Claude Code deduplication

When .claude/rules/ is already populated with instructions, apm compile --target claude automatically omits the instructions section from CLAUDE.md to avoid duplicate content in Claude Code’s context window. The directory can be populated by either apm install --target claude or by an earlier apm compile --target claude run – both write per-file instruction rules into .claude/rules/. CLAUDE.md is still generated when it carries a constitution or dependency @import paths. If .claude/rules/ is later removed, re-running apm compile restores the instructions section to CLAUDE.md.

To opt out of the deduplication and always include the instructions section in CLAUDE.md (for debugging or when you intentionally want both copies), pass --force-instructions (alias: --no-dedup):

apm compile --target claude --force-instructions

This flag affects both the Claude and Copilot deduplication paths (see Copilot deduplication).

Managed-section mode

By default apm compile replaces an APM-generated AGENTS.md entirely and retains an unmarked project-root file. If your team keeps hand-written content in root AGENTS.md alongside APM-managed rules, use managed-section mode to update only the APM-owned block while leaving everything else untouched.

For the full apm.yml key reference for compilation.agents_md, see the compilation.agents_md section in the manifest schema.

1. Add markers to AGENTS.md:

<!-- apm:start -->
<!-- apm will insert content here -->
<!-- apm:end -->

2. Enable the mode in apm.yml:

compilation:
  agents_md:
    mode: managed_section
    start_marker: "<!-- apm:start -->"
    end_marker: "<!-- apm:end -->"

The default markers are <!-- apm:start --> and <!-- apm:end -->, so you can omit start_marker and end_marker if you use those verbatim.

Constraints:

• An existing target file must carry the markers. New distributed placements are created with a managed block, ready for later recompiles. This automatic bootstrap applies only to distributed placements; add markers yourself before enabling the mode for a single-file AGENTS.md.
• Both markers must be present in the file exactly once (missing or duplicate markers raise a loud error so no content is silently lost).
• The start marker must appear before the end marker; reversed order raises a loud error.
• start_marker and end_marker must be distinct non-empty strings.
• Content outside the markers is preserved verbatim across every compile run; only the block between the markers is replaced. When source attribution emits a footer, it identifies this block as a generated section rather than describing the whole file as generated.
• In distributed compile mode, the same marker rules apply to every generated AGENTS.md. A placement in a nested Git repository (a .git directory or gitfile), including its descendants, is excluded from discovery and output.
• After adding markers and enabling managed-section mode, use apm compile --dry-run --clean to inspect the eligible placement set. The preview excludes nested repositories and reports managed orphan files that --clean retains, just like a real compile.
• apm compile --clean never removes an orphan with either managed marker, because the file can contain team-owned content outside the managed block. Remove it manually when that content is no longer needed.

For example, compile scoped rules while retaining the rest of each generated file:

apm compile --target codex --dry-run --clean
apm compile --target codex --clean

If an existing distributed AGENTS.md has no markers, add the marker block around the content APM should own before the first managed-section compile.

Global compilation (-g)

Install a package once globally and root-context tools on your machine can pick up its instructions without per-project setup. For user-scope instructions, use the --global or -g flag:

apm compile --global
apm compile -g --dry-run

This reads global instructions from ~/.apm/apm_modules/ (instructions without applyTo: frontmatter) and writes user-scope root context files for root-context targets:

• ~/.claude/CLAUDE.md (or $CLAUDE_CONFIG_DIR/CLAUDE.md)
• ~/.codex/AGENTS.md
• ~/.config/opencode/AGENTS.md
• ~/.copilot/AGENTS.md
• ~/.cursor/AGENTS.md
• ~/.gemini/GEMINI.md

OpenCode is the exception: its generated ~/.config/opencode/AGENTS.md retains explicit sections for applyTo instructions as well.

Overwrite protection

When a target root context file exists but contains no APM marker, it is treated as hand-authored and never overwritten. This applies to every catalog target, including AGENTS.md, CLAUDE.md, and GEMINI.md. Use --dry-run to preview what would be written without modifying files.

Constraints

• Compilation is explicit. apm install -g (see Install packages) does not write root context files; it prints a one-line hint pointing at apm compile -g when global instructions land on a root-context-only target.
• --global cannot be combined with project-output flags such as --target, --all, --watch, --root, or --output.
• Compiled output is security-scanned before it is written. Critical findings stop the write and make apm compile -g exit non-zero.
• Skills-only packages (no global instructions) do not write root files.

Pitfalls

• Confusing compile’s scope. Compile only handles instructions (and optionally a single agent to prepend via --chatmode). If you edit a prompt, skill, agent, hook, or command, apm compile will not redeploy it – run apm install for that.
• Forgetting --target on a clean workspace. With no harness folder present and no targets: in apm.yml, the cascade falls back to minimal and writes only AGENTS.md. The CLI prints a hint, but the easy fix is to either create the harness folder or pin targets: in your manifest.
• Stale AGENTS.md after deleting an instruction. Compile leaves previous output in place by default. Pass --clean to remove orphaned files generated by earlier runs. When compiling for the claude target, --clean also removes a stale APM-generated CLAUDE.md when deduplication suppresses CLAUDE.md entirely: all instructions already live in .claude/rules/, and no constitution or dependency content keeps CLAUDE.md active. Hand-authored root context files (those without the <!-- Generated by APM CLI --> marker) are never deleted.
• Hand-edited primitives skip the security scan. apm compile does not run the install-time hidden-Unicode scan. After hand-edits, run apm audit before publishing. See drift and secure-by-default.
• Zero-output success. If compile reports success but writes no files, your project either has no instructions, or every requested target was rejected. The CLI surfaces this as a warning – check targets: and the contents of .apm/instructions/.

Once your instructions compile cleanly into the harnesses you care about, package the result with apm pack and share it via a marketplace.