Concepts overview

Skills Manager treats agent skills as governed, versioned packages — not loose files in git alone.

Three ideas

1. Tiers — A skill lives at project, organization, or global (marketplace) scope. Resolution prefers the nearest tier.
2. Versions — Content is content-addressed (sha). Only active versions are served to the CLI.
3. Sync — The console is the source of truth; pm-skills materializes the resolved set onto disk with provenance and a lockfile.

Mental model

Console (author / review / publish / install)
        │
        ▼
   Resolve API  (project ▸ org ▸ global + pins)
        │
        ▼
   pm-skills pull  →  .claude/skills/…  +  pm-skills.lock.json
        │
        ▼
   Coding agents / Agentkit AgentSkills plugin

Concept map

Topic	Page
Project / org / global	Hierarchy & tiers
SKILL.md shape	Skill anatomy
Effective set, shadowing, pins	Resolution & pins
Draft → review → active	Lifecycle
API keys and RBAC	Authentication
SkillSpector gates	Security scanning

Environments

Unlike Prompt Manager prompts, skill versions are not environment-gated today. An optional --env / environment value may be echoed into the lockfile for labeling, but resolution serves the active version only.