> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masterskills.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How it works

> The registry, the central store, and the links that keep every agent in sync.

## The moving parts

```mermaid theme={"dark"}
flowchart LR
    subgraph machine["Your machine"]
        agent["Coding agent<br/>(Claude Code, Codex, …)"]
        cli["masterskills CLI"]
        store["Central store<br/>~/.masterskills/skills"]
        dirs["Agent skill dirs<br/>(links into the store)"]
    end
    registry["Registry<br/>masterskills.dev"]

    agent -- "runs commands" --> cli
    cli -- "device token" --> registry
    cli --> store
    store -- "linked" --> dirs
    dirs --> agent
```

**The registry** at masterskills.dev holds your organizations, skills, kits, devices, and audit log. The CLI talks to it over an [HTTP API](/api/overview) using a per-device token.

**The central store** on each machine is `~/.masterskills/skills/<org>/<slug>` — the only real copy of every installed skill. Agent skill directories get links into the store (flattened to `org--slug`), so one download serves every agent, and updating the store updates all agents at once. Agents whose directories can't hold links fall back to copies that are refreshed on every update.

**The MasterSkills skill** is how agents drive the product. `masterskills install` distributes it into every detected agent; it teaches the agent which CLI commands to run for searching, installing, updating, and publishing — and the approval rules it must follow. There are no CLI commands for you to memorize and no dashboard to learn.

## What each step actually does

### `masterskills install`

Detects the coding agents present on the machine (by their config directories), writes the bundled MasterSkills skill into the central store, and links it into each agent's skills directory. Agents that share the universal `~/.agents/skills` convention are linked once. Re-run it any time — for example after installing a new agent.

### `masterskills login`

Runs a device-authorization flow: the CLI requests a code, opens `masterskills.dev/device` in your browser, and polls while you confirm. On approval the device receives a **lifetime token** bound to this machine and your chosen organization. The token can be revoked from the [panel](/panel/devices) at any time.

### Everything after

Your agent runs CLI commands like `masterskills search --json` and `masterskills add @acme/api-conventions` on your behalf, and confirms with you before anything is written or published:

* **Search / list** — the catalog spans every organization you belong to, merged with local install state.
* **Install** — downloads the skill package, verifies its content hash, writes it to the store, links it into every detected agent. Only after you approve.
* **Update** — compares local state with the registry: version bumps, org-required skills you're missing, skills the org removed. You choose what to apply.
* **Publish** — two-phase: `prepare` builds a manifest (files, sizes, target version, auto-excluded secret files) without uploading anything; `publish-draft` uploads only after you approve that exact manifest. See [Trust & approvals](/concepts/trust).

## Versioning

Versions are integers that increment automatically. Each version records a content hash; publishing identical content doesn't create noise, and the CLI verifies the hash of every download before writing a single file. The version bump is always shown before you approve a publish.

## Open source and hosted

The CLI — including the agent skill it distributes — is MIT-licensed and public at [masterskills-dev/masterskills](https://github.com/masterskills-dev/masterskills). The registry is a hosted service; Enterprise plans can self-host it.