Skip to content

Commit 63b0e5d

Browse files
authored
feat(manifest): adopt APM manifest compliance with scoped profile (#57)
- Add apm.yml parser supporting OpenAPM v0.1 scoped subset (dependencies.apm string/object forms, target/targets) - Add sklt install command to resolve and install from apm.yml - Wire sklt add to update apm.yml when present - Add tests for manifest parser and install command - Update README and parity docs for APM compatibility - Record decision in ADR-0001
1 parent 06a2024 commit 63b0e5d

9 files changed

Lines changed: 959 additions & 8 deletions

File tree

‎README.md‎

Lines changed: 40 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,18 +26,21 @@ mise run dev -- --help
2626
## CLI Usage
2727

2828
```bash
29-
skillet --help
30-
skillet find [query]
31-
skillet init [directory]
29+
sklt --help
30+
sklt find [query]
31+
sklt init [directory]
32+
sklt add <source>
33+
sklt install
3234
```
3335

3436
Implemented commands:
3537
- `find`: search discovered local skills by name/description
3638
- `init`: scaffold a valid `SKILL.md`
39+
- `add`: install skills from a source (git, OCI, HTTP archive, local)
40+
- `install`: install all dependencies declared in `apm.yml`
3741
- `generate-lock`: deterministic `skillet.lock.yaml` generation from installed skills
3842

3943
In-progress commands:
40-
- `add`
4144
- `check`
4245
- `update`
4346

@@ -92,6 +95,39 @@ sources:
9295
- <agent-id>
9396
```
9497
98+
## APM Manifest
99+
100+
Skillet reads and writes `apm.yml` as its primary manifest format, conforming to the [OpenAPM v0.1 specification](https://microsoft.github.io/apm/reference/manifest-schema/) with a scoped profile for skills only.
101+
102+
Supported fields:
103+
- `name`, `version`, `description`
104+
- `target` / `targets`: which agent harnesses to deploy to
105+
- `dependencies.apm`: git, local, and HTTP sources
106+
107+
Unsupported fields (ignored with notice):
108+
- `dependencies.mcp`, `dependencies.lsp`
109+
- `scripts`, `includes`, `registries`, `policy`, `compilation`, `marketplace`
110+
111+
Example `apm.yml`:
112+
113+
```yaml
114+
name: my-project
115+
version: 1.0.0
116+
dependencies:
117+
apm:
118+
- microsoft/apm-sample-package#v1.0.0
119+
- git: https://gitlab.com/acme/coding-standards.git
120+
path: instructions/security
121+
ref: v2.0
122+
- ./local-skills
123+
```
124+
125+
Install everything declared:
126+
127+
```bash
128+
sklt install
129+
```
130+
95131
## OCI Artifact Spec
96132

97133
Skillet OCI resolver expects artifacts with:
Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
number: 0001
3+
date: 2026-06-20
4+
raising_team: echohello-dev
5+
prepared_by: [email protected]
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

‎docs/parity/2026-02-20-vercel-cli-parity.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,38 @@ Parity review covers:
2828
3. Complete flag-level parity during `add/check/update` implementation issues (`#10`, `#12`).
2929
4. Revisit optional parity for `remove/list` after core install/update workflow is complete.
3030

31+
## APM Manifest Parity (added 2026-06-20)
32+
33+
Compared against: [OpenAPM v0.1 manifest schema](https://microsoft.github.io/apm/reference/manifest-schema/)
34+
35+
| Area | APM | `skillet` | Status | Notes |
36+
| --- | --- | --- | --- | --- |
37+
| Manifest format | `apm.yml` | `apm.yml` (read/write) | **Accepted** | ADR-0001: adopt APM manifest with scoped profile. |
38+
| `dependencies.apm` | String + object forms, git/local/HTTP/registry/marketplace | String + object forms, git/local/HTTP only | Partial | Registry and marketplace deps are not supported. |
39+
| `dependencies.mcp` | Full MCP server management | Not supported | Intentional gap | Out of scope for skills-only resolver. |
40+
| `dependencies.lsp` | LSP server entries | Not supported | Intentional gap | Out of scope. |
41+
| `target` / `targets` | String or list, auto-detect | String or list, auto-detect | Partial | Only maps to Skillet's known agents; unsupported targets silently ignored. |
42+
| `scripts` | Named shell commands | Not supported | Intentional gap | Out of scope. |
43+
| `includes` | Auto or explicit path list | Not supported | Intentional gap | Out of scope. |
44+
| `registries` | REST-based APM registries | Not supported | Gap | Could be added later; not on immediate roadmap. |
45+
| `policy` | Consumer-side org policy | Not supported | Intentional gap | Out of scope. |
46+
| `compilation` | `apm compile` settings | Not supported | Intentional gap | Out of scope. |
47+
| `marketplace` | Marketplace authoring block | Not supported | Intentional gap | Out of scope. |
48+
| `sklt install` | `apm install` equivalent | Implemented | Partial | No `--frozen`, `--update`, or transitive resolution yet. |
49+
| Lockfile | `apm.lock.yaml` | `skillet.lock.yaml` | Partial | Field names aligned where practical; may adopt `apm.lock.yaml` in future ADR. |
50+
51+
## Decisions
52+
53+
1. Keep lightweight output style (no branded/colorized output) as an intentional divergence.
54+
2. Maintain core command name parity (`add/find/check/update/init`).
55+
3. Complete flag-level parity during `add/check/update` implementation issues (`#10`, `#12`).
56+
4. Revisit optional parity for `remove/list` after core install/update workflow is complete.
57+
5. **(NEW)** Adopt `apm.yml` as primary manifest per ADR-0001; scope to skills-only subset.
58+
3159
## Follow-up items
3260

3361
- `#10` Add command implementation and flag parity.
3462
- `#12` Check/update command parity and behavior.
3563
- Future: decide whether `remove/list` parity is required for v1.
64+
- Future ADR: evaluate adopting `apm.lock.yaml` directly.
65+
- Issue: add virtual-package shorthand (`owner/repo/path`) to git resolver.

‎src/cli.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,10 @@ import { runAddCommand } from "./commands/add";
55
import { runCheckCommand } from "./commands/check";
66
import { runFindCommand } from "./commands/find";
77
import { runInitCommand } from "./commands/init";
8+
import { runInstallCommand } from "./commands/install";
89
import { runUpdateCommand } from "./commands/update";
910

10-
const COMMANDS = ["add", "find", "check", "update", "init", "generate-lock"] as const;
11+
const COMMANDS = ["add", "find", "check", "update", "init", "install", "generate-lock"] as const;
1112
type CommandName = (typeof COMMANDS)[number];
1213

1314
type GlobalFlags = {
@@ -36,6 +37,7 @@ const COMMAND_HELP: Record<CommandName, string> = {
3637
check: "Check for updates to installed skills",
3738
update: "Update installed skills",
3839
init: "Create a SKILL.md template",
40+
install: "Install dependencies from apm.yml",
3941
"generate-lock": "Generate skillet.lock.yaml",
4042
};
4143

@@ -76,6 +78,10 @@ async function runCommand(command: CommandName, args: string[], flags: GlobalFla
7678
return runInitCommand(args, { yes: flags.yes });
7779
}
7880

81+
if (command === "install") {
82+
return runInstallCommand(args, { yes: flags.yes, verbose: flags.verbose });
83+
}
84+
7985
if (flags.verbose) {
8086
console.error(`Running ${command} with args: ${args.join(" ")}`);
8187
}

‎src/commands/add.ts‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import { resolveGitSource } from "../resolvers/git";
88
import { resolveHttpArchive } from "../resolvers/http-archive";
99
import { resolveOciSource } from "../resolvers/oci";
1010
import { parseSkillMarkdown } from "../skills/skill";
11+
import { readApmManifest, writeApmManifest, addDependencyToManifest } from "../manifest/apm";
1112

1213
type WriteLine = (line: string) => void;
1314

@@ -149,6 +150,18 @@ export async function runAddCommand(args: string[], options: RunAddCommandOption
149150
stdout(`Updated lockfile: ${lock.outputPath}`);
150151
}
151152

153+
// Update apm.yml if present and source is new
154+
const manifest = readApmManifest(cwd);
155+
if (manifest && !parsed.global) {
156+
const added = addDependencyToManifest(manifest, parsed.source);
157+
if (added) {
158+
writeApmManifest(cwd, manifest);
159+
if (options.verbose) {
160+
stdout(`Updated apm.yml with ${parsed.source}`);
161+
}
162+
}
163+
}
164+
152165
return 0;
153166
}
154167

@@ -269,7 +282,7 @@ type ResolvedSource = {
269282
contentPath: string;
270283
};
271284

272-
async function resolveSource(
285+
export async function resolveSource(
273286
source: string,
274287
options: { tempRoot: string; insecureHttp?: boolean }
275288
): Promise<ResolvedSource> {
@@ -319,13 +332,13 @@ async function resolveSource(
319332
};
320333
}
321334

322-
type SourceSkill = {
335+
export type SourceSkill = {
323336
name: string;
324337
description: string;
325338
path: string;
326339
};
327340

328-
function discoverSourceSkills(contentPath: string): SourceSkill[] {
341+
export function discoverSourceSkills(contentPath: string): SourceSkill[] {
329342
const candidates = new Set<string>();
330343
const standardRoots = [
331344
contentPath,

0 commit comments

Comments
 (0)