---
topic: configure
source_keys:
  - context7-microsoft-apm
---

## Scaffolding a new package

```bash
apm plugin init <name> --yes
```

Scaffolds `apm.yml` + a `.apm/` skeleton in the current directory. Run this once per package (e.g. once per `plugins/<name>/` directory in a monorepo-hybrid layout), not once for the whole repo.

## `apm.yml` — required fields

Only `name` and `version` (SemVer) are required:

```yaml
name: my-pkg
version: 1.0.0
```

## `apm.yml` — top-level keys

- `name`, `version` — required (see above)
- `description`, `author`, `license`, `homepage`, `repository`, `keywords` — standard package metadata
- `type` — `instructions | skill | hybrid | prompts`; constrains `.apm/` contents
- `targets` — which harnesses this package compiles to (plural list form preferred; legacy singular `target: copilot,claude` CSV form still accepted)
- `includes` — `auto` publishes the authoritative local layout as-is, or list explicit repo paths
- `dependencies`/`devDependencies` — `apm`/`mcp`/`lsp` entries; `devDependencies` share the same shape but are excluded from the shipped artifact
- `scripts` — named commands runnable via `apm run <name>`
- `compilation` — target/strategy/exclude/placement controls for `apm compile`/`apm pack`
- `policy` — e.g. `fetch_failure_default`
- `registries` — named registry endpoints for shorthand dependency resolution
- `marketplace` — owner + packages list; see `references/marketplace.md` for the full marketplace workflow

See `docs/research/docs/microsoft-apm/configuration.md` for the complete annotated schema.

## Dependency reference forms

`dependencies.apm` entries accept: a pinned tag (`owner/repo#tag`), a plain repo (uses default branch), a single primitive path within a repo, a raw git URL, a `git:`/`path:`/`ref:` object for finer control, or a local relative path (`./packages/my-shared-skills`).

## MCP server secrets

`${VAR}` indirection is required for MCP server secrets in `apm.yml` — see SKILL.md Gotchas.

## Registries (config-level, not `apm.yml`)

Any git repo is a valid package source by default — no registry required. To declare named registries for shorthand dependency resolution:

```bash
apm experimental enable registries   # required first — see SKILL.md Gotchas
apm config set registry.corp-main.url https://artifactory.corp.example.com/apm
apm config set registry.corp-main.token eyJ...
apm config set registry.corp-main.default true
```

`apm config get`/`apm config unset` manage individual keys the same way.