Skip to content

Add dedicated APM Dependencies reference page #20674

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Mar 12, 2026
Merged

Add dedicated APM Dependencies reference page #20674

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
922de40
Initial plan
Copilot Mar 12, 2026
c5f2ab6
Add APM dependencies reference page and update frontmatter.md section
Copilot Mar 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 82 additions & 0 deletions docs/src/content/docs/reference/dependencies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
---
title: APM Dependencies
description: Install and manage APM (Agent Package Manager) packages in your agentic workflows, including skills, prompts, instructions, agents, hooks, and plugins.
sidebar:
order: 330
---

The `dependencies:` frontmatter field installs [APM (Agent Package Manager)](https://microsoft.github.io/apm/) packages before workflow execution. When present, the compiler packs dependencies in the activation job and unpacks them in the agent job for faster, deterministic startup.

APM manages AI agent primitives such as skills, prompts, instructions, agents, hooks, and plugins (including the Claude `plugin.json` specification). Packages can depend on other packages and APM resolves the full dependency tree.

## Reproducibility and governance

APM lock files (`apm.lock`) pin every package to an exact commit SHA, so the same versions are installed on every run. Lock file diffs appear in pull requests and are reviewable before merge, giving teams and enterprises a clear audit trail and the ability to govern which agent context is in use. See the [APM governance guide](https://microsoft.github.io/apm/enterprise/governance/) for details on policy enforcement and access controls.

## Format

### Simple array format

```yaml wrap
dependencies:
- microsoft/apm-sample-package
- github/awesome-copilot/skills/review-and-refactor
- anthropics/skills/skills/frontend-design
```

### Object format with options

```yaml wrap
dependencies:
packages:
- microsoft/apm-sample-package
- github/awesome-copilot/skills/review-and-refactor
isolated: true # clear repo primitives before unpack (default: false)
```

## Package reference formats

Each entry is an APM package reference. Supported formats:

| Format | Description |
|--------|-------------|
| `owner/repo` | Full APM package |
| `owner/repo/path/to/primitive` | Individual primitive (skill, instruction, plugin, etc.) from a repository |
| `owner/repo#ref` | Package pinned to a tag, branch, or commit SHA |

Comment on lines +41 to +46
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page documents owner/repo#ref dependency references, but the current frontmatter schema disallows # in dependencies entries (see pkg/parser/schemas/main_workflow_schema.json → dependencies item pattern: ^[a-zA-Z0-9_-]+/[a-zA-Z0-9_./-]+$). Users following this format will hit a schema validation error during compilation.

Either adjust the docs to match the schema (no #ref), or update the schema (and ideally add tests) to permit optional #ref suffixes for dependency strings.

Copilot uses AI. Check for mistakes.
### Examples

```yaml wrap
dependencies:
# Full APM package
- microsoft/apm-sample-package
# Individual primitive from any repository
- github/awesome-copilot/skills/review-and-refactor
# Plugin (Claude plugin.json format)
- github/awesome-copilot/plugins/context-engineering
# Version-pinned to a tag
- microsoft/apm-sample-package#v2.0
# Version-pinned to a branch
- microsoft/apm-sample-package#main
# Git URL with sub-path and ref (object format)
- git: https://github.com/acme/coding-standards.git
path: instructions/security
ref: v2.0
Comment on lines +61 to +64
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example shows a dependencies entry as an object (- git: … path: … ref: …), but gh-aw only extracts dependency entries as strings (see extractAPMDependenciesFromFrontmatter in pkg/workflow/frontmatter_extraction_metadata.go) and renders them as - <string> lines for microsoft/apm-action (see GenerateAPMPackStep in pkg/workflow/apm_dependencies.go). This object-form per-item reference won’t compile/work.

Either remove this example, or extend the schema + frontmatter extraction + pack-step generation to support structured dependency objects and map them to whatever input format apm-action expects.

Suggested change
# Git URL with sub-path and ref (object format)
- git: https://github.com/acme/coding-standards.git
path: instructions/security
ref: v2.0

Copilot uses AI. Check for mistakes.
```

## Compilation behavior

The compiler emits an `apm pack` step in the activation job and an `apm unpack` step in the agent job. The APM target is automatically inferred from the configured engine (`copilot`, `claude`, or `all` for other engines). The `isolated` flag controls whether existing `.github/` primitive directories are cleared before the bundle is unpacked in the agent job.

To reproduce or debug the pack/unpack flow locally, run `apm pack` and `apm unpack` directly. See the [pack and distribute guide](https://microsoft.github.io/apm/guides/pack-distribute/) for instructions.

## Reference

| Resource | URL |
|----------|-----|
| APM documentation | https://microsoft.github.io/apm/ |
| APM governance guide | https://microsoft.github.io/apm/enterprise/governance/ |
| Pack and distribute guide | https://microsoft.github.io/apm/guides/pack-distribute/ |
| gh-aw integration (APM docs) | https://microsoft.github.io/apm/integrations/gh-aw/ |
| apm-action (GitHub) | https://github.com/microsoft/apm-action |
| microsoft/apm (GitHub) | https://github.com/microsoft/apm |
25 changes: 3 additions & 22 deletions docs/src/content/docs/reference/frontmatter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,35 +151,16 @@ Each plugin repository must be specified in `org/repo` format. The compiler gene

### APM Dependencies (`dependencies:`)

Specifies [microsoft/apm](https://github.com/microsoft/apm) packages to install before workflow execution. When present, the compiler resolves and packs dependencies in the activation job, then unpacks them in the agent job for faster, deterministic startup.

APM (Agent Package Manager) manages AI agent primitives such as skills, prompts, instructions, agents, and hooks. Packages can depend on other packages and APM resolves the full dependency tree.

**Simple array format** (most common):
Specifies [APM (Agent Package Manager)](https://microsoft.github.io/apm/) packages to install before workflow execution. APM manages AI agent primitives such as skills, prompts, instructions, agents, hooks, and plugins (including the Claude `plugin.json` format). When present, the compiler runs `apm pack` in the activation job and `apm unpack` in the agent job for faster, deterministic startup.

```yaml wrap
dependencies:
- microsoft/apm-sample-package
- github/awesome-copilot/skills/review-and-refactor
- anthropics/skills/skills/frontend-design
- microsoft/apm-sample-package#v2.0 # version-pinned
```
Comment on lines +154 to 161
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docs now show version pinning via owner/repo#ref (e.g. microsoft/apm-sample-package#v2.0), but the compiler’s frontmatter JSON schema currently rejects # in dependencies entries (see pkg/parser/schemas/main_workflow_schema.json where dependencies item pattern is ^[a-zA-Z0-9_-]+/[a-zA-Z0-9_./-]+$). As written, users following this example will fail schema validation at compile time.

Either remove the #ref example/claims here, or update the schema (and any related validation/docs) to explicitly allow #ref for dependency entries.

Copilot uses AI. Check for mistakes.

**Object format** with options:

```yaml wrap
dependencies:
packages:
- microsoft/apm-sample-package
- github/awesome-copilot/skills/review-and-refactor
isolated: true # clear repo primitives before unpack (default: false)
```

Each entry is an APM package reference. Supported formats:

- `owner/repo` — full APM package
- `owner/repo/path/to/skill` — individual skill or primitive from a repository

The compiler emits a pack step in the activation job and a restore step in the agent job. The APM target is automatically inferred from the configured engine (`copilot`, `claude`, or `all` for other engines). The `isolated` flag controls whether existing `.github/` primitive directories are cleared before the bundle is unpacked in the agent job.
See **[APM Dependencies Reference](/gh-aw/reference/dependencies/)** for the full format specification, version pinning syntax, plugin support, reproducibility and governance details, and local debugging instructions.

### Runtimes (`runtimes:`)

Expand Down
Loading