Appearance

Reproducibility and lockfiles ​

A configuration file says what you want, for example "the frontend-design skill from this repository's main branch". A branch changes every time someone pushes to it, so the same configuration could install different content on different days or on different machines. The lockfile fixes that. It records exactly which version the CLI used, and later syncs install that same version until someone runs a command to move it forward.

Why two files ​

  • .agents/config.yaml is the file you edit. It lists sources (registry URLs and folders), the ref to follow for each Git source, and which resources to take.
  • .agents/lock.yaml is generated by the CLI. It records the exact Git commit each ref pointed to, and fingerprints of the content found there.

A team commits both. Reviewers read the configuration to see what changed in intent, and the lock makes every teammate's sync, and every CI run, install the same bytes.

What the lock records ​

For each remote Git source, identified by its URL and ref, the lock contains:

  • The normalized URL of the repository.
  • The ref as written in the configuration, such as main or v1.2.0.
  • The exact commit that ref resolved to.
  • For each folder the CLI searched (the source's path, or the repository root) and its layout: a revision_digest, which is a SHA-256 fingerprint of everything found there.
  • For every resource found in that folder, whether or not a group selects it: its content_digest and archive_digest.

The lock covers every resource under the source, so adding a locator to a group's include usually leaves the lock unchanged. The CLI already has the commit and the fingerprints it needs.

Marketplace sources are recorded in the same file, in a separate marketplaces section, with the exact content revision and digests of each installed resource. The lockfiles reference describes the full format.

How sync uses the lock ​

A normal sync downloads the commit recorded in the lock, checks the downloaded files against the recorded fingerprints, and installs the selected resources. If the fingerprints do not match, it stops with an error instead of installing something different.

If the lock is missing, or no longer matches the configuration (for example after you add a source or change a ref), sync first updates the lock, changing only the records that need it. It does this only for lockfiles the CLI is allowed to write. Two stricter variants are available:

  • sync --locked refuses to write any configuration or lockfile and fails when a lock is out of date. Use it in CI. It also fails when a Marketplace serves a repaired archive for unchanged content, because refreshing the recorded archive_digest is a lock write; run a writing sync or update to pick up the new archive evidence.
  • sync --check changes nothing and exits with status 1 when a lock or the installed files are out of date.

One lock per configuration file ​

Each configuration file has its own lock next to it:

ConfigurationLockCommitted to Git?
/etc/agent-marketplace/config.yaml (organization)/etc/agent-marketplace/lock.yamlmanaged by your organization
~/.agents/config.yaml (user)~/.agents/lock.yamlno
.agents/config.yaml (repository).agents/lock.yamlyes
.agents/config.local.yaml (personal-local).agents/lock.local.yamlno

The organization lock is optional, and ordinary commands do not create it. Some organizations never distribute one. When it is absent, the organization's Git sources stay unpinned and follow their refs. When it is present, the CLI uses exactly what it records and refuses to run if it does not match.

What is not locked ​

A directory source is a folder on your disk. The CLI reads it fresh on every run, and it never appears in a lock. Two machines install the same thing from it only if their folders hold the same files.

Moving to newer versions ​

Nothing moves a lock forward on its own, not even a new push to the branch you follow. You do it explicitly:

  • agent-marketplace update looks up each ref again, records the commit it points to now, and syncs. With --bump it first rewrites eligible refs in v4 sources: to newer matching tags. A ref that an included config file declares is reported and left unchanged; edits stay owned by the selected writable root.
  • agent-marketplace lock --upgrade refreshes the locks to the current commits of their refs without syncing. You can limit it to one registry with --registry.

After either command, review the change to .agents/lock.yaml and commit it like any other change. How to keep resources reproducible walks through the workflow.