Concepts
- Coordinates & scope
-
A published skill is addressed by a coordinate
@scope/name. The scope
is your username; it is stamped server-side from your identity, never typed — so you can
only ever publish under your own. Until you publish, a skill you author locally carries the
@local sentinel scope (a placeholder, not a guess at your real one); at
publish the server stamps @local → @you. On disk the scope disappears anyway:
a skill always materializes to a flat .claude/skills/<name>/.
- Offline-first &
@local -
Authoring never needs the registry.
skg init brings a skill under management with
the @local coordinate and records it in skillgraph.json;
skg dep wires edges; skg install reconciles the project from
local content, resolving @local skills straight from .claude/skills/
with no network call. @local skills are present-in-place — never re-downloaded
or pruned. Only publish (sharing) and installing someone else's
@scope/name reach the network. local is a reserved scope.
- Owned vs installed
- Installed skills are ones you consume (read-only). Owned skills are ones you
manage and can publish.
fork turns an installed skill into an owned copy under your
scope, recording its origin as lineage.
- The registry is the source of truth
-
Ownership, lineage, and content are server-authoritative. Your local files — the manifest, the
lock, the per-skill sidecar — are regenerable, non-authoritative state; editing them can't forge
ownership or inject content. Published versions are immutable.
- Manifest → lock → skills
-
skillgraph.json is intent (the skills you want, by version or latest);
skillgraph.lock.json is the resolved, pinned graph you got;
.claude/skills/ is the materialized content. A bare install reproduces
from the lock without re-resolving — npm's install vs ci, over a
flattened, single-version graph.