holocron/plugins/kyberforge/docs/research/docs/microsoft-apm/configuration.md

topic, source_keys

topic	source_keys
configuration	context7-microsoft-apm

The apm.yml manifest

Every APM package — producer or consumer — is rooted in an apm.yml file. The only required fields are name and version (SemVer):

name: my-pkg
version: 1.0.0

Full schema

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]

# Constrains what .apm/ may contain: instructions, skill, hybrid, or prompts
type: skill

# Pins which harnesses this package compiles to. Prefer the plural `targets:`
# list form; the legacy singular `target:` CSV form is still accepted.
targets:
  - copilot
  - claude

# "auto" publishes the authoritative local source layout, or list explicit
# repo paths to define the complete publication set.
includes: auto

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

# Same shape as dependencies, but excluded from the shipped artifact —
# for dev-only tooling and tests.
devDependencies:
  apm:
    - my-org/internal-test-skills

# Named commands runnable via `apm run <name>`
scripts:
  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:
  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 several forms: 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

Secrets for MCP server config (headers, env vars) should use ${VAR} indirection rather than literal values, so they're resolved by APM or the host harness at install/runtime and never committed to the manifest:

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

Registries are optional — any git repo is a valid package source by default — but a project can declare named registries and pick a default: for shorthand dependency resolution, useful for teams centralizing internal packages.