Consuming marketplace plugins

This repository publishes an apm marketplace named vanixiets, declared by the manifest at .github/plugin/marketplace.json. Its plugins package the agent skills maintained under modules/home/ai/plugins/, and any project can consume them with the apm CLI and deploy them to Claude Code, Codex, Cursor, OpenCode, and the other harnesses apm supports. Consuming the marketplace requires only apm and does not depend on Nix or on any other part of this repository’s infrastructure. The behavior described below was verified against apm 0.28.0, and the pinning details in particular are version-dependent.

Quick start

The first consumer on a new machine registers the marketplace, initializes the project, and installs a plugin group.

apm marketplace add cameronraysmith/vanixiets
apm marketplace browse vanixiets
apm init -y --target claude,codex
printf '%s\n' '.agents/skills/' '.claude/skills/' '.codex/skills/' >> .gitignore
apm install 'preferences-code-and-collaboration-conventions@vanixiets#main'
git add apm.yml apm.lock.yaml .gitignore && git commit

apm init -y --target claude,codex writes the target list into apm.yml non-interactively, so later installs need neither a -t flag nor harness auto-detection. A target is mandatory. With no harness marker directory in the project, no -t flag on the command, and no targets: field in apm.yml, apm install exits with an error rather than guessing.

The skill trees apm deploys into the harness directories are regenerated by apm install, so gitignore them instead of committing them. Gitignore patterns must start at column 0; an indented pattern silently fails to match. Ignore the skills subdirectories rather than the whole harness directories: apm integrates hooks from some dependencies into .claude/settings.json, and projects commonly carry their own committed harness configuration that ignoring .claude/ would exclude. The apm_modules/ staging directory needs no manual entry, since apm appends it to .gitignore itself on the first install.

Team and CI use

The dependency apm records in apm.yml is the portable form cameronraysmith/vanixiets/modules/home/ai/plugins/<group>#main, which names the source repository and path directly. The marketplace name is a discovery convenience for the machine that first adds a dependency, and it does not appear in the recorded dependency. Collaborators therefore clone the project and run bare apm install with no marketplace registered.

CI should run apm install --frozen, which refuses to proceed when apm.yml and apm.lock.yaml disagree.

Registering the marketplace is optional even for the first install, since the portable form works directly:

apm install 'cameronraysmith/vanixiets/modules/home/ai/plugins/<group>#main' -t claude

Pinning policy

Always append an explicit ref to a dependency, normally #main. An unpinned dependency line produces a persistent “dependency unpinned” warning, and under apm 0.28.0 it also triggers a lockfile defect in which apm update proposes the same no-op update on every subsequent run.

Do not pin with a 40-character commit SHA. apm update treats a full SHA as a revision pin and rewrites it to the repository’s newest annotated tag, which may reference a tree that predates the plugins directory and leave the install broken. If immutable pinning is required, hand-edit apm.yml to the SHA, refrain from running apm update, and re-materialize the install with apm install.

Staying current

apm outdated previews what would move. apm update -y bumps #main pins to the current upstream tip and converges to a no-op once nothing has changed.

Marketplace manifest resolution is cached for one hour. When a newly published plugin is not yet visible to apm marketplace browse, force a refresh with apm marketplace update vanixiets.

Transitive dependencies

A plugin group may declare its own remote apm dependencies, which are installed along with it. The preferences-code-and-collaboration-conventions group, for example, declares theclaymethod/unslop, a prose-editing skill. The lockfile records a hash for every deployed file, so its size grows with the total deployed payload rather than with the number of direct dependencies.

User-level installs

Adding -g installs into the user-level harness directories instead of the project.

apm install 'preferences-code-and-collaboration-conventions@vanixiets#main' -g -t claude

For the claude target this deploys to $CLAUDE_CONFIG_DIR when that variable is set and to ~/.claude/skills/ otherwise, and it keeps its own manifest and lockfile under ~/.apm/. Users whose home configuration is managed declaratively, for example with nix home-manager, should prefer project scope, because a global install writes into the managed tree.