「npm for agent context」- Microsoft가 제작한 Agent Package Manager (APM)를 사용해 보았다

Claude Code나 GitHub Copilot, Cursor 등의 AI 코딩 에이전트를 사용하다 보면, 툴마다 CLAUDE.md, .github/copilot-instructions.md, .cursorrules와 같이 설정 파일 형식이 달라, 동일한 「지시(Instructions)」「스킬(Skills)」「MCP 서버 설정」을 툴마다 다시 만들어야 하는 고민이 있습니다.

이 과제에 대해 Microsoft가 공개한 것이 **APM (Agent Package Manager)**입니다. 「npm for agent context」라고 설명되어 있으며, 실제로 설치하여 사용해 보았습니다.

공식 사이트: https://microsoft.github.io/apm/

리포지토리: https://github.com/microsoft/apm

APM은 AI 에이전트를 위한 **컨텍스트(Context, 지시·스킬·프롬프트 등)를 관리하기 위한 의존성 관리자(Dependency Manager)**입니다.

npm / pip / cargo와 같은 「매니페스트(Manifest) + 락 파일(Lock file)」 방식을 채택하고 있어, 단 하나의 apm.yml을 작성하는 것만으로 Claude Code · GitHub Copilot · Cursor · Codex · Gemini · OpenCode · Windsurf 등 여러 하네스(Harness, AI 에이전트 실행 환경)를 위해 각각이 이해할 수 있는 네이티브 파일 형식으로 전개해 줍니다.

APM이 관리할 수 있는 컨텍스트는 다음과 같은 7가지 종류로 정리되어 있습니다.

Instructions - 프로젝트 전체의 가이드라인 -
Skills - 재사용 가능한 절차·지식 -
Prompts - 슬래시 커맨드(Slash command) -
Agents - 전문적인 페르소나(서브 에이전트) -
Hooks - 라이프사이클 핸들러(Lifecycle handler) -
Commands - 커스텀 CLI -
MCP servers - 외부 도구 통합

이식성(Portability): 하나의 매니페스트로 여러 하네스에 대응 -
보안(Security): 숨겨진 Unicode 문자의 스캔 및 콘텐츠 해시를 통한 고정 -
거버넌스(Governance): 조직의 정책을 설치 시 적용

APM 자체는 AI 에이전트의 런타임(Runtime)이 아니라, 「각 툴이 이해할 수 있는 파일을 배치할 뿐」이라는 설계로 되어 있다는 점도 포인트입니다.

공식 절차에 따라 설치 스크립트를 사용하여 바이너리를 설치합니다.

curl -sSL https://raw.githubusercontent.com/microsoft/apm/main/install.sh | sh

공식 사이트에서는 단축 URL (https://aka.ms/apm-unix)이 안내되어 있지만, 실체는 위의 GitHub 상에 있는 설치 스크립트입니다.

실행하면 OS·아키텍처를 자동 판별하여 GitHub Releases에서 최신 바이너리를 취득하고, /usr/local/bin에 배치해 줍니다.

+--------------------------------------------------------------+
| APM Installer |
| The NPM for AI-Native Development |
...

설치 후에는 다음과 같이 동작 확인을 할 수 있습니다.

$ apm --version
Agent Package Manager (APM) CLI version 0.20.0 (43a00c2)

또한, Homebrew (brew install microsoft/apm/apm) 또는 pip (pip install apm-cli)를 통한 설치도 지원합니다.

apm --help로 주요 커맨드를 확인하면 npm과 유사한 구성임을 알 수 있습니다.

Commands:
audit Scan installed packages for hidden Unicode characters
compile Compile APM context into distributed AGENTS.md files
...

apm init myagent -y

실행하면 최소 구성의 apm.yml이 생성됩니다.

name: myagent
version: 1.0.0
description: APM project for myagent
...

dependencies.apm에는 다른 프로젝트의 패키지를, dependencies.mcp에는 MCP 서버를 선언해 나가는 방식입니다.

공식 샘플 패키지를 설치해 보겠습니다.

cd myagent
apm install microsoft/apm-sample-package#v1.0.0

여기서 처음에 맞닥뜨린 문제는 타겟이 되는 하네스 (Harness)를 감지할 수 없다는 에러였습니다.

[x] No harness detected
APM scanned for harness markers (.claude/, CLAUDE.md, .cursor/, .cursorrules,
.github/copilot-instructions.md, ...) but found none in this project.
...

새 프로젝트에는 .claude/나 .github/copilot-instructions.md와 같은 마커가 존재하지 않기 때문에, 어떤 하네스용으로 파일을 전개할지 명시할 필요가 있는 것 같습니다. 이번에는 Claude Code를 대상으로 --target claude를 지정했습니다.

apm install --target claude

[>] Installing dependencies from apm.yml...
[i] Targets: claude (source: --target flag)
[+] microsoft/apm-sample-package #v1.0.0 @fb285168
...

지정한 패키지가 내부적으로 참조하고 있던 github/awesome-copilot의 스킬 (Skill)까지 의존 관계로서 한꺼번에 해결 및 설치되는 것을 확인할 수 있습니다.

생성된 파일은 다음과 같습니다.

.claude/agents/design-reviewer.md
.claude/commands/accessibility-audit.md
.claude/commands/design-review.md
...

.claude/commands/design-review.md의 내용을 보면, Claude Code의 슬래시 커맨드 (Slash command)로 바로 사용할 수 있는 Markdown이 전개되어 있었습니다.

---
description: Review code for design system compliance and visual consistency
---
...

설치 후 apm.yml에는 의존 패키지가 추가되고, apm.lock.yaml에는 해결된 커밋 해시 (Commit hash) 및 파일별 해시가 기록됩니다.

dependencies:
  apm:
    - microsoft/apm-sample-package#v1.0.0
...

lockfile_version: '1'
generated_at: '2026-06-13T15:48:29.410048+00:00'
apm_version: 0.20.0
...

이 apm.lock.yaml을 팀원과 공유하면, apm install을 실행하는 모든 사람이 **바이트 단위로 동일한 컨텍스트 (Context)**를 재현할 수 있다는 점이 APM의 핵심 셀링 포인트인 것 같습니다.

apm audit을 실행하면 설치된 패키지와 락 파일 (Lock file) 내용 사이에 차이(Drift)가 없는지 체크할 수 있습니다.

$ apm audit
[>] Scanning all installed packages...
[>] Replaying install (cache-only)...
...

CI에서 apm audit --ci를 실행하면, 누군가 전개된 파일을 수동으로 수정해 버리는 등의 사고를 감지할 수 있을 것 같습니다.

apm targets를 통해 현재 프로젝트가 어떤 하네스용으로 전개되어 있는지, 혹은 대응 가능한지 확인할 수 있습니다.

TARGET STATUS SOURCE DEPLOY DIR
------------ ---------- ---------------------------------------- ----------
claude active .claude/ .claude/
...

주요 에이전트 실행 환경이 거의 망라되어 있어, apm install --target <name>

을 전환하는 것만으로 동일한 의존 관계를 다른 하네스 (Harness)용으로 전개할 수 있습니다.

여기까지는 공식 샘플 패키지를 사용한 동작 확인이었지만, 실제로 자신의 패키지를 만들 경우 apm.yml

을 어떻게 설계하면 좋을지 정리해 보겠습니다.

APM이 인식하는 패키지 레이아웃 (Layout)은 크게 3가지가 있습니다.

• 단일 스킬 (Single Skill): 리포지토리 루트에 SKILL.md를 두는 것만으로 구성되는 심플한 구조. agents/나 scripts/를 공존시키는 것도 가능하며, 의존 관계 관리가 필요하다면 apm.yml을 추가한 HYBRID 패키지로 만들 수 있습니다.
• 복수 프리미티브 (Multiple Primitives): .apm/ 하위에 skills/, agents/, instructions/ 등의 서브 디렉토리를 나누어, 여러 프리미티브를 묶어서 관리하는 구성. apm install 시 각각이 개별적으로 전개됩니다.
• Claude 플러그인 (Claude Plugin): 이미 plugin.json을 가진 리포지토리라면, 구성 변경 없이 그대로 APM 패키지로 취급할 수 있습니다.

"하나의 완성된 기능을 배포하는 것"이 목적이라면 단일 스킬, "여러 관련 스킬·에이전트를 세트로 배포하고 싶은" 경우라면 .apm/ 구성, 이것이 기본적인 판단 기준이 될 것 같습니다.

apm init으로 생성되는 apm.yml에는 includes: auto라는 항목이 있습니다. 이는 ".apm/ 하위에 있는 것을 전부 배포 대상으로 한다"는 설정으로, 이것이 없으면 로컬의 프리미티브는 일절 배포되지 않습니다.

includes: auto

공개할 프리미티브를 한정하고 싶은 경우에는 auto 대신 명시적인 경로 리스트를 지정할 수도 있습니다. "사내용 실험적 스킬은 포함하지 않고, 완성된 것만 배포한다"와 같은 조정을 여기서 할 수 있을 것 같습니다.

dependencies.apm에는 다른 리포지토리 전체를 의존성으로 지정하는 방법과, 리포지토리 내의 특정 프리미티브만 지정하는 방법 두 가지가 있습니다.

dependencies:
  apm:
    - microsoft/apm-sample-package#v1.0.0 # 리포지토리 전체를 태그로 지정하여 의존
...

또한 devDependencies를 사용하면 배포물에는 포함하고 싶지 않은 개발·테스트용 의존성(사내 테스트 스킬 등)을 분리할 수 있습니다. apm pack으로 패키지화할 때 자동으로 제외된다는 점이 npm의 devDependencies와 같은 느낌으로 다룰 수 있을 것 같습니다.

apm install이 어떤 하네스용으로 전개될지는 다음 우선순위에 따라 결정됩니다.

• --target 플래그
• apm.yml의 targets: 필드
• 파일 시스템상의 자동 탐지 (.claude/, .cursor/, .github/copilot-instructions.md 등)

여러 명이 사용하는 패키지의 경우, 환경에 따라 탐지 결과가 달라지는 것을 피하기 위해 apm.yml에 targets:를 명시해 두는 것이 안전해 보입니다.

targets:
  - claude
  - copilot

참고로 스킬의 전개 위치는 하네스에 따라 차이가 있습니다. Claude Code는 .claude/skills/에 전개되지만, Copilot·Cursor·OpenCode·Codex·Gemini는 공통의 .agents/skills/를 읽어 가기 때문에, 한 번의 apm install로 여러 하네스에 동일한 스킬을 전달할 수 있습니다. 반면 에이전트 정의(agents/)는 하네스마다 전용 디렉토리(.github/agents/ 등)에 전개된다는 차이점이 있다는 점은 기억해 두는 것이 좋습니다.

별도의 기사에서 소개한 zensical-skills는 위의 "복수 프리미티브" 레이아웃의 실례입니다.

name: zensical-skills
version: 1.0.0
description: APM project for zensical-skills
...

• Zensical의 공식 문서를 페이지 단위로 SKILL.md화 하여 .apm/skills/ 하위에 48개 배치
• 문서 사이트 편집에 특화된 서브 에이전트 (Sub-agent)를 .apm/agents/에 1개 추가
• 외부 의존성 (External dependency)이 없으므로 dependencies는 비어 있으며, includes: auto로 .apm/ 하위 전체를 배포

사용 측 리포지토리(Repository)에서는 이를 의존성으로 한 줄 추가하기만 하면 됩니다.

dependencies:
  apm:
    - techolve/zensical-skills

"도구 고유의 공식 문서를 Skill화하여 배포한다"는 패턴은 includes: auto와 외부 의존성 없는 심플한 apm.yml만으로도 충분히 구현 가능하다는 것을 알 수 있었습니다. 반대로, 여러 팀의 규약이나 리뷰 기준을 하나의 패키지에 담고 싶다면, devDependencies로 사내 검증용 테스트 스킬을 분리하거나, targets로 하네스 (Harness)를 고정하는 등의 조정이 필요할 것으로 보입니다.

실제로 사용해 본 소감입니다.

• 셋업 (Setup)은 npm 경험자라면 직관적임 (init → apm.yml 편집 → install)
• 패키지는 GitHub 리포지토리를 그대로 참조할 수 있어, 사내 프라이빗 리포지토리에 "스킬 모음"을 두고 전사적으로 공유하는 방식으로 활용하기 쉬워 보임
• 의존 관계 안에 MCP 서버를 포함할 수 있어, 에이전트용 셋업을 통째로 "하나의 의존성 트리 (Dependency tree)"로 다룰 수 있음
• 신규 프로젝트에서는 --target 명시가 필요하거나 락 파일 (Lock file) 메커니즘이 있는 등, "인프라로서의 안정감"이 느껴지는 설계
• apm.yml 레이아웃은 "단일 스킬", "복수 프리미티브", "Claude 플러그인"의 3가지 선택지가 있어, 배포하고자 하는 대상의 입도 (Granularity)에 따라 선택하면 될 듯함

여러 AI 코딩 도구를 병행 사용하는 팀에서 에이전트용 지시사항, 스킬, MCP 설정을 일원 관리하고 싶을 때 검토해 볼 가치가 있는 도구라고 느꼈습니다.