---
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` — full schema

```yaml
name: my-pkg
version: 1.0.0
description: Code review skills for Python services
author: Jane Doe            # plain string, or {name, email?, url?} object
license: MIT
homepage: https://example.com/my-pkg
repository: https://github.com/org/my-pkg
keywords: [ai, review, python]

type: skill                 # instructions | skill | hybrid | prompts — constrains .apm/ contents

targets:                    # which harnesses this package compiles to; prefer plural list form
  - copilot
  - claude

includes: auto               # "auto" = publish the authoritative local layout; or list explicit repo paths

dependencies:
  apm:
    - microsoft/apm-sample-package#v1.0.0        # pinned to a tag
    - github/awesome-copilot/skills/review-and-refactor  # single primitive
  mcp:
    - microsoft/azure-devops-mcp                 # MCP server dependency
  lsp:
    - name: pyright
      command: pyright-langserver
      args: ["--stdio"]
      extensionToLanguage:
        ".py": python

devDependencies:             # same shape as dependencies, excluded from the shipped artifact
  apm:
    - my-org/internal-test-skills

scripts:                     # named commands runnable via `apm run <name>`
  start: "copilot -p 'README.prompt.md'"
  review: "copilot -p 'code-review.prompt.md'"

compilation:
  target: all
  strategy: distributed
  exclude:
    - "apm_modules/**"
  placement:
    min_instructions_per_file: 1

policy:
  fetch_failure_default: warn

registries:
  public-apm:
    url: https://registry.example.com/api/public-apm
  default: public-apm

marketplace:                 # see references/marketplace.md for the full marketplace workflow
  owner:
    name: contoso
    url: https://github.com/contoso
  packages:
    - name: code-review
      source: contoso/code-review
      version: "^1.0.0"
      tags: [review, quality]
```

## 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

Use `${VAR}` indirection for headers/env vars — never a literal secret value in `apm.yml`:

```yaml
mcp:
  - name: linear
    registry: false
    transport: http
    url: https://mcp.linear.app/sse
    headers:
      Authorization: "Bearer ${LINEAR_TOKEN}"
  - name: my-internal
    registry: false
    transport: stdio
    command: my-server
    env:
      API_TOKEN: "${MY_API_TOKEN}"
```

## 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.