|
| 1 | +--- |
| 2 | +number: 0001 |
| 3 | +date: 2026-06-20 |
| 4 | +raising_team: echohello-dev |
| 5 | + |
| 6 | +status: accepted |
| 7 | +--- |
| 8 | + |
| 9 | +# 0001. Adopt APM Manifest Compliance with Scoped Profile |
| 10 | + |
| 11 | +## Context |
| 12 | + |
| 13 | +Microsoft APM (Agent Package Manager) has published the OpenAPM v0.1 specification with a formal JSON Schema for `apm.yml`. The spec explicitly invites third-party conforming resolvers. APM is gaining traction as the de facto dependency manager for agent skills, prompts, and MCP servers across Claude, Copilot, Cursor, OpenCode, Codex, Gemini, and Windsurf. |
| 14 | + |
| 15 | +Skillet (`sklt`) was built as a lightweight, skills-only resolver with unique support for OCI artifacts and single-binary distribution. Until now it had no manifest format — installations were purely CLI-driven (`sklt add <source>`). This creates friction for teams who want reproducible, version-pinned skill trees checked into source control. |
| 16 | + |
| 17 | +We evaluated three paths: |
| 18 | +1. **Invent `skillet.yml`** — own format, own ecosystem, full control. |
| 19 | +2. **Become an APM-conforming resolver** — read/write `apm.yml`, interoperate with the growing APM ecosystem. |
| 20 | +3. **Hybrid** — support both formats. |
| 21 | + |
| 22 | +## Decision |
| 23 | + |
| 24 | +Adopt **Path 2: APM-conforming resolver with a scoped profile**. |
| 25 | + |
| 26 | +- Skillet reads and writes `apm.yml` as its primary manifest. |
| 27 | +- Skillet resolves `dependencies.apm` entries (git, local, HTTP sources) and deploys skills into per-agent directories. |
| 28 | +- Skillet **ignores** `mcp`, `lsp`, `hooks`, `commands`, `plugins`, `marketplace`, `compilation`, and `policy` blocks, surfacing a clear "not supported by sklt" notice when these are present. This aligns with the spec which permits resolvers to ignore unknown keys. |
| 29 | +- Skillet **retains** `skillet.lock.yaml` as its lockfile format for now, with field names aligned to APM's lockfile spec where practical. A future ADR may adopt `apm.lock.yaml` directly. |
| 30 | +- Skillet **adds** `sklt install` as the bare-install command (no arguments = install everything declared in `apm.yml`). |
| 31 | +- `sklt add <source>` updates `apm.yml` when one exists, appending the source to `dependencies.apm`. |
| 32 | + |
| 33 | +### Rationale |
| 34 | + |
| 35 | +- **Ecosystem access:** Any repo with an `apm.yml` works with Skillet immediately. |
| 36 | +- **Differentiation preserved:** OCI artifacts, single-binary distribution, and symlink-first installs remain unique to Skillet. |
| 37 | +- **Reduced design burden:** We don't need to design, document, and evangelise a competing manifest format. |
| 38 | +- **Future optionality:** If OpenAPM adds OCI in a future revision, we can propose it as a spec extension from a position of working implementation. |
| 39 | + |
| 40 | +## Consequences |
| 41 | + |
| 42 | +### Positive |
| 43 | +- Instant compatibility with APM-authored packages and marketplaces. |
| 44 | +- Teams can migrate between APM and Skillet without rewriting manifests. |
| 45 | +- `sklt install` provides reproducible, manifest-driven workflows. |
| 46 | +- Positions Skillet as "the lightweight, OCI-native APM resolver for skills-only workflows." |
| 47 | + |
| 48 | +### Negative / trade-offs |
| 49 | +- Must track a moving specification (OpenAPM v0.3 working draft). |
| 50 | +- Scope is narrower than APM; some users may expect MCP/plugin support and be disappointed. |
| 51 | +- Virtual-package shorthand (`owner/repo/path`) is not yet supported by our git resolver; object-form (`git` + `path`) must be used instead. |
| 52 | + |
| 53 | +### Follow-ups |
| 54 | +- ADR-0002: Evaluate adopting `apm.lock.yaml` directly vs keeping `skillet.lock.yaml`. |
| 55 | +- Issue: Add virtual-package shorthand support to `src/resolvers/git.ts`. |
| 56 | +- Issue: Implement `--frozen` CI mode for `sklt install`. |
| 57 | +- Issue: Implement `--update` consent-gated ref refresh for `sklt install`. |
| 58 | + |
| 59 | +## References |
| 60 | +- https://microsoft.github.io/apm/reference/manifest-schema/ |
| 61 | +- https://microsoft.github.io/apm/reference/lockfile-spec/ |
| 62 | +- https://github.com/microsoft/apm/blob/main/manifest-v0.1.schema.json |
| 63 | +- docs/parity/2026-02-20-vercel-cli-parity.md |
0 commit comments