Skip to content

Choose your harnesses

Use this page to decide which agent tools get your team’s skills and instructions, and to find where a file landed. APM calls each agent tool a harness: GitHub Copilot, Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Windsurf and Kiro are examples. Each one reads its own folder, so APM writes one package in each harness’s format.

List the harnesses in apm.yml. Each value is a target:

apm.yml
targets:
- copilot
- claude
- cursor
- codex

apm init --target copilot,claude,cursor,codex writes the same list. Commit it: every teammate and CI run then writes the same files, and the lockfile records the same MCP ownership on every machine.

To write for one harness in a single run, pass --target (comma-separated):

Terminal window
apm install --target claude

APM picks targets in this order: --target, then targets: in apm.yml, then a saved default (apm config set target claude), then detection.

With no targets:, APM looks for folders a harness already created (.claude/, .cursor/, .codex/, .github/instructions/ and so on). A new repository has none, so apm install stops before writing anything:

Error: No harness detected

Detection can also guess wrong: a CLAUDE.md you wrote as documentation turns on Claude Code. Declare targets: to remove the guess. apm targets shows what detection finds on disk (it does not read targets:):

Terminal window
apm targets
TARGET STATUS SOURCE DEPLOY DIR
------------ ---------- ---------------------------------------- ----------
claude active .claude/ .claude/
copilot active .github/instructions/ .github/
cursor active .cursor/ .cursor/
codex active .codex/ .codex/
gemini inactive needs GEMINI.md .gemini/
...

Installing microsoft/apm-sample-package#v1.0.0 with the four targets above writes files like these; the MCP and hooks lines show where those land when a package has them. Skills go to the shared .agents/skills/ folder that Copilot, Cursor and Codex read; Claude Code keeps its own.

.github/agents/design-reviewer.agent.md
.github/instructions/design-standards.instructions.md
.github/prompts/design-review.prompt.md
.agents/skills/style-checker/SKILL.md
.mcp.json (MCP servers)
.github/hooks/<package>-hooks.json (hooks)

Some primitives have no equivalent in a harness and are skipped with a [!] line; for example, Claude Code commands drop prompt frontmatter keys they do not support. The full primitive-by-harness table, including Gemini, OpenCode, Windsurf and Kiro, is the Targets matrix. To trace one file back to its package, run apm find PATH.

-g installs into your home folder so the packages follow you into every project:

Terminal window
apm install -g microsoft/apm-sample-package#v1.0.0 --target copilot,claude

APM keeps the user manifest and lockfile in ~/.apm/ (or $APM_HOME) and writes files where each harness reads user settings: ~/.copilot/, ~/.claude/, ~/.cursor/, ~/.codex/. Skills go to ~/.claude/skills/ for Claude Code and to ~/.agents/skills/ for GitHub Copilot, Codex and Cursor. Point a harness at another profile with COPILOT_HOME, CLAUDE_CONFIG_DIR or CODEX_HOME; the value must be an absolute path. A selection with no harness that supports user scope exits 2 before changing anything. Details: Environment variables.

Codex, Gemini CLI and OpenCode read instructions from one root file (AGENTS.md, or GEMINI.md for Gemini), not per-file rules. After an install that brings instructions for them, APM prints:

[i] Instructions installed for codex. Run 'apm compile' to update AGENTS.md.
Terminal window
apm compile

apm compile merges your instructions into those root files. It writes CLAUDE.md when .claude/rules/ does not already carry the instructions. Commit the generated file and rerun apm compile when instructions change. apm uninstall and apm prune print a matching hint when a removed package’s instructions are still in the root file. Flags: apm compile.

Run apm install and read its opening line; it names the targets and where they came from:

[i] Targets: claude, codex, copilot, cursor (source: apm.yml)

Then check one path from the tabs above.

Copyright (c) Microsoft Corporation. General documentation: CC-BY-4.0. Software, code examples and OpenAPM: Apache-2.0. See scope and exclusions.