From e83c0b1aedc77858c854436aebcc550d2736161b Mon Sep 17 00:00:00 2001
From: Toon Verwerft <toonverwerft@gmail.com>
Date: Thu, 3 Sep 2026 10:54:43 +0200
Subject: [PATCH] Make the agent skills installable via APM
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The skills live in `.agents/skills/`, which is the cross-runtime location
agents read directly — but it is not a layout APM discovers in a source
repo. APM expects `apm.yml` + `.apm/skills/` at the package root
(`.agents/skills/` is its deploy *target*, not a source), so pointing a
dependency at this repo failed with "no apm.yml, SKILL.md, hooks, or
plugin structure found".

Adds the two files that make it a package, mirroring how our other skill
bundles are laid out:

* `apm.yml` — name, description, version
* `.apm/skills` — symlink to `../.agents/skills`

`.agents/skills/` stays the single source of truth, so a plain checkout
keeps working without APM, and one dependency now pulls all six skills:

    dependencies:
      apm:
        - git: git@github.com:phpro/http-tools.git
          ref: v2.x

Verified against APM 0.29.0: resolves as `package_type: apm_package` and
integrates 6 skills with their `references/` files intact.
---
 .agents/skills/README.md | 29 +++++++++++++++++++++++++++++
 .apm/skills              |  1 +
 apm.yml                  |  8 ++++++++
 3 files changed, 38 insertions(+)
 create mode 120000 .apm/skills
 create mode 100644 apm.yml

diff --git a/.agents/skills/README.md b/.agents/skills/README.md
index 8a9bd15..ac9aae9 100644
--- a/.agents/skills/README.md
+++ b/.agents/skills/README.md
@@ -7,6 +7,35 @@ read it, some via a `.claude/skills` symlink which is git-ignored here).
 They are written for the **consumer** of this package — someone integrating a third-party API in
 their own application — not for contributors to the library itself.
 
+## Installing
+
+Via [APM](https://microsoft.github.io/apm/), which deploys all six into your harness of choice:
+
+```yaml
+# apm.yml
+dependencies:
+  apm:
+    - git: git@github.com:phpro/http-tools.git
+      ref: v2.x
+```
+
+```bash
+apm install
+```
+
+`apm.yml` and `.apm/skills` (a symlink to this directory) at the repo root are what make the
+package installable; `.agents/skills/` stays the real home, so the skills also work by plain
+checkout without APM. Pass `--target agent-skills` if you want them deployed to `.agents/skills/`
+in the consuming project rather than to a specific harness.
+
+To pull in only some of them, name the skills you want:
+
+```yaml
+    - git: git@github.com:phpro/http-tools.git
+      ref: v2.x
+      skills: [generate-http-response, test-http-integration]
+```
+
 ## Skills
 
 | Skill | Use when |
diff --git a/.apm/skills b/.apm/skills
new file mode 120000
index 0000000..2b7a412
--- /dev/null
+++ b/.apm/skills
@@ -0,0 +1 @@
+../.agents/skills
\ No newline at end of file
diff --git a/apm.yml b/apm.yml
new file mode 100644
index 0000000..737bc7d
--- /dev/null
+++ b/apm.yml
@@ -0,0 +1,8 @@
+name: phpro/http-tools
+description: Agent skills for building HTTP integrations with phpro/http-tools — requests, responses, request handlers, client/transport configuration and tests.
+version: 0.1.0
+author: Toon Verwerft
+dependencies:
+  apm: []
+  mcp: []
+scripts: {}