plugins/kyberforge/.apm/skills/apm-install/README.md

@@ -4,7 +4,7 @@ Installs and configures the `apm` (Agent Package Manager) CLI and the agent runt
 
 ## What it does
 
-Covers the two provisioning steps for working with apm: installing the `apm` binary itself (quick-install script, pinned version, air-gapped mirror, or pip), and installing/managing an agent runtime apm drives (`apm runtime setup copilot|codex|gemini|llm`, listing installed runtimes, checking which one `apm run` defaults to).
+Covers the two provisioning steps for working with apm: installing the `apm` binary itself (quick-install script, pinned version, air-gapped mirror, or pip/pipx), and installing/managing an agent runtime apm drives (`apm runtime setup copilot|codex|gemini|llm`, listing installed runtimes, checking which one `apm run` defaults to).
 
 ## Usage
 

plugins/kyberforge/.apm/skills/apm-install/SKILL.md

@@ -1,13 +1,9 @@
 ---
 name: apm-install
 description: >
-  Use when the user wants to install the apm (Agent Package Manager) CLI
-  itself, pin or upgrade its version, set up an air-gapped/enterprise mirror
-  install, or install and manage an agent runtime that apm drives (Copilot
-  CLI, Codex, Gemini, generic llm) — "install apm", "set up apm", "pin apm to
-  a version", "apm runtime setup", "which runtime will apm run pick". Do not
-  use for authoring apm.yml, scaffolding a package/marketplace, compiling,
-  packing, publishing, or running apm audit — use apm-workflow for those.
+  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, or auditing apm packages -> `apm-workflow`.
 metadata:
   category: apm
   source_keys:
@@ -16,13 +12,12 @@ metadata:
 
 ## Gotchas
 
-- apm does not execute agents itself — it only installs and manages the runtimes that do. "Install apm" and "install a runtime apm manages" are two separate steps; don't conflate them or skip the second when the user actually wants a working agent CLI, not just the package manager.
-- The air-gapped/enterprise mirror path needs `GITHUB_URL` and `VERSION` set together against a downloaded `install.sh` — it does not work through the piped one-liner form.
-- `pip install apm-cli` requires Python 3.10+; the quick-install script has no such prerequisite. Prefer the quick-install script unless the environment is pip-first.
-- On a Debian/externally-managed Python environment (PEP 668), `pip install apm-cli` fails immediately with `error: externally-managed-environment`. Fall back to `pipx install apm-cli` — same PyPI package, but pipx creates an isolated venv and correctly exposes the `apm` binary on `PATH`.
-- Installing the Copilot CLI runtime through `apm runtime setup copilot` requires Node.js v22+ and npm v10+ already present — apm does not install Node/npm for you.
+- 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.
 
-## Install apm
+## Step 1 — Install the apm CLI
+
+If `apm --version` already answers and the user is not pinning or upgrading, skip to Step 2.
 
 Default:
 
@@ -31,16 +26,17 @@ 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, e.g. `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, e.g. `curl -sSL https://aka.ms/apm-unix | APM_INSTALL_DIR=$HOME/.local/bin sh`.
-- Air-gapped / GitHub Enterprise mirror: download `install.sh` first, then run it with `GITHUB_URL` and `VERSION` set, e.g. `GITHUB_URL=https://github.corp.com VERSION=v1.2.3 sh install.sh`.
-- pip (Python 3.10+ environments): `pip install apm-cli`.
-- pipx (externally-managed/PEP 668 environments where plain `pip install` fails, e.g. Debian): `pipx install apm-cli`.
-- Manual: download the platform archive from the GitHub releases page, extract, place the binary on `PATH`.
+
+- **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`.
 
-## Install or manage an agent runtime
+## Step 2 — Install or manage an agent runtime
 
 Default:
 

plugins/kyberforge/skills/apm-install/README.md

@@ -4,7 +4,7 @@ Installs and configures the `apm` (Agent Package Manager) CLI and the agent runt
 
 ## What it does
 
-Covers the two provisioning steps for working with apm: installing the `apm` binary itself (quick-install script, pinned version, air-gapped mirror, or pip), and installing/managing an agent runtime apm drives (`apm runtime setup copilot|codex|gemini|llm`, listing installed runtimes, checking which one `apm run` defaults to).
+Covers the two provisioning steps for working with apm: installing the `apm` binary itself (quick-install script, pinned version, air-gapped mirror, or pip/pipx), and installing/managing an agent runtime apm drives (`apm runtime setup copilot|codex|gemini|llm`, listing installed runtimes, checking which one `apm run` defaults to).
 
 ## Usage
 

plugins/kyberforge/skills/apm-install/SKILL.md

@@ -1,13 +1,9 @@
 ---
 name: apm-install
 description: >
-  Use when the user wants to install the apm (Agent Package Manager) CLI
-  itself, pin or upgrade its version, set up an air-gapped/enterprise mirror
-  install, or install and manage an agent runtime that apm drives (Copilot
-  CLI, Codex, Gemini, generic llm) — "install apm", "set up apm", "pin apm to
-  a version", "apm runtime setup", "which runtime will apm run pick". Do not
-  use for authoring apm.yml, scaffolding a package/marketplace, compiling,
-  packing, publishing, or running apm audit — use apm-workflow for those.
+  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, or auditing apm packages -> `apm-workflow`.
 metadata:
   category: apm
   source_keys:
@@ -16,13 +12,12 @@ metadata:
 
 ## Gotchas
 
-- apm does not execute agents itself — it only installs and manages the runtimes that do. "Install apm" and "install a runtime apm manages" are two separate steps; don't conflate them or skip the second when the user actually wants a working agent CLI, not just the package manager.
-- The air-gapped/enterprise mirror path needs `GITHUB_URL` and `VERSION` set together against a downloaded `install.sh` — it does not work through the piped one-liner form.
-- `pip install apm-cli` requires Python 3.10+; the quick-install script has no such prerequisite. Prefer the quick-install script unless the environment is pip-first.
-- On a Debian/externally-managed Python environment (PEP 668), `pip install apm-cli` fails immediately with `error: externally-managed-environment`. Fall back to `pipx install apm-cli` — same PyPI package, but pipx creates an isolated venv and correctly exposes the `apm` binary on `PATH`.
-- Installing the Copilot CLI runtime through `apm runtime setup copilot` requires Node.js v22+ and npm v10+ already present — apm does not install Node/npm for you.
+- 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.
 
-## Install apm
+## Step 1 — Install the apm CLI
+
+If `apm --version` already answers and the user is not pinning or upgrading, skip to Step 2.
 
 Default:
 
@@ -31,16 +26,17 @@ 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, e.g. `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, e.g. `curl -sSL https://aka.ms/apm-unix | APM_INSTALL_DIR=$HOME/.local/bin sh`.
-- Air-gapped / GitHub Enterprise mirror: download `install.sh` first, then run it with `GITHUB_URL` and `VERSION` set, e.g. `GITHUB_URL=https://github.corp.com VERSION=v1.2.3 sh install.sh`.
-- pip (Python 3.10+ environments): `pip install apm-cli`.
-- pipx (externally-managed/PEP 668 environments where plain `pip install` fails, e.g. Debian): `pipx install apm-cli`.
-- Manual: download the platform archive from the GitHub releases page, extract, place the binary on `PATH`.
+
+- **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`.
 
-## Install or manage an agent runtime
+## Step 2 — Install or manage an agent runtime
 
 Default: