Evaluate APM (Agent Package Manager) as the distribution mechanism

[vnys]

What

Evaluate APM (Agent Package Manager) — Microsoft, MIT-licensed — as the distribution mechanism for the skills in this repo.

Why

This repo's unsolved problem is distribution: a team currently has to know the repo exists and copy files by hand. APM is "npm for agent context":

• an apm.yml manifest declares skills/prompts/agents/MCP servers as versioned dependencies (from GitHub/ADO/GitLab), with content hashing and an optional apm-policy.yml for install-time governance
• apm install deploys each component to whatever harness the developer actually runs — GitHub Copilot, Claude Code, Cursor, Codex, OpenCode, Windsurf, Kiro and more; each harness receives only the primitives it supports

The cross-harness part is the real argument at Equinor: most developers are on Copilot, so Claude-only skill distribution raises the floor for a minority. The Fusion team already references APM in equinor/fusion-skills, so adopting it here could align with an emerging house convention rather than inventing a parallel one.

Suggested scope

1. Look at how equinor/fusion-skills uses APM (manifest shape, versioning, policy)
2. Prototype an apm.yml in a consumer repo that pulls one skill from here (the CSS authoring skill, Create CSS authoring skill #12, is a good candidate — it is harness-agnostic prose)
3. Check what a skill needs to look like to be APM-packageable (naming, frontmatter, directory layout) and whether that constrains anything we planned in the epics
4. Decide: adopt, wait, or pass — and record the decision in the README

Non-goals

• Migrating this repo's authoring workflow — APM is about consumption, the skills are still authored here as plain markdown.

[vnys]

Evaluated against the four scope items. Everything factual in the issue checks out, and one point is stronger than stated.

Verified

• microsoft/apm — real, MIT, 3,665 stars, last pushed today. Actively maintained, not a stalled experiment.
• Fusion does use it: three packages under apm/ (fusion-developer, -app, -services), each an apm.yml bundling skills, agents, instructions and MCP.
• The cross-harness claim holds, per APM's own targets matrix.

The strongest argument, which the issue understates

From docs/reference/targets-matrix, skills is the only primitive supported by all twelve targets:

Primitive	Targets supporting it
skills	12 of 12 — copilot, claude, cursor, codex, gemini, opencode, windsurf, kiro, grok-build, antigravity, intellij, agent-skills
mcp	10
hooks	9
instructions	7
agents	7
commands	6
prompts	2

This repo ships nothing but skills. We are in the one lane with no compatibility gaps — the distribution risk of adopting APM is close to zero, and the Copilot-majority argument in the issue is served without qualification.

Scope 3 — what a skill must look like

We already comply. APM's conventional layout is:

<skill-name>/
  SKILL.md      required — the directory name is the skill's identity
  scripts/      optional
  references/   optional
  assets/       optional
  examples/     optional

typography-x-height-alignment was restructured into exactly that shape earlier today for unrelated reasons (the 300-line ceiling), so the fit is already there. APM's name rules — lowercase alphanumeric plus hyphens, 1–64 chars, no consecutive or leading/trailing hyphens, must equal the directory name — match what CLAUDE.md already requires. No constraint on anything planned in the epics.

APM also consumes a skill directory directly as a dependency (Fusion's manifests use path: skills/fusion-devtools), so no restructuring into .apm/skills/ is needed.

One real conflict, worth fixing either way

APM's skill authoring guide says:

Imperative. Start with a verb that names the user action ("Use when", "Apply when"), not the skill ("This skill helps you…").
Intent-first. Lead with the user's intent, then the trigger conditions. Runtimes match on the first sentence.

Our descriptions currently open third-person — Aligns paired font families by measured x-height… — following the USE FOR: / DO NOT USE FOR: convention adopted from equinor/fusion-skills yesterday. That pulls against APM's rule, and our earlier phrasing (Use when defining, porting or reviewing…) matched it better.

A hybrid satisfies both, and is worth doing independently of the APM decision:

description: 'Use when two paired fonts look mismatched at the same nominal size.
USE FOR: extracting font metrics, deriving the correction factor, emitting it as a token.
DO NOT USE FOR: building the size ramp itself (use typography-scale).'

The actual blocker is not APM

Fusion installs from tagged releases:

apm install equinor/fusion-skills/apm/fusion-developer#v1.6.0 --target copilot

Package versions follow the repo release version, and dependency refs marked # release-managed are advanced to the release tag by a script at release-prep time.

equinor/skills has zero tags and zero releases. Adopting APM therefore means building a release process first. That is the work — the manifest is the easy part.

Two caveats before deciding

1. Fusion's manifests declare targets: [copilot] only. The cross-harness capability is real in APM, but it is not yet demonstrated in-house. A prototype here would be breaking new ground at Equinor rather than following a proven internal path — which is fine, but it is not the "align with an emerging house convention" framing the issue uses. What we would be aligning with is the tool, not yet the multi-target usage.
2. Unanswered, and the right question for the prototype: whether apm install equinor/skills/skills/<name> works standalone, or whether every consumer needs a wrapping package with an apm.yml. Fusion always wraps, so their setup does not answer it. If a bare skill path installs, adoption is nearly free for consumers; if not, we own a package-manifest surface too.

Recommendation: adopt, sequenced

1. Tag a first release once css-authoring: channel variables, modern CSS, verified support #13 and Add typography-scale and typography-x-height-alignment skills #14 are merged — needed for APM, and independently good for the npx skills add path.
2. Prototype with css-authoring (Create CSS authoring skill #12) as the issue proposes. Right choice: harness-agnostic prose, no scripts or assets to complicate a first attempt. Answer caveat 2 while doing it.
3. Apply the description hybrid above regardless of the outcome.
4. Record the decision in the README, per the issue's scope.

🤖 Generated with Claude Code