Skip to content
Signalcraft
日本語

← Back to Signalcraft

Managing AI Skills Reproducibly Across Machines

Managing AI Skills Reproducibly Across Machines

Trying one AI-agent Skill can be as simple as installing it from GitHub. As soon as more machines and agents are involved, the important questions become which Skill, which commit, and which installation scope produced the current setup.

I separated the Skill itself, the installer, the project manifest, and the lockfile that records the resolved state. The main conclusion is to keep experimentation and reproducible dependency management as different workflows.

Decide what must be fixed

Object Responsibility What to check when machines multiply
Skill SKILL.md and related assets Source location and publication scope
Installer Expands files into an agent directory Project versus global scope
Manifest Declares required dependencies Which Skills are standard
Lockfile Records commits, hashes, and resolution Whether the state can be reproduced

Editing an installed directory does not communicate intent to another machine. A manifest without a pinned commit or installation destination cannot reproduce the same arrangement either.

Use npx skills to discover and try

The Vercel Labs Skills CLI is a convenient entry point for finding Skills and adding them to a project or user environment.

npx skills add vercel-labs/agent-skills \
  --skill frontend-design \
  --agent codex

To inspect a Skill without making a permanent project decision, use skills use:

npx skills use vercel-labs/agent-skills \
  --skill frontend-design \
  --agent codex

Check the help for the installed CLI before using --global or selecting additional agents. This is a discovery and trial path; it is not automatically the same as a team dependency lock.

Use gh skill for an individual GitHub Skill

The GitHub CLI gh skill install command is suited to installing a selected Skill from a GitHub repository into a chosen agent scope.

gh skill install github/awesome-copilot \
  documentation-writer \
  --agent codex \
  --scope project \
  --pin v1.2.0

Treat the installed version of gh and its gh skill install --help output as the authority for the supported agent, scope, and pin formats. This is clear for one explicitly pinned Skill, but it is not a resolver for a project-wide set of Skills, MCP servers, and agent configuration.

Use APM for project dependencies

APM is an Agent Package Manager for Skills, instructions, prompts, agents, hooks, plugins, and MCP servers. Declare dependencies in apm.yml and record resolved commits and hashes in apm.lock.yaml.

project/
├── apm.yml
├── apm.lock.yaml
├── apm_modules/        # APM-generated working directory
└── .agents/            # Agent-facing expansion directory

On another machine or in CI, expand the recorded state:

apm install --frozen --target codex

--frozen is the important boundary: it detects a manifest/lock mismatch instead of silently resolving a new state. Regenerate the lockfile only as an intentional update and review its commit, hash, and destination changes.

apm lock
git diff -- apm.lock.yaml

Whether apm_modules/ or an expanded .agents/ directory is committed depends on the APM and custom-Skill layout. If custom Skills live in the same general area, distinguish generated output from source files explicitly.

Use the three tools at different stages

Goal First tool to use Source of truth to keep
Try a candidate once npx skills use Usually nothing pinned
Install one GitHub Skill gh skill install A pinned reference or project setting
Reproduce a setup in machines and CI APM apm.yml and apm.lock.yaml
Manage Skills, MCP, and prompts together APM Manifest and lockfile
Share a custom Skill Source repository or chosen package manager Git history of the source

Managing the same Skill through both npx skills and APM creates two update paths. Choose one source and one update mechanism for a team standard; keep personal experiments separate.

Verify reproducibility in CI

If APM is a project dependency, use a clean CI environment to verify that the lockfile expands successfully.

apm install --frozen --target codex
apm audit --ci

Check the installed APM for the exact audit subcommand and options. The important test is not merely that files exist in the destination; it is that the same lockfile can produce the same inputs in a clean environment.

A reviewable update flow is:

  1. Add or change a dependency in apm.yml.
  2. Run apm lock to update the resolution.
  3. Inspect commits and hashes in apm.lock.yaml.
  4. Expand it in a clean environment with apm install --frozen.
  5. Run the audit and a minimal agent behavior check.
  6. Review the manifest and lockfile together.

Scope of the recommendation

For a short personal trial, npx skills use is enough. For one pinned GitHub Skill, gh skill is easy to understand. For a project that needs the same Skills, CI state, and other agent assets across machines, a manifest and lockfile such as APM are a better fit.

APM does not guarantee the quality or safety of a Skill. Review the dependency contents, update diff, permissions, and generated files. Pinning Skills like software dependencies makes the boundaries for installation, update, audit, and recovery easier to see.

References