Defame1297
60be7b3232
Only 12 of 39 skills carried metadata.version, and adoption tracked which plugin a skill lived in rather than any stated rule: core, gitea and lint were consistent adopters, bin and kyberforge were consistent non-adopters, git was split with one outlier. There was no documented convention, and skill-author's own bump logic was already written as if presence were conditional. metadata.version is now required on every skill. The 19 skills here that never carried one (bin, kyberforge, gitea-files) are seeded at 1.0.0, not 0.1.0 -- that value stays reserved for a skill's actual creation point under skill-author's existing convention. The skill-frontmatter pre-commit hook now fails a SKILL.md missing the field, the same class of failure as a missing name/description. Full rationale in the new ADR. The git-plugin skills that also need this field follow in the next commit, bundled with issue #113's rtk normalization since both touch the same files. Refs: #127 ADR: 0022 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
54 lines
2.9 KiB
Markdown
54 lines
2.9 KiB
Markdown
---
|
|
name: apm-install
|
|
description: >
|
|
Use when installing, pinning, or upgrading the apm (Agent Package Manager)
|
|
CLI itself, or installing and managing an agent runtime apm drives. Not
|
|
authoring, publishing, auditing, or dependency installation for an apm
|
|
package -> `apm-workflow`.
|
|
metadata:
|
|
version: "1.0.0"
|
|
category: apm
|
|
source_keys:
|
|
- context7-microsoft-apm
|
|
---
|
|
|
|
## Gotchas
|
|
|
|
- apm never executes an agent itself — it only installs and manages the runtimes that do. Installing apm alone leaves the user with a package manager and no working agent CLI, so Step 2 is required whenever the user actually wants one; skip it only when they explicitly want the package manager alone.
|
|
- `apm runtime setup copilot` needs Node.js v22+ and npm v10+ already on `PATH`; apm will not install them for you.
|
|
|
|
## Step 1 — Install the apm CLI
|
|
|
|
If `apm --version` already answers and the user is not pinning or upgrading, skip to Step 2.
|
|
|
|
Default:
|
|
|
|
```bash
|
|
curl -sSL https://aka.ms/apm-unix | sh
|
|
```
|
|
|
|
Escape hatches — combine as needed:
|
|
|
|
- **Pin a version** — append `@vX.Y.Z` to the piped script's arguments: `curl -sSL https://aka.ms/apm-unix | sh -s -- @v1.2.3`.
|
|
- **Custom install directory** — set `APM_INSTALL_DIR` on the piped script's command: `curl -sSL https://aka.ms/apm-unix | APM_INSTALL_DIR=$HOME/.local/bin sh`.
|
|
- **Air-gapped mirror / GitHub Enterprise** — an air-gapped host cannot reach `aka.ms` at all, so get `install.sh` onto the box and run it from disk instead of piping. Point it at the mirror with `APM_RELEASE_BASE_URL` and pin `VERSION`: `APM_RELEASE_BASE_URL=https://mirror.corp/apm VERSION=v1.2.3 sh install.sh`; add `APM_RELEASE_METADATA_URL` instead if you leave `VERSION` unset. `GITHUB_URL` is the GitHub Enterprise host, not a release mirror. All four are ordinary environment variables that also work through the pipe — running from disk is a network constraint, not a script one.
|
|
- **pip** — `pip install apm-cli` requires Python 3.10+. Not on an externally-managed (PEP 668) Python such as Debian or Ubuntu, where it hard-fails with `error: externally-managed-environment`; use pipx below. The quick-install script has no Python prerequisite, so prefer it unless the environment is pip-first.
|
|
- **pipx** — `pipx install apm-cli` on those PEP 668 environments. Same PyPI package, but pipx builds an isolated venv and exposes `apm` on `PATH`.
|
|
- **Manual** — download the platform archive from the GitHub releases page, extract, and place the binary on `PATH`.
|
|
|
|
Verify with `apm --version`.
|
|
|
|
## Step 2 — Install or manage an agent runtime
|
|
|
|
Default:
|
|
|
|
```bash
|
|
apm runtime setup copilot
|
|
```
|
|
|
|
Other targets: `apm runtime setup codex`, `apm runtime setup gemini`, `apm runtime setup llm`.
|
|
|
|
- `apm runtime list` — show installed runtimes.
|
|
- `apm runtime status` — show which runtime `apm run` will pick by default.
|
|
- `apm runtime remove <name> -y` — uninstall without an interactive prompt.
|