Skip to content

Commit d92d3ff

Browse files
cabirdCopilotdanielmeppiel
authored
Add agent-guide: teach AI agents how to use APM (#516)
* Add agent-guide: teach AI agents how to use APM Add a new agent-guide/ directory at the repo root containing two files that teach AI agents (and humans) how to install, use, and create APM packages: - SKILL.md: lightweight activation triggers and key rules for when an AI agent should reach for APM - apm-expert.agent.md: deep reference covering installation on all platforms (Linux, macOS, Windows, WSL), the full command reference, package authoring with all primitive formats, org-wide patterns, plugin development, and troubleshooting Placed at the repo root for immediate visibility to anyone cloning the repo or browsing on github.com. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Restructure as PROSE-compliant APM package Reorganize agent-guide/ into packages/apm-guide/ -- a proper APM subdirectory package that users can install with: apm install microsoft/apm/packages/apm-guide Architecture: skill-centric with bundled resources - SKILL.md index with activation triggers and key rules - 8 focused resource files (~40-150 lines each) for progressive disclosure: installation, workflow, commands, dependencies, authentication, governance, package-authoring, troubleshooting - Thin agent persona (~50 lines) linking to the skill for depth PROSE compliance: - Progressive Disclosure: SKILL.md loads first; resources on demand - Reduced Scope: each resource covers one domain - Orchestrated Composition: composable skill + agent + resources - Explicit Hierarchy: SKILL.md -> resources -> sections Content additions beyond original PR: - Authentication: token precedence, per-org, GHE, ADO, Artifactory - Governance: policy schema, enforcement, inheritance, audit - Dependencies: all 13+ ref formats, version pinning, MCP deps - Package authoring: all 7 primitive types with examples - Troubleshooting: error-to-fix lookup table Also extends doc-sync instruction (Rule 4) to keep skill resources synchronized when CLI commands, auth, policy, or formats change. Co-authored-by: Chris Bird <cabird@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Daniel Meppiel <danielmeppiel@users.noreply.github.com> Co-authored-by: Chris Bird <cabird@users.noreply.github.com>
1 parent 1b64a1a commit d92d3ff

12 files changed

Lines changed: 831 additions & 3 deletions

File tree

‎.github/instructions/doc-sync.instructions.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,10 @@ description: "Rules to keep documentation synchronized with code changes"
55

66
# Rules to keep documentation up-to-date
77

8-
- Rule 1: Whenever changes are made to the codebase, it's important to also update the documentation to reflect those changes. You must ensure that the following documentation is updated: [Starlight content pages in docs/src/content/docs/](../../docs/src/content/docs/). Each page uses Starlight frontmatter (title, sidebar order). Cross-page links use relative paths (e.g., `../../guides/compilation/`).
8+
- Rule 1: Whenever changes are made to the codebase, it is important to also update the documentation to reflect those changes. You must ensure that the following documentation is updated: [Starlight content pages in docs/src/content/docs/](../../docs/src/content/docs/). Each page uses Starlight frontmatter (title, sidebar order). Cross-page links use relative paths (e.g., `../../guides/compilation/`).
99

10-
- Rule 2: The main [README.md](../../README.md) file is a special case that requires user approval before changes, so, if there is a deviation in the code that affects what is stated in the main [README.md](../../README.md) file, you must warn the user and describe the drift and [README.md](../../README.md) update proposal, and wait for confirmation before updating it.
10+
- Rule 2: The main [README.md](../../README.md) file is a special case that requires user approval before changes, so, if there is a deviation in the code that affects what is stated in the main [README.md](../../README.md) file, you must warn the user and describe the drift and [README.md](../../README.md) update proposal, and wait for confirmation before updating it.
1111

12-
- Rule 3: Documentation is meant to be very simple and straightforward, we must avoid bloating it with unnecessary information. It must be pragmatic, to the point, succint and practical.To: "**"
12+
- Rule 3: Documentation is meant to be very simple and straightforward, we must avoid bloating it with unnecessary information. It must be pragmatic, to the point, succinct and practical.
13+
14+
- Rule 4: When changing CLI commands, flags, dependency formats, authentication flow, policy schema, or primitive file formats, also update the corresponding resource files in [packages/apm-guide/.apm/skills/apm-usage/](../../packages/apm-guide/.apm/skills/apm-usage/). Map changes to the correct file: commands.md for CLI changes, dependencies.md for reference formats, authentication.md for token resolution, governance.md for policy schema, package-authoring.md for primitive formats.

‎packages/apm-guide/.apm/agents/apm-expert.agent.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
name: apm-expert
3+
description: >
4+
Expert on APM (Agent Package Manager). Helps users install, configure,
5+
author, and troubleshoot APM packages, dependencies, compilation, MCP
6+
servers, and governance policies.
7+
---
8+
9+
# APM Expert
10+
11+
You are an expert on APM (Agent Package Manager), the open-source package
12+
manager for AI coding agents by Microsoft. You help developers install, manage,
13+
and author packages that deliver instructions, prompts, agents, skills, and MCP
14+
server configurations to their projects.
15+
16+
## When to use APM
17+
18+
- Sharing reusable AI instructions, prompts, or agents across repos
19+
- Installing community or org-wide coding standards packages
20+
- Managing MCP server configurations declaratively
21+
- Enforcing governance policies on AI agent dependencies
22+
- Compiling agent context for targets like Codex or Gemini
23+
24+
## When NOT to use APM
25+
26+
- Managing traditional code libraries (use npm, pip, cargo, etc.)
27+
- Deploying production applications or services
28+
- Managing infrastructure or cloud resources
29+
- Version-controlling non-AI configuration files
30+
- Tasks unrelated to AI coding agent setup
31+
32+
## Essential workflow (5 commands)
33+
34+
```bash
35+
apm init # 1. initialize project
36+
apm install owner/package#v1.0.0 # 2. install dependencies
37+
apm compile # 3. compile agent context
38+
apm run <script> # 4. run a named script
39+
apm audit --ci # 5. validate in CI
40+
```
41+
42+
**Always commit:** apm.yml, apm.lock.yaml, .apm/, .github/, .claude/, .cursor/
43+
**Never commit:** apm_modules/ (add to .gitignore)
44+
45+
## Detailed reference
46+
47+
For detailed reference on commands, authentication, dependencies, governance,
48+
and package authoring, see the
49+
[APM Usage Skill](../skills/apm-usage/SKILL.md).

‎packages/apm-guide/.apm/skills/apm-usage/SKILL.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
name: apm-usage
3+
description: >
4+
Activate when the user asks about APM (Agent Package Manager): installing,
5+
configuring, authoring, or troubleshooting AI-agent packages, dependencies,
6+
compilation, MCP servers, policy, or any `apm` CLI command.
7+
---
8+
9+
# APM Usage
10+
11+
APM (Agent Package Manager) is the open-source package manager for AI coding
12+
agents. It lets teams install, share, and govern reusable instructions, prompts,
13+
agents, skills, and MCP server configurations across projects.
14+
15+
## When to activate
16+
17+
- User mentions `apm` or "Agent Package Manager"
18+
- Questions about installing or managing AI-agent packages
19+
- Setting up instructions, prompts, agents, skills, or chatmodes
20+
- Configuring MCP servers through apm.yml
21+
- Authentication for private repos (GitHub, ADO, GHES, Artifactory)
22+
- Policy enforcement or `apm audit`
23+
- Package authoring or publishing
24+
- Compiling agent context (`apm compile`)
25+
- Troubleshooting apm errors
26+
27+
## Key rules
28+
29+
- **Commit these files:** apm.yml, apm.lock.yaml, .apm/, .github/, .claude/, .cursor/
30+
- **Never commit:** apm_modules/ (add to .gitignore)
31+
- **Team sync:** after `git clone`, run `apm install` to restore dependencies
32+
- **Update deps:** `apm install --update` refreshes to latest refs
33+
- **Pin versions:** use tags (`#v1.0.0`) in production, branches for development
34+
- **ASCII only:** all CLI output and source must stay within printable ASCII
35+
36+
## Reference
37+
38+
For detailed guidance, see the following resources:
39+
40+
- [Installation](./installation.md) -- install and update APM
41+
- [Workflow](./workflow.md) -- core workflow, apm.yml format, what to commit
42+
- [Commands](./commands.md) -- full CLI command reference
43+
- [Dependencies](./dependencies.md) -- all dependency formats and version pinning
44+
- [Authentication](./authentication.md) -- token setup for private repos
45+
- [Governance](./governance.md) -- policy engine and audit checks
46+
- [Package Authoring](./package-authoring.md) -- creating APM packages
47+
- [Troubleshooting](./troubleshooting.md) -- common errors and fixes

‎packages/apm-guide/.apm/skills/apm-usage/authentication.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Authentication
2+
3+
## Token precedence chain
4+
5+
APM checks these sources in order, using the first valid token found:
6+
7+
| Priority | Variable | Scope | Notes |
8+
|----------|----------|-------|-------|
9+
| 1 | `GITHUB_APM_PAT_{ORG}` | Per-org | Org name uppercased, hyphens to underscores |
10+
| 2 | `GITHUB_APM_PAT` | Global | Falls back to git credential if rejected |
11+
| 3 | `GITHUB_TOKEN` | Global | Shared with GitHub Actions |
12+
| 4 | `GH_TOKEN` | Global | Set by `gh auth login` |
13+
| 5 | `git credential fill` | Per-host | System credential manager |
14+
| -- | None | -- | Unauthenticated (public GitHub repos only) |
15+
16+
## Per-org setup
17+
18+
Use per-org tokens when accessing packages across multiple organizations:
19+
20+
```bash
21+
export GITHUB_APM_PAT_CONTOSO=ghp_token_for_contoso
22+
export GITHUB_APM_PAT_FABRIKAM=ghp_token_for_fabrikam
23+
```
24+
25+
**Naming rules:**
26+
- Uppercase the org name
27+
- Replace hyphens with underscores
28+
- Example: `contoso-microsoft` -> `GITHUB_APM_PAT_CONTOSO_MICROSOFT`
29+
30+
## Fine-grained PAT requirements
31+
32+
Required permissions:
33+
- **Metadata:** Read
34+
- **Contents:** Read
35+
- **Repository access:** All repos or specific repos
36+
37+
**Important:** The resource owner must be the **organization**, not your user
38+
account. User-scoped fine-grained PATs cannot access org repos even if you are
39+
a member.
40+
41+
For SSO-protected orgs, authorize the token under Settings > Tokens > Configure SSO.
42+
43+
## Azure DevOps (ADO)
44+
45+
ADO uses a dedicated token variable -- the GitHub token chain does not apply:
46+
47+
```bash
48+
export ADO_APM_PAT=your_ado_pat
49+
apm install dev.azure.com/org/project/_git/repo
50+
```
51+
52+
ADO paths use the 3-segment format: `org/project/repo`. Auth is always required.
53+
54+
## GitHub Enterprise Server (GHES)
55+
56+
```bash
57+
export GITHUB_HOST=github.company.com
58+
export GITHUB_APM_PAT_MYORG=ghp_ghes_token
59+
apm install myorg/internal-package # resolves to github.company.com
60+
```
61+
62+
## GHE Cloud data residency (*.ghe.com)
63+
64+
```bash
65+
export GITHUB_APM_PAT_MYENTERPRISE=ghp_enterprise_token
66+
apm install myenterprise.ghe.com/platform/standards
67+
```
68+
69+
No public repos exist on `*.ghe.com` -- auth is always required.
70+
71+
## Enterprise Managed Users (EMU)
72+
73+
- EMU orgs live on `github.com` (e.g., `contoso-microsoft`) or `*.ghe.com`
74+
- Use standard PAT prefixes (`ghp_`, `github_pat_`)
75+
- Fine-grained PATs must use the EMU org as resource owner
76+
- EMU accounts cannot access public repos on github.com
77+
- If mixing enterprise and public repos, use separate tokens
78+
79+
## Artifactory proxy (air-gapped environments)
80+
81+
```bash
82+
export PROXY_REGISTRY_URL=https://artifactory.company.com/apm-remote
83+
export PROXY_REGISTRY_TOKEN=your_bearer_token
84+
export PROXY_REGISTRY_ONLY=1 # optional: proxy-only mode
85+
```
86+
87+
When `PROXY_REGISTRY_ONLY=1`, APM routes all traffic through the proxy and
88+
never contacts GitHub directly.
89+
90+
## Troubleshooting
91+
92+
```bash
93+
# Diagnose the auth chain -- shows which token source is used
94+
apm install --verbose your-org/package
95+
96+
# Increase git credential timeout (default 30s, max 180s)
97+
export APM_GIT_CREDENTIAL_TIMEOUT=120
98+
```

‎packages/apm-guide/.apm/skills/apm-usage/commands.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# CLI Command Reference
2+
3+
## Project setup
4+
5+
| Command | Purpose | Key flags |
6+
|---------|---------|-----------|
7+
| `apm init [NAME]` | Initialize a new APM project | `-y` skip prompts, `--plugin` authoring mode |
8+
9+
## Dependency management
10+
11+
| Command | Purpose | Key flags |
12+
|---------|---------|-----------|
13+
| `apm install [PKGS...]` | Install packages | `--update` refresh refs, `--force` overwrite, `--dry-run`, `--verbose`, `--only [apm\|mcp]`, `--target`, `--dev`, `-g` global, `--trust-transitive-mcp`, `--parallel-downloads N` |
14+
| `apm uninstall PKGS...` | Remove packages | `--dry-run`, `-g` global |
15+
| `apm prune` | Remove orphaned packages | `--dry-run` |
16+
| `apm deps list` | List installed packages | `-g` global, `--all` both scopes |
17+
| `apm deps tree` | Show dependency tree | -- |
18+
| `apm deps info PKG` | Show package details | -- |
19+
| `apm deps clean` | Clean dependency cache | `--dry-run`, `-y` skip confirm |
20+
| `apm deps update [PKGS...]` | Update specific packages | `--verbose`, `--force`, `--target`, `--parallel-downloads N` |
21+
22+
## Compilation
23+
24+
| Command | Purpose | Key flags |
25+
|---------|---------|-----------|
26+
| `apm compile` | Compile agent context | `-o` output, `-t` target, `--chatmode`, `--dry-run`, `--no-links`, `--watch`, `--validate`, `--single-agents`, `-v` verbose, `--local-only`, `--clean`, `--with-constitution/--no-constitution` |
27+
28+
## Scripts
29+
30+
| Command | Purpose | Key flags |
31+
|---------|---------|-----------|
32+
| `apm run SCRIPT` | Execute a named script | `-p name=value` (repeatable) |
33+
| `apm preview SCRIPT` | Preview script without running | `-p name=value` |
34+
| `apm list` | List available scripts | -- |
35+
36+
## Security and audit
37+
38+
| Command | Purpose | Key flags |
39+
|---------|---------|-----------|
40+
| `apm audit [PKG]` | Scan for security issues | `--file PATH`, `--strip`, `--dry-run`, `-v`, `-f [text\|json\|sarif\|md]`, `-o PATH`, `--ci`, `--policy SOURCE`, `--no-cache`, `--no-fail-fast` |
41+
42+
## Distribution
43+
44+
| Command | Purpose | Key flags |
45+
|---------|---------|-----------|
46+
| `apm pack` | Bundle package for distribution | `-o PATH`, `-t TARGET`, `--archive`, `--dry-run`, `--format [apm\|plugin]`, `--force` |
47+
| `apm unpack BUNDLE` | Extract a bundle | `-o PATH`, `--skip-verify`, `--force`, `--dry-run` |
48+
49+
## Marketplace
50+
51+
| Command | Purpose | Key flags |
52+
|---------|---------|-----------|
53+
| `apm marketplace add OWNER/REPO` | Register a marketplace | `-n NAME`, `-b BRANCH` |
54+
| `apm marketplace list` | List registered marketplaces | -- |
55+
| `apm marketplace browse NAME` | Browse marketplace packages | -- |
56+
| `apm marketplace update [NAME]` | Update marketplace index | -- |
57+
| `apm marketplace remove NAME` | Remove a marketplace | `-y` skip confirm |
58+
| `apm search QUERY@MARKETPLACE` | Search marketplace | `--limit N` |
59+
60+
## MCP servers
61+
62+
| Command | Purpose | Key flags |
63+
|---------|---------|-----------|
64+
| `apm mcp list` | List MCP servers in project | `--limit N` |
65+
| `apm mcp search QUERY` | Search MCP registry | `--limit N` |
66+
| `apm mcp show SERVER` | Show server details | -- |
67+
68+
## Runtime management (experimental)
69+
70+
| Command | Purpose | Key flags |
71+
|---------|---------|-----------|
72+
| `apm runtime setup {copilot\|codex\|llm}` | Install a runtime | `--version`, `--vanilla` |
73+
| `apm runtime list` | Show installed runtimes | -- |
74+
| `apm runtime remove {copilot\|codex\|llm}` | Remove a runtime | `--yes` |
75+
| `apm runtime status` | Show active runtime | -- |
76+
77+
## Configuration and updates
78+
79+
| Command | Purpose | Key flags |
80+
|---------|---------|-----------|
81+
| `apm config` | Show current configuration | -- |
82+
| `apm config get [KEY]` | Get a config value | -- |
83+
| `apm config set KEY VALUE` | Set a config value | -- |
84+
| `apm update` | Update APM itself | `--check` only check |

0 commit comments

Comments
 (0)