Getting Started with APM

Welcome to APM - the AI Package Manager that transforms any project into reliable AI-Native Development. This guide will walk you through setup, installation, and creating your first AI-native project.

Prerequisites

Token Configuration (All Optional)

APM works without any tokens for public modules. Tokens unlock additional capabilities:

For Private Module Access

Variable	Purpose	When Needed
`GITHUB_APM_PAT`	Private GitHub/GHE repos	Private GitHub packages
`ADO_APM_PAT`	Private Azure DevOps repos	Private ADO packages

GITHUB_APM_PAT

export GITHUB_APM_PAT=ghp_finegrained_token_here

Purpose: Access to private APM modules on GitHub/GitHub Enterprise
Type: Fine-grained Personal Access Token (org or user-scoped)
Permissions: Repository read access to repositories you want to install from

ADO_APM_PAT

export ADO_APM_PAT=your_ado_pat

Purpose: Access to private APM modules on Azure DevOps
Type: Azure DevOps Personal Access Token
Permissions: Code (Read) scope

For Running Prompts (`apm run`)

Variable	Purpose	When Needed
`GITHUB_COPILOT_PAT`	Copilot runtime	`apm run` with Copilot

GITHUB_COPILOT_PAT

export GITHUB_COPILOT_PAT=ghp_copilot_token

Purpose: Authentication for apm run with Copilot runtime
Type: Personal Access Token with Copilot access
Fallback: Falls back to GITHUB_TOKEN if not set

Host Configuration

Variable	Purpose	Default
`GITHUB_HOST`	Default host for bare package names	`github.com`

GITHUB_HOST

export GITHUB_HOST=github.company.com

Purpose: Set default host for bare package names (e.g., owner/repo)
Default: github.com
Note: Azure DevOps has no equivalent - always use FQDN syntax (e.g., dev.azure.com/org/project/repo)

Common Setup Scenarios

Scenario 1: Public Modules Only (Most Users)

# No tokens needed - just works!
apm install microsoft/apm-sample-package
apm compile

Scenario 2: Private GitHub Modules

export GITHUB_APM_PAT=ghp_org_token    # For GitHub/GHE

Scenario 3: Private Azure DevOps Modules

export ADO_APM_PAT=your_ado_pat
# Note: Always use FQDN syntax for ADO
apm install dev.azure.com/org/project/repo

Scenario 4: GitHub Enterprise as Default

export GITHUB_HOST=github.company.com
export GITHUB_APM_PAT=ghp_enterprise_token
# Now bare packages resolve to your enterprise
apm install team/package  # → github.company.com/team/package

Scenario 5: Running Prompts

export GITHUB_COPILOT_PAT=ghp_copilot_token  # For apm run

Package Sources

APM installs packages from multiple sources. Use the format that matches your repository host:

Source	Format	Example
GitHub.com	`owner/repo`	`apm install microsoft/apm-sample-package`
GitHub Enterprise	`ghe.company.com/owner/repo`	`apm install ghe.myco.com/team/standards`
Azure DevOps	`dev.azure.com/org/project/repo`	`apm install dev.azure.com/myorg/proj/rules`
Virtual Package	`owner/repo/path/to/skill`	`apm install github/awesome-copilot/skills/review-and-refactor`

GitHub Enterprise Support

APM supports all GitHub Enterprise deployment models via GITHUB_HOST (see Host Configuration).

Examples

# GitHub Enterprise Server
export GITHUB_HOST=github.company.com
apm install team/package  # → github.company.com/team/package

# GitHub Enterprise Cloud with Data Residency
export GITHUB_HOST=myorg.ghe.com
apm install platform/standards  # → myorg.ghe.com/platform/standards

# Multiple instances: Use FQDN for explicit hosts
apm install partner.ghe.com/external/integration  # FQDN always works
apm install github.com/public/open-source-package

Key Insight: Use GITHUB_HOST to set your default for bare package names. Use FQDN syntax to specify supported hosts explicitly (e.g., github.com, *.ghe.com, Azure DevOps). Custom hosts require setting GITHUB_HOST.

Azure DevOps Support

APM supports Azure DevOps Services (cloud) and Azure DevOps Server (self-hosted). Note: There is no ADO_HOST equivalent - Azure DevOps always requires FQDN syntax.

URL Format

Azure DevOps uses 3 segments vs GitHub's 2:

GitHub: owner/repo
Azure DevOps: org/project/repo

# Both formats work (the _git segment is optional):
apm install dev.azure.com/myorg/myproject/myrepo
apm install dev.azure.com/myorg/myproject/_git/myrepo

# With git reference
apm install dev.azure.com/myorg/myproject/myrepo#main

# Legacy visualstudio.com URLs
apm install mycompany.visualstudio.com/myorg/myproject/myrepo

# Self-hosted Azure DevOps Server
apm install ado.company.internal/myorg/myproject/myrepo

# Virtual packages (individual files)
apm install dev.azure.com/myorg/myproject/myrepo/prompts/code-review.prompt.md

For authentication, see Token Configuration.

Token Creation Guide

Create Fine-grained PAT for GITHUB_APM_PAT (Private GitHub modules):
- Go to github.com/settings/personal-access-tokens/new
- Select "Fine-grained Personal Access Token"
- Scope: Organization or Personal account (as needed)
- Permissions: Repository read access
Create Azure DevOps PAT for ADO_APM_PAT (Private ADO modules):
- Go to https://dev.azure.com/{org}/_usersSettings/tokens
- Create PAT with Code (Read) scope
Create Copilot PAT for GITHUB_COPILOT_PAT (Running prompts):
- Go to github.com/settings/tokens
- Create token with Copilot access

Installation

Quick Install (Recommended)

The fastest way to get APM running:

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

This script automatically:

Detects your platform (macOS/Linux, Intel/ARM)
Downloads the latest binary
Installs to /usr/local/bin/
Verifies installation

Python Package

If you prefer managing APM through Python:

pip install apm-cli

Note: This requires Python 3.8+ and may have additional dependencies.

Manual Installation

Download the binary for your platform from GitHub Releases:

macOS Apple Silicon

curl -L https://github.com/microsoft/apm/releases/latest/download/apm-darwin-arm64.tar.gz | tar -xz
sudo mkdir -p /usr/local/lib/apm
sudo cp -r apm-darwin-arm64/* /usr/local/lib/apm/
sudo ln -sf /usr/local/lib/apm/apm /usr/local/bin/apm

macOS Intel

curl -L https://github.com/microsoft/apm/releases/latest/download/apm-darwin-x86_64.tar.gz | tar -xz
sudo mkdir -p /usr/local/lib/apm
sudo cp -r apm-darwin-x86_64/* /usr/local/lib/apm/
sudo ln -sf /usr/local/lib/apm/apm /usr/local/bin/apm

Linux x86_64

curl -L https://github.com/microsoft/apm/releases/latest/download/apm-linux-x86_64.tar.gz | tar -xz
sudo mkdir -p /usr/local/lib/apm
sudo cp -r apm-linux-x86_64/* /usr/local/lib/apm/
sudo ln -sf /usr/local/lib/apm/apm /usr/local/bin/apm

From Source (Developers)

For development or customization:

git clone https://github.com/microsoft/apm.git
cd apm

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install in development mode
uv venv
uv pip install -e ".[dev]"

# Activate the environment for development
source .venv/bin/activate  # On macOS/Linux
# .venv\Scripts\activate   # On Windows

Build Binary from Source

To build a platform-specific binary using PyInstaller:

# Clone and setup (if not already done)
git clone https://github.com/microsoft/apm.git
cd apm

# Install uv and dependencies
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv
uv pip install -e ".[dev]"
uv pip install pyinstaller

# Activate environment
source .venv/bin/activate

# Build binary for your platform
chmod +x scripts/build-binary.sh
./scripts/build-binary.sh

This creates a platform-specific binary at ./dist/apm-{platform}-{arch}/apm that can be distributed without Python dependencies.

Build features:

Cross-platform: Automatically detects macOS/Linux and Intel/ARM architectures
UPX compression: Automatically compresses binary if UPX is available (brew install upx)
Self-contained: Binary includes all Python dependencies
Fast startup: Uses --onedir mode for optimal CLI performance
Verification: Automatically tests the built binary and generates checksums

Setup AI Runtime

APM works with multiple AI coding agents. Choose your preferred runtime:

GitHub Copilot CLI (Recommended)

apm runtime setup copilot

Uses GitHub Copilot CLI with native MCP integration and advanced AI coding assistance.

OpenAI Codex CLI

apm runtime setup codex

Uses GitHub Models API for GPT-4 access through Codex CLI.

LLM Library

apm runtime setup llm

Installs the LLM library for local and cloud model access.

Verify Installation

Check what runtimes are available:

apm runtime list

First Project Walkthrough

Let's create your first AI-native project step by step:

1. Initialize Project

apm init my-first-project
cd my-first-project

This creates a complete Context structure:

my-first-project/
├── apm.yml              # Project configuration
├── SKILL.md             # Package meta-guide for AI discovery
└── .apm/
    ├── agents/          # AI assistant personalities
    ├── instructions/    # Context and coding standards
    ├── prompts/         # Reusable agent workflows
    └── context/         # Project knowledge base

About SKILL.md: This file serves as a meta-guide that helps AI agents discover and understand the package's capabilities. When your package is installed as a dependency, the SKILL.md content helps the AI understand what skills/workflows are available and how to use them.

Note: Legacy .apm/chatmodes/ directory with .chatmode.md files is still supported.

2. Explore Generated Files

Let's look at what was created:

# See project structure
ls -la .apm/

# Check the main configuration
cat apm.yml

# Look at available workflows
ls .apm/prompts/

3. Compile Context

Transform your context into agent-specific formats:

apm compile

Auto-Detection: APM automatically detects which integrations to generate based on folder presence:

If .github/ exists → VSCode/Copilot integration (generates AGENTS.md)
If .claude/ exists → Claude Code integration (generates CLAUDE.md)
Both can coexist - APM generates outputs for all detected integrations

Generated Files:

AGENTS.md - Contains instructions grouped by applyTo patterns (VSCode-compatible)
CLAUDE.md - Contains instructions with @import syntax (Claude-compatible)

Note: These files contain only instructions - prompts and agents are installed separately during apm install.

4. Install Dependencies

Install APM and MCP dependencies from your apm.yml configuration:

apm install

What gets installed:

For VSCode/Copilot (when .github/ exists):

.github/prompts/*-apm.prompt.md - Reusable prompt templates
.github/agents/*-apm.agent.md - Agent definitions
.github/skills/{folder-name}/ - Skills with SKILL.md meta-guide

For Claude Code (when .claude/ exists):

.claude/commands/*-apm.md - Slash commands

Tip: Both integrations can coexist in the same project. APM installs to all detected targets.

Adding APM Dependencies (Optional)

For reusable context from other projects, add APM dependencies:

# Add to apm.yml
dependencies:
  apm:
    - microsoft/apm-sample-package  # Design standards, prompts
    - github/awesome-copilot/skills/review-and-refactor  # Code review skill
  mcp:
    - io.github.github/github-mcp-server

# Install APM dependencies
apm install --only=apm

# View installed dependencies
apm deps list

# See dependency tree
apm deps tree

Virtual Packages

APM supports virtual packages - installing individual files directly from any repository without requiring a full APM package structure. This is perfect for reusing individual workflow files or configuration from existing projects.

💡 Explore ready-to-use prompts and agents!
Browse github/awesome-copilot for a curated collection of community-contributed skills, instructions, and agents across all major languages and frameworks. Install any subdirectory directly with APM. Also works with Awesome Copilot's plugins.

What are Virtual Packages?

Instead of installing an entire package (owner/repo), you can install specific files:

# Install individual files directly
apm install github/awesome-copilot/skills/architecture-blueprint-generator
apm install myorg/standards/instructions/code-review.instructions.md
apm install company/templates/chatmodes/qa-assistant.chatmode.md

How it Works:

Path Detection: APM detects paths with 3+ segments as virtual packages
File Download: Downloads the file from GitHub's raw content API
Structure Generation: Creates a minimal APM package automatically:
- Generates apm.yml with metadata extracted from file frontmatter
- Places file in correct .apm/ subdirectory based on extension
- Creates sanitized package name from path

Supported File Types:

.prompt.md - Agent workflows
.instructions.md - Context and rules
.agent.md - Agent definitions

Installation Structure:

Files install to apm_modules/{owner}/{sanitized-package-name}/:

apm install github/awesome-copilot/skills/review-and-refactor

Creates:

apm_modules/
└── github/
    └── awesome-copilot/
        └── skills/
            └── review-and-refactor/
                ├── apm.yml
                └── SKILL.md

Adding to apm.yml:

Virtual packages work in apm.yml just like regular packages:

dependencies:
  apm:
    # Regular packages
    - microsoft/apm-sample-package
    
    # Virtual packages - individual files
    - github/awesome-copilot/skills/architecture-blueprint-generator
    - myorg/engineering/instructions/testing-standards.instructions.md

Branch/Tag Support:

Use @ref syntax for specific versions:

# Install from specific branch
apm install github/awesome-copilot/skills/review-and-refactor@develop

# Install from tag
apm install myorg/templates/chatmodes/assistant.chatmode.md@v2.1.0

Use Cases:

Quick Prototyping: Test individual workflows without package overhead
Selective Adoption: Pull single files from large repositories
Cross-Team Sharing: Share individual standards without full package structure
Legacy Migration: Gradually adopt APM by importing existing files

Example Workflow:

# 1. Find useful prompt in another repo
# Browse: github.com/awesome-org/best-practices

# 2. Install specific file
apm install awesome-org/best-practices/prompts/security-scan.prompt.md

# 3. Use immediately - no apm.yml configuration needed!
apm run security-scan --param target="./src"

# 4. Or add explicit script to apm.yml for custom flags
# scripts:
#   security: "copilot --full-auto -p security-scan.prompt.md"

Benefits:

✅ Zero overhead - No package creation required
✅ Instant reuse - Install any file from any repository
✅ Auto-discovery - Run installed prompts without script configuration
✅ Automatic structure - APM creates package layout for you
✅ Full compatibility - Works with apm compile and all commands
✅ Version control - Support for branches and tags

Runnable Prompts (Auto-Discovery)

Starting with v0.5.0, installed prompts are immediately runnable without manual configuration:

# Install a prompt
apm install github/awesome-copilot/skills/architecture-blueprint-generator

# Run immediately - APM auto-discovers it!
apm run architecture-blueprint-generator --param project_name="my-app"

# Auto-discovery works for:
# - Installed virtual packages
# - Local prompts (./my-prompt.prompt.md)
# - Prompts in .apm/prompts/ or .github/prompts/
# - All prompts from installed regular packages

How auto-discovery works:

No script found in apm.yml? APM searches for matching prompt files
Runtime detection: Automatically uses GitHub Copilot CLI (preferred) or Codex
Smart defaults: Applies recommended flags for chosen runtime
Collision handling: If multiple prompts found, use qualified path: owner/repo/prompt-name

Priority:

Explicit scripts in apm.yml always win (power user control)
Auto-discovery provides zero-config convenience for simple cases

Disambiguation with qualified paths:

# If you have prompts from multiple sources
apm run github/awesome-copilot/code-review
apm run acme/standards/code-review

See Prompts Guide for complete auto-discovery documentation.

5. Run Your First Workflow

Execute the default "start" workflow:

apm run start --param name="<YourGitHubHandle>"

This runs the AI workflow with your chosen runtime, demonstrating how APM enables reliable, reusable AI interactions.

6. Explore Available Scripts

See what workflows are available:

apm list

7. Preview Workflows

Before running, you can preview what will be executed:

apm preview start --param name="<YourGitHubHandle>"

Common Troubleshooting

Token Issues

Problem: "Authentication failed" or "Token invalid" Solution:

Verify token has correct permissions
Check token expiration
Ensure environment variables are set correctly

# Test token access
curl -H "Authorization: token $GITHUB_CLI_PAT" https://api.github.com/user

Runtime Installation Fails

Problem: apm runtime setup fails Solution:

Check internet connection
Verify system requirements
Try installing specific runtime manually

Command Not Found

Problem: apm: command not found Solution:

Check if /usr/local/bin is in your PATH
Try which apm to locate the binary
Reinstall using the quick install script

Permission Denied

Problem: Permission errors during installation Solution:

Use sudo for system-wide installation
Or install to user directory: ~/bin/

Next Steps

Now that you have APM set up:

Learn the concepts: Read Core Concepts to understand the AI-Native Development framework
Study examples: Check Examples & Use Cases for real-world patterns
Build workflows: See Context Guide to create advanced workflows
Explore dependencies: See Dependency Management for sharing context across projects
Explore integrations: Review Integrations Guide for tool compatibility

Quick Reference

Essential Commands

apm init <project>     # 🏗️ Initialize AI-native project
apm compile           # ⚙️ Generate AGENTS.md compatibility layer
apm run <workflow>    # 🚀 Execute agent workflows
apm runtime setup     # ⚡ Install coding agents
apm list              # 📋 Show available workflows
apm install           # 📦 Install APM & MCP dependencies
apm deps list         # 🔗 Show installed APM dependencies

File Structure

apm.yml - Project configuration and scripts
.apm/ - Context directory (source primitives)
SKILL.md - Package meta-guide for AI discovery
AGENTS.md - Generated VSCode/Copilot instructions
CLAUDE.md - Generated Claude Code instructions
.github/prompts/, .github/agents/, .github/skills/ - Installed VSCode primitives and skills
.claude/commands/ - Installed Claude commands
apm_modules/ - Installed APM dependencies
*.prompt.md - Executable agent workflows

Ready to build reliable AI workflows? Let's explore the core concepts next!

FilesExpand file tree

getting-started.md

Latest commit

History