CLI Reference

Global options

Option	Env variable	Default	Description
`--registry <url>`	`APM_REGISTRY`	`https://apm.orthg.nl`	APM registry URL
`--version`			Print version
`--help`			Print help

Package names

All packages use scoped names in the format @scope/name. The scope is typically the GitHub owner or organization:

@anthropics/code-review
@user/my-skill
@myorg/internal-guidelines

`apm init`

Set up APM for your project. Interactive, guided setup that creates agent configuration files and wires installed skills into your agent toolchain.

apm init

What it does:

Creates AGENTS.md at project root if it doesn't exist
Adds a skill resolution block to AGENTS.md — points agents to the locally installed @apm/init skill
Lists your installed skills (from apm-lock.json) with descriptions
Detects agent config files (CLAUDE.md, .cursorrules, .github/copilot-instructions.md, GEMINI.md, .windsurfrules) and offers to wire them to AGENTS.md

Every step prompts for confirmation and explains what it's doing and why. Safe to run multiple times — it detects existing state and skips completed steps.

Example:

$ apm init

apm Setting up APM for this project.

  ? Create AGENTS.md? (Y/n) y
    AGENTS.md is the entry point for AI agents working in your project.
    It contains project-specific instructions and references to skills.
  ✓ Created AGENTS.md

  ? Teach agents how to use installed skills? (Y/n) y
    Adds the @skill: resolution syntax and a link to the APM spec to AGENTS.md.
    Without this, agents can't find or load skills installed by APM.
  ✓ Added skill resolution block to AGENTS.md

  2 installed skill(s) in apm-lock.json:
    @anthropics/code-review — Review code changes for security, performance...
    @cloudflare/code-review — Reviews Workers and Cloudflare-specific patter...

  ? Wire CLAUDE.md → AGENTS.md? (Y/n) y
    Claude Code reads CLAUDE.md but not AGENTS.md directly.
    This reference completes the chain: CLAUDE.md → AGENTS.md → skills.
  ✓ Updated CLAUDE.md

apm Done! Your agents can now discover installed skills.
  Learn more: https://apm.orthg.nl/docs/at-skill-spec

The skill resolution block added to AGENTS.md looks like:

<!-- apm:skills -->
## Installed Skills

See .skills/apm/init/SKILL.md for the APM skill specification.
<!-- /apm:skills -->

Agent config files (e.g. CLAUDE.md) get a reference block:

<!-- apm:skills -->
See [AGENTS.md](./AGENTS.md) for installed agent skills.
<!-- /apm:skills -->

See Wiring Agents to Skills for the full setup guide.

`apm install` (alias: `apm i`)

Install a skill by scoped name, or restore all from lockfile.

# Install a single skill (with dependencies)
apm install @scope/name

# Restore all skills from lockfile
apm install

What it does (single package):

Fetches package metadata from the registry
Creates .skills/scope/name/ in your project root
Writes the SKILL.md file
Records commitSha and integrity hash in the lockfile
Tracks the download with the registry
Recursively installs dependencies — if the skill is a composite with dependencies in its frontmatter, all dependencies are fetched and installed automatically

What it does (from lockfile):

Re-fetches all packages listed in apm-lock.json
Verifies integrity — compares the content hash against the lockfile. If content has changed since the lockfile was created, the install is blocked with a warning and a GitHub compare URL
Useful for cloning a project and restoring its skills

Project root detection: APM walks up from the current directory looking for apm-lock.json, package.json, Cargo.toml, or .git. Falls back to the current directory.

Example (with dependencies):

$ apm install @apm/init
apm Fetching @apm/init...
  ✓ @apm/init
apm Fetching @apm/search...
  ✓ @apm/search
apm Fetching @apm/install...
  ✓ @apm/install
apm Fetching @apm/uninstall...
  ✓ @apm/uninstall

Example (integrity mismatch on lockfile restore):

$ apm install
apm Installing 4 package(s) from lockfile...
  ↓ @apm/init...
    ⚠ WARNING: Content has changed since lockfile was created.
    Run apm update to review and accept changes.
    Diff: https://github.com/orthogonalhq/apm-skills/compare/c476879...a3f1b2c
  ↓ @apm/search... ✓
  ↓ @apm/install... ✓
  ↓ @apm/uninstall... ✓

After installing, run apm init to wire skills into your agent configs.

`apm uninstall` (alias: `apm u`)

Remove an installed skill.

apm uninstall @scope/name

What it does:

Removes .skills/scope/name/ directory
Cleans up empty scope directories
Removes the entry from apm-lock.json

Example:

$ apm uninstall @anthropics/code-review
apm Uninstalled @anthropics/code-review

`apm update` (alias: `apm up`)

Re-fetch latest versions for all installed skills with change detection.

apm update

What it does:

Reads all packages from apm-lock.json
Fetches the latest version of each from the registry
Compares integrity hashes — if content changed, shows a warning with a GitHub compare URL
Prompts for approval — you must explicitly accept changes before the skill is updated
Updates the lockfile with new commitSha and integrity hash

Example (with changes):

$ apm update
apm Updating 4 package(s)...
  ↑ @apm/init...
    ⚠ CHANGED: Content has changed.
    Diff: https://github.com/orthogonalhq/apm-skills/compare/c476879...a3f1b2c
    Accept changes? (y/N) y
    ✓ Updated
  ↑ @apm/search... ✓
  ↑ @apm/install... ✓
  ↑ @apm/uninstall... ✓
apm All packages updated

`apm search`

Search for skills in the registry.

apm search <query>

Searches the registry using full-text search over scopes, names, and descriptions. Results show the scoped name, metadata (stars, license), description, and source repository.

Example:

$ apm search "error handling"
Found 3 skill(s) matching 'error handling':

  @user/error-handling (★ 42 · MIT)
  Best practices for error handling across languages
  user/error-handling-skill

  @org/resilient-apis (★ 18 · Apache-2.0)
  Building resilient API error responses
  org/resilient-apis

`apm info`

Show details about a skill.

apm info @scope/name

Fetches and displays package metadata from the registry.

Example:

$ apm info @anthropics/code-review

  @anthropics/code-review  Systematic code review checklist

  scope: @anthropics
  repo:  anthropics/skills
  path:  code-review
  ref:   main
  owner: anthropics
  stars: 87

  Install:
  apm install @anthropics/code-review

`apm validate`

Validate a local SKILL.md file against the specification.

apm validate <path>

Accepts either a path to a SKILL.md file or a directory containing one. Checks:

YAML frontmatter is present and parseable
name field exists, is valid (lowercase alphanumeric + hyphens, max 64 chars, no consecutive hyphens)
name matches the parent directory name
description field exists and is within 1024 characters

Exit codes:

Code	Meaning
`0`	Valid
`1`	Validation errors found

Example (valid):

$ apm validate ./my-skill
✓ SKILL.md is valid
  name: my-skill
  description: A description of what this skill does

Example (invalid):

$ apm validate ./bad-skill
✗ SKILL.md has 2 error(s):
  · name must be lowercase alphanumeric with hyphens
  · description must not be empty

Lockfile

APM maintains an apm-lock.json file at your project root. It serves two purposes:

Reproducible installs — run apm install on a fresh clone to restore all skills
Tamper detection — commitSha and integrity hash verify content hasn't changed

{
  "lockfileVersion": 2,
  "packages": {
    "@apm/init": {
      "sourceRepo": "orthogonalhq/apm-skills",
      "sourcePath": "init",
      "sourceRef": "main",
      "commitSha": "c4768797c0ed8888deeb53bfc8069e68f4a7b671",
      "integrity": "sha256-7651b8aa7e84f0e9e12c3a03fa3af745635446cbb5065c77ffefb95e3afe2f34",
      "description": "APM skill resolution. Defines how @skill references resolve to installed SKILL.md files.",
      "kind": "composite",
      "dependencies": ["@apm/search", "@apm/install", "@apm/uninstall"]
    },
    "@apm/search": {
      "sourceRepo": "orthogonalhq/apm-skills",
      "sourcePath": "search",
      "sourceRef": "main",
      "commitSha": "280ccfcdf63eeeb8eddd971b7ce14a94fbca7186",
      "integrity": "sha256-d3e393fd74682b18441313f251b9484688d9834952e6629ee992d830b1c37610",
      "description": "Search the APM registry for agent skills.",
      "kind": "skill"
    }
  }
}

Field	Description
`sourceRepo`	GitHub repository
`sourcePath`	Path to SKILL.md within the repo
`sourceRef`	Git branch or tag
`commitSha`	Pinned commit SHA — immutable reference to the exact content
`integrity`	`sha256-` hash of the SKILL.md content — detects tampering
`description`	One-line description from frontmatter
`kind`	`skill` or `composite`
`dependencies`	Scoped names of required skills (composite only)
`tags`	Tags from frontmatter

Commit apm-lock.json to version control.

Command summary

Command	Alias	Description
`apm init`		Set up agent configs for your project
`apm install @scope/name`	`apm i`	Install a skill (with dependencies)
`apm install`	`apm i`	Restore all from lockfile (with integrity check)
`apm uninstall @scope/name`	`apm u`	Remove a skill
`apm update`	`apm up`	Re-fetch latest with change detection
`apm search <query>`		Search the registry
`apm info @scope/name`		Show skill details
`apm validate <path>`		Validate a SKILL.md

Environment variables

Variable	Description
`APM_REGISTRY`	Override the default registry URL. Same as `--registry`.

On this page