IDE & Tool Integration
APM is designed to work seamlessly with your existing development tools and workflows. This guide covers integration patterns, supported AI runtimes, and compatibility with popular development tools.
APM + Spec-kit Integration
Section titled “APM + Spec-kit Integration”APM manages the context foundation and provides advanced context management for software projects. It works exceptionally well alongside Spec-kit for specification-driven development, as well as with other AI Native Development methodologies like vibe coding.
APM: Context Foundation
Section titled “APM: Context Foundation”APM provides the infrastructure layer for AI development:
- Context Packaging: Bundle project knowledge, standards, and patterns into reusable modules
- Dynamic Loading: Smart context composition based on file patterns and current tasks
- Performance Optimization: Optimized context delivery for large, complex projects
- Memory Management: Strategic LLM token usage across conversations
Spec-kit: Specification Layer
Section titled “Spec-kit: Specification Layer”When using Spec-kit for Specification-Driven Development (SDD), APM automatically integrates the Spec-kit constitution:
- Constitution Injection: When using
apm compile, APM injects the Spec-kitconstitution.mdinto the compiled instruction files (AGENTS.md) - Rule Enforcement: All coding agents respect the non-negotiable rules governing your project
- Contextual Augmentation: Compiled output embeds your team’s context modules after Spec-kit’s constitution
- SDD Enhancement: Augments the Spec Driven Development process with additional context curated by your teams
Integrated Workflow
Section titled “Integrated Workflow”# 1. Set up APM contextual foundationapm init my-project && apm install
# 2. Optional: compile for Codex/OpenCode instructions, Gemini, etc.# Spec-kit constitution is automatically included in compiled AGENTS.mdapm compile
# 3. AI workflows use both SDD rules and team contextKey Benefits of Integration:
- Universal Context: APM grounds any coding agent on context regardless of workflow
- SDD Compatibility: Perfect for specification-driven development approaches
- Flexible Workflows: Also works with traditional prompting and vibe coding
- Team Knowledge: Combines constitutional rules with team-specific context
Running Agentic Workflows
Section titled “Running Agentic Workflows”For running agentic workflows locally, see the Agent Workflows guide.
User-scope deployment:
apm install -gdeploys primitives to user-level directories (~/.copilot/,~/.claude/, etc.), making packages available across all projects. See Global Installation for per-target coverage.
VS Code Integration
Section titled “VS Code Integration”APM works natively with VS Code’s GitHub Copilot implementation.
Auto-Detection: VS Code integration is automatically enabled when a
.github/folder exists in your project. If neither.github/nor.claude/exists,apm installskips folder integration (packages are still installed toapm_modules/).
Native VS Code Primitives
Section titled “Native VS Code Primitives”VS Code implements core primitives for GitHub Copilot that APM integrates with:
- Agents: AI personas and workflows with
.agent.mdfiles in.github/agents/(legacy:.chatmode.mdin.github/chatmodes/) - Instructions Files: Modular instructions with
copilot-instructions.mdand.instructions.mdfiles - Prompt Files: Reusable task templates with
.prompt.mdfiles in.github/prompts/ - Skills: Structured capabilities with
SKILL.mdin.github/skills/
Note: APM supports both the new
.agent.mdformat and legacy.chatmode.mdformat. VS Code provides Quick Fix actions to migrate from.chatmode.mdto.agent.md.
Automatic Prompt and Agent Integration
Section titled “Automatic Prompt and Agent Integration”APM automatically integrates prompts and agents from installed packages into VS Code’s native structure:
# Install APM packages - integration happens automatically when .github/ existsapm install microsoft/apm-sample-package
# Prompts are automatically integrated to:# .github/prompts/*.prompt.md (verbatim copy, original filename preserved)
# Agents are automatically integrated to:# .github/agents/*.agent.md (verbatim copy)
# Instructions are automatically integrated to:# .github/instructions/*.instructions.md (verbatim copy, original filename)
# Hooks are automatically integrated to:# .github/hooks/*.json (hook definitions with rewritten script paths)How Auto-Integration Works:
- Zero-Config: Always enabled, works automatically with no configuration needed
- Auto-Cleanup: Removes integrated files when you uninstall or prune packages (tracked via
deployed_filesinapm.lock.yaml) - Collision Detection: If a local file has the same name as a package file, APM skips it with a warning (use
--forceto overwrite) - Always Overwrite: Package-owned files are always copied fresh — no version comparison
- Link Resolution: Context links are resolved during integration
Integration Flow:
- Run
apm installto fetch APM packages - APM automatically creates
.github/prompts/,.github/agents/,.github/instructions/, and.github/hooks/directories as needed - Discovers
.prompt.md,.agent.md,.instructions.md, and hook.jsonfiles in each package - Copies prompts to
.github/prompts/with their original filename (e.g.,accessibility-audit.prompt.md) - Copies agents to
.github/agents/with their original filename (e.g.,security.agent.md) - Copies instructions to
.github/instructions/with their original filename (e.g.,python.instructions.md) - Copies hooks to
.github/hooks/with their original filename and copies referenced scripts - If a local file already exists with the same name, skips with a warning (use
--forceto overwrite) - Records all deployed files in
apm.lock.yamlunderdeployed_filesper package - VS Code automatically loads all prompts, agents, instructions, and hooks for your coding agents
- Run
apm uninstallto automatically remove integrated primitives (usingdeployed_filesmanifest)
Intent-First Discovery: Files keep their original names for natural autocomplete in VS Code:
- Type
/design— VS Code showsdesign-review.prompt.md - Type
/accessibility— VS Code showsaccessibility-audit.prompt.md - Search by what you want to do, not where it comes from
Example:
# Install package with auto-integrationapm install microsoft/apm-sample-package
# Result in VS Code:# Prompts:# .github/prompts/accessibility-audit.prompt.md - Available in chat# .github/prompts/design-review.prompt.md - Available in chat# .github/prompts/style-guide-check.prompt.md - Available in chat
# Agents:# .github/agents/design-reviewer.agent.md - Available as chat mode# .github/agents/accessibility-expert.agent.md - Available as chat mode
# Instructions:# .github/instructions/python.instructions.md - Applied to matching files
# Use with natural autocomplete:# Type: /design# VS Code suggests: design-review.prompt.mdVS Code Native Features:
- All integrated prompts appear in VS Code’s prompt picker
- All integrated agents appear in VS Code’s chat mode selector
- Native chat integration with primitives
- Seamless
/promptcommand support - File-pattern based instruction application
- Agent support for different personas and workflows
Optional: Compiled Context with AGENTS.md
Section titled “Optional: Compiled Context with AGENTS.md”For tools that do not support granular primitive discovery (such as Gemini), apm compile produces an AGENTS.md file that merges instructions into a single document. This is not needed for GitHub Copilot, Claude, or Cursor, which read per-file instructions natively. OpenCode and Codex also read AGENTS.md, so run apm compile to deploy instructions there.
# Compile all local and dependency instructions into AGENTS.mdapm compile --target copilot
# Default distributed compilation creates focused AGENTS.md files per directory# Use --single-agents for a single monolithic file (legacy mode)apm compile --single-agentsAGENTS.md aggregates instructions, context, and optionally the Spec-kit constitution into a single document that GitHub Copilot reads as project-level guidance.
Claude Integration
Section titled “Claude Integration”APM provides first-class support for Claude Code and Claude Desktop through native format generation.
Auto-Detection: Claude integration is automatically enabled when a
.claude/folder exists in your project. If neither.github/nor.claude/exists,apm installskips folder integration (packages are still installed toapm_modules/).
Optional: Compiled Output for Claude
Section titled “Optional: Compiled Output for Claude”Running apm compile is optional for Claude Code, which reads deployed primitives natively via apm install. If you want a single CLAUDE.md instruction file (for example, for Claude Desktop), you can generate one:
| File | Purpose |
|---|---|
CLAUDE.md | Merged project instructions for Claude (instructions only, using @import syntax) |
When you run apm install, APM integrates package primitives into Claude’s native structure:
| Location | Purpose |
|---|---|
.claude/agents/*.md | Sub-agents from installed packages (from .agent.md files) |
.claude/commands/*.md | Slash commands from installed packages (from .prompt.md files) |
.claude/skills/{folder}/ | Skills from packages with SKILL.md or .apm/ primitives |
.claude/settings.json (hooks key) | Hooks from installed packages (merged into settings) |
OpenCode (.opencode/)
Section titled “OpenCode (.opencode/)”APM natively integrates with OpenCode when a .opencode/ directory exists in your project. Run apm install and APM automatically deploys primitives to OpenCode’s native format:
| APM Primitive | OpenCode Destination | Format |
|---|---|---|
Agents (.agent.md) | .opencode/agents/*.md | Markdown with YAML frontmatter |
Prompts (.prompt.md) | .opencode/commands/*.md | Converted to command format |
Skills (SKILL.md) | .opencode/skills/{name}/SKILL.md | Identical (agentskills.io standard) |
| MCP servers | opencode.json | mcp key with command array, environment |
| Instructions | Via AGENTS.md | Read natively by OpenCode |
Setup: Create a .opencode/ directory in your project root, then run apm install. APM detects the directory and deploys automatically. OpenCode reads AGENTS.md natively for instructions.
Note: OpenCode does not support hooks.
Cursor (.cursor/)
Section titled “Cursor (.cursor/)”| Location | Purpose |
|---|---|
.cursor/rules/*.mdc | Instructions converted to Cursor rules format |
.cursor/agents/*.md | Sub-agents from installed packages |
.cursor/skills/{name}/SKILL.md | Skills from installed packages |
.cursor/hooks.json (hooks key) | Hooks from installed packages (merged into config) |
.cursor/hooks/{pkg}/ | Referenced hook scripts |
.cursor/mcp.json | MCP server configurations |
Codex CLI (.codex/)
Section titled “Codex CLI (.codex/)”| APM Primitive | Codex Destination | Format |
|---|---|---|
Skills (SKILL.md) | .agents/skills/{name}/SKILL.md | Identical (agentskills.io standard) |
Agents (.agent.md) | .codex/agents/*.toml | Converted from Markdown to TOML |
Hooks (.json) | .codex/hooks.json + .codex/hooks/{pkg}/ | Merged JSON config with _apm_source markers |
| Instructions | Via AGENTS.md | Compile-only (apm compile --target codex) |
Setup: Create a .codex/ directory in your project root, then run apm install. APM detects the directory and deploys automatically.
Note: Skills deploy to
.agents/skills/(the cross-tool agent skills standard directory), not.codex/skills/. Agents are transformed from.agent.mdMarkdown to.tomlformat.
Automatic Agent Integration
Section titled “Automatic Agent Integration”APM automatically deploys agent files from installed packages into .claude/agents/:
# Install a package with agentsapm install danielmeppiel/design-guidelines
# Result:# .claude/agents/security.md -- Sub-agent available for Claude CodeHow it works:
apm installdetects.agent.mdand.chatmode.mdfiles in the package- Copies each to
.claude/agents/as.mdfiles apm uninstallautomatically removes the package’s agents
Automatic Command Integration
Section titled “Automatic Command Integration”APM automatically converts .prompt.md files from installed packages into Claude slash commands:
# Install a package with promptsapm install microsoft/apm-sample-package
# Result:# .claude/commands/accessibility-audit.md -- /accessibility-audit# .claude/commands/design-review.md -- /design-reviewHow it works:
apm installdetects.prompt.mdfiles in the package- Converts each to Claude command format in
.claude/commands/ apm uninstallautomatically removes the package’s commands
Automatic Skills Integration
Section titled “Automatic Skills Integration”APM automatically integrates skills from installed packages into .github/skills/:
# Install a package with skillsapm install ComposioHQ/awesome-claude-skills/mcp-builder
# Result:# .github/skills/mcp-builder/SKILL.md -- Skill available for agents# .github/skills/mcp-builder/... -- Full skill folder copiedSkill Folder Naming: Uses the source folder name directly (e.g., mcp-builder, design-guidelines), not flattened paths.
How skill integration works:
apm installchecks if the package contains aSKILL.mdfile- If
SKILL.mdexists: copies the entire skill folder to.github/skills/{folder-name}/(primary location) - If a
.claude/directory exists: also copies to.claude/skills/{folder-name}/for Claude compatibility - Sub-skills inside
.apm/skills/are promoted to top-level.github/skills/entries apm uninstallremoves the skill folder from both locations
Automatic Hook Integration
Section titled “Automatic Hook Integration”APM automatically integrates hooks from installed packages. Hooks define lifecycle event handlers (e.g., PreToolUse, PostToolUse, Stop) supported by VS Code Copilot, Claude Code, and Cursor.
Note: Hook packages must be authored in the target platform’s native format. APM handles path rewriting and file placement but does not translate between hook schema formats (e.g., Claude’s
commandkey vs GitHub Copilot’sbash/powershellkeys, or event name casing differences).
# Install a package with hooksapm install anthropics/claude-plugins-official/plugins/hookify
# VS Code result (.github/hooks/):# .github/hooks/hookify-hooks.json -- Hook definitions# .github/hooks/scripts/hookify/hooks/*.py -- Referenced scripts
# Claude result (.claude/settings.json):# Hooks merged into .claude/settings.json hooks key# Scripts copied to .claude/hooks/hookify/
# Cursor result (.cursor/hooks.json) — only when .cursor/ exists:# Hooks merged into .cursor/hooks.json hooks key# Scripts copied to .cursor/hooks/hookify/How hook integration works:
apm installdiscovers hook JSON files in.apm/hooks/orhooks/directories- For VS Code: copies hook JSON to
.github/hooks/and rewrites script paths - For Claude: merges hook definitions into
.claude/settings.jsonunder thehookskey - For Cursor: merges hook definitions into
.cursor/hooks.jsonunder thehookskey (only when.cursor/exists) - For Codex: merges hook definitions into
.codex/hooks.jsonunder thehookskey (only when.codex/exists) - Copies referenced scripts to the target location
- Rewrites
${CLAUDE_PLUGIN_ROOT}and relative script paths for the target platform apm uninstallremoves hook files and cleans up merged settings
Optional: Target-Specific Compilation
Section titled “Optional: Target-Specific Compilation”Compilation is optional for Copilot, Claude, and Cursor, which read per-file instructions natively. For OpenCode and Codex, run apm compile to generate AGENTS.md for instructions. Also use it when targeting Gemini:
# Generate all formats (default)apm compile
# Generate only Claude formatsapm compile --target claude# Creates: CLAUDE.md (instructions only)
# Generate only VS Code/Copilot formatsapm compile --target copilot# Creates: AGENTS.md (instructions only)Remember:
apm compilegenerates instruction files only. Useapm installto integrate prompts, agents, instructions, commands, and skills from packages.
Claude Command Format
Section titled “Claude Command Format”Generated commands follow Claude’s native structure:
<!-- APM Managed: microsoft/apm-sample-package@abc123 --># Design Review
Review the current design for accessibility and UI standards.
## Instructions[Content from original .prompt.md]Example Workflow
Section titled “Example Workflow”# 1. Install packages (integrates agents, commands, and skills automatically)apm install microsoft/apm-sample-packageapm install github/awesome-copilot/skills/review-and-refactor
# 2. Optional: compile instructions if not using Claude Code natively# apm compile --target claude
# 3. In Claude Code, use:# /code-review -- Runs the code review workflow# /gdpr-assessment -- Runs GDPR compliance check
# 4. CLAUDE.md provides project instructions automatically# 5. Agents in .claude/agents/ are available as sub-agents# 6. Skills in .claude/skills/ are available for agents to referenceClaude Desktop Integration
Section titled “Claude Desktop Integration”Skills installed to .github/skills/ are the primary location; when a .claude/ directory exists, APM also copies skills to .claude/skills/ for compatibility. Each skill folder contains a SKILL.md that defines the skill’s capabilities and any supporting files.
Claude Desktop can use CLAUDE.md as its project instructions file. Optionally run apm compile --target claude to generate CLAUDE.md with @import syntax for organized instruction loading.
Cleanup and Sync
Section titled “Cleanup and Sync”APM maintains synchronization between packages and Claude primitives:
- Install: Adds agents, commands, and skills for new packages, tracked via
deployed_filesinapm.lock.yaml - Uninstall: Removes only that package’s agents, commands, and skill directories (as tracked in
apm.lock.yaml). User-authored files are preserved. - Update: Refreshes agents, commands, and skills when package version changes
- Virtual Packages: Individual files and skills (e.g.,
github/awesome-copilot/skills/review-and-refactor) are tracked viaapm.lock.yamland removed correctly on uninstall
Other IDE Support
Section titled “Other IDE Support”IDEs with GitHub Copilot
Section titled “IDEs with GitHub Copilot”Any IDE with GitHub Copilot support works with APM’s file-level integration. APM deploys primitives to .github/, which Copilot discovers automatically:
apm install microsoft/apm-sample-package
# GitHub Copilot picks up:# .github/prompts/*.prompt.md# .github/agents/*.agent.md# .github/instructions/*.instructions.mdSupported IDEs: JetBrains (IntelliJ, PyCharm, WebStorm, etc.), Visual Studio, VS Code, and any IDE with GitHub Copilot integration.
Cursor
Section titled “Cursor”APM natively integrates with Cursor when a .cursor/ directory exists in your project. Run apm install and APM automatically deploys primitives to Cursor’s native format:
| APM Primitive | Cursor Destination | Format |
|---|---|---|
Instructions (.instructions.md) | .cursor/rules/*.mdc | Converted: applyTo: → globs: frontmatter |
Agents (.agent.md) | .cursor/agents/*.md | Markdown with YAML frontmatter |
Skills (SKILL.md) | .cursor/skills/{name}/SKILL.md | Identical (agentskills.io standard) |
Hooks (.json) | .cursor/hooks.json + .cursor/hooks/{pkg}/ | Merged JSON config |
| MCP servers | .cursor/mcp.json | Standard mcpServers JSON |
Setup: Create a .cursor/ directory in your project root (or use Cursor’s settings), then run apm install. APM detects the directory and deploys automatically.
Fallback: apm compile also generates AGENTS.md at the project root, which Cursor discovers as project-level context. This is useful for compiled/merged instruction output.
# Preview what will be compiledapm compile --dry-run
# Compile with source attribution for traceabilityapm compile --verbose
# Watch mode: auto-recompile when primitives changeapm compile --watchMCP (Model Context Protocol) Integration
Section titled “MCP (Model Context Protocol) Integration”APM provides first-class support for MCP servers, including registry-based servers that publish stdio packages (npm, pypi, docker) or HTTP/SSE remote endpoints.
Auto-Discovery from Packages
Section titled “Auto-Discovery from Packages”APM auto-discovers MCP server declarations from packages during apm install:
- apm.yml dependencies: MCP servers listed under
dependencies.mcpin a package’sapm.ymlare collected automatically. - plugin.json: Packages with a
plugin.json(at the root,.github/plugin/, or.claude-plugin/) are recognized as marketplace plugins. APM synthesizes anapm.ymlfromplugin.jsonmetadata when noapm.ymlexists. When both files are present (hybrid mode), APM usesapm.ymlfor dependency management while preservingplugin.jsonfor plugin ecosystem compatibility. See Plugin authoring. - Transitive collection: APM walks the dependency tree and collects MCP servers from all transitive packages.
Trust Model
Section titled “Trust Model”APM enforces a trust boundary for MCP servers to prevent packages from silently injecting arbitrary server processes:
| Dependency Type | Registry Servers | Self-Defined Servers |
|---|---|---|
| Direct (depth 1) | Auto-trusted | Auto-trusted |
| Transitive (depth > 1) | Auto-trusted | Skipped with warning |
Self-defined servers are those declared with registry: false in apm.yml — they run arbitrary commands rather than resolving through the official MCP registry.
To trust self-defined servers from transitive dependencies, either:
- Re-declare the server in your root
apm.yml(recommended), or - Use the
--trust-transitive-mcpflag:
# Trust self-defined MCP servers from transitive packagesapm install --trust-transitive-mcpClient Configuration
Section titled “Client Configuration”APM configures MCP servers in the native config format for each supported client:
| Client | Config Location | Format |
|---|---|---|
| VS Code | .vscode/mcp.json | JSON servers object |
| GitHub Copilot CLI | ~/.copilot/mcp-config.json | JSON mcpServers object |
| Codex CLI | ~/.codex/config.toml | TOML mcp_servers section |
Runtime targeting: APM detects which runtimes are installed and configures MCP servers for all of them. Use --runtime <name> or --exclude <name> to control which clients receive configuration.
VS Code detection: APM considers VS Code available when either the
codeCLI command is on PATH or a.vscode/directory exists in the current working directory. This means VS Code MCP configuration works even whencodeis not on PATH — common on macOS and Linux when “Install ‘code’ command in PATH” has not been run from the VS Code command palette, or when VS Code was installed via a method that doesn’t register the CLI (e.g..tar.gz, Flatpak, or a non-standard macOS install location).
# Install MCP dependencies for all detected runtimesapm install
# Target only VS Codeapm install --runtime vscode
# Skip Codex configurationapm install --exclude codex
# Install only MCP dependencies (skip APM packages)apm install --only mcp
# Preview MCP configuration without writingapm install --dry-runAPM also handles stale server cleanup: when a package is uninstalled or an MCP dependency is removed, APM removes the corresponding entries from all client configs.
Package Type Inference
Section titled “Package Type Inference”The MCP registry API may return empty registry_name fields for packages. APM infers the package type from:
- Explicit
registry_name(when provided) runtime_hint(e.g.npxto npm,uvxto pypi)- Package name patterns (e.g.
@scope/nameto npm,ghcr.io/...to docker,PascalCase.Nameto nuget)
Supported Package Types
Section titled “Supported Package Types”When installing registry MCP servers, APM selects the best available package for each runtime:
| Package Registry | VS Code | Copilot CLI | Codex CLI |
|---|---|---|---|
| npm | Yes (npx) | Yes (npx) | Yes (npx) |
| pypi | Yes (uvx/python3) | Yes (uvx) | Yes (uvx) |
| docker | Yes | Yes | Yes |
| homebrew | — | Yes | Yes |
| Other (with runtime_hint) | Yes (generic) | Yes (generic) | Yes (generic) |
| HTTP/SSE remotes | Yes | Yes | Yes |
MCP Server Declaration
Section titled “MCP Server Declaration”# apm.yml - MCP dependenciesdependencies: mcp: # Simple registry references (resolved via MCP registry) - ghcr.io/github/github-mcp-server - ghcr.io/modelcontextprotocol/filesystem-server
# Registry server with overlays - name: ghcr.io/modelcontextprotocol/postgres-server transport: stdio package: npm args: ["--connection-string", "postgresql://localhost/mydb"]
# Self-defined server (not in registry) - name: my-internal-server registry: false transport: stdio command: python args: ["-m", "my_server"] env: PORT: "3000"# Install MCP dependenciesapm install
# Search the MCP registryapm mcp search github
# Show server detailsapm mcp info ghcr.io/github/github-mcp-server
# List available MCP serversapm mcp list${input:...} Variables in headers and env
Section titled “${input:...} Variables in headers and env”Values in headers and env can reference VS Code input variables using ${input:<variable-id>}. At runtime, VS Code prompts the user for each referenced input before starting the server.
For registry-backed servers, APM auto-generates input prompts from registry metadata. For self-defined servers, APM detects the ${input:...} patterns in your apm.yml and generates matching input definitions.
dependencies: mcp: - name: my-server registry: false transport: http url: https://my-server.example.com/mcp/ headers: Authorization: "Bearer ${input:my-server-token}" X-Project: "${input:my-server-project}"Runtime support:
| Runtime | ${input:...} support |
|---|---|
| VS Code | ✅ Prompts user at runtime |
| Copilot CLI | ❌ Use environment variables instead |
| Codex | ❌ Use environment variables instead |
Roadmap
Section titled “Roadmap”The following IDE integrations are planned for future releases:
- JetBrains IDE support: Native integration with IntelliJ, PyCharm, WebStorm, and other JetBrains IDEs
- Windsurf support: Integration with the Windsurf AI coding environment
- Cursor deeper integration: Enhanced Cursor support including rule versioning and conflict resolution
Related Resources
Section titled “Related Resources”- Getting Started — Set up APM in your environment
- Key Concepts — Core APM concepts and terminology
- CLI Reference — Complete command documentation
- Review the VSCode Copilot Customization Guide for VSCode-specific features
- Check the Spec-kit documentation for SDD integration details
- Explore MCP servers for tool integration options