Resolution & pins

When you run pm-skills list or pull, the server returns the effective skill set for a project — one winner per skill name.

Precedence

project  >  organization  >  global (marketplace / installs)

If the same name exists at more than one tier, the higher-precedence tier shadows the others. list / status can surface shadow relationships so you know why an org skill is hidden.

Only active content

Draft and under-review versions never reach the CLI. Resolution serves the skill’s active version SHA (or an install pin — see below).

Install pins

A SkillInstall record pins a wider-tier skill (usually global) into a project or organization:

Field	Meaning
pinned_sha	Exact version served until updated
auto_update	If true, follow the source skill’s active version

Pins are created and updated in the UI (Install to project / install management). The CLI does not create installs on the server.

Local lockfile

pm-skills.lock.json records what was last pulled:

{
  "version": 1,
  "project_id": "…",
  "skills": {
    "secure-coding-policy": {
      "sha": "77c2d8a1f0e3",
      "tier": "organization",
      "skill_id": "…"
    }
  },
  "synced_at": "…"
}

• pull refreshes files + lockfile from current resolution (unless --frozen).
• pull --frozen installs exactly the lockfile SHAs and fails if the server differs (CI reproducibility).
• update advances local pins (and rewrites files) when a newer approved version exists — with a diff preview.

Drift states

pm-skills status compares lockfile, disk content hashes, and server resolution:

State	Meaning
in sync	Local matches pinned SHA
update available	Server resolution moved ahead
modified locally	On-disk content ≠ lockfile hash
removed on server	In lockfile, gone from resolution
new in resolution	On server, not yet in lockfile

See Pull, status, update and CI.