> ## 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.

# Skills

> Named, versioned instruction packages your agents load — @org/slug, private by default.

An **Agent Skill** is a folder with a `SKILL.md` at its root — instructions an AI coding agent loads on demand — plus any supporting files (`references/*.md`, templates, scripts). MasterSkills doesn't change the format; it gives skills a home, a name, versions, and permissions.

## Naming

Every registry skill is **`@org/slug`** — npm-style, where `org` is your organization's namespace:

```text theme={"dark"}
@acme/api-conventions
@acme/booking-flow-rules
@acme/review-checklist
```

Slugs are lowercase letters, digits, and dashes. The slug defaults to the `name` in the skill's `SKILL.md` frontmatter when publishing. [Kits](/concepts/kits) share the same namespace, so a single `masterskills add @acme/<slug>` resolves either.

## Visibility

| Visibility          | Who can install it                                                                           |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `private` (default) | Members of the organization only                                                             |
| `public`            | Any signed-in device, by full `@org/slug` name — the catalog listing itself stays org-scoped |

Publishing defaults to private, always. Making a skill public is an explicit flag.

## Versions

Versions are **integers that bump automatically** when the content changes — there is no version field to maintain. Every version records:

* a `sha256` **content hash** — the CLI verifies it on every download before writing anything to disk
* size and file count
* creation time, and a `yankedAt` timestamp if an admin yanks the version in the panel

The upcoming version number is always shown in the publish manifest before you approve it.

## Required skills

Admins can mark a skill **required** for the organization. Required skills show up in everyone's [update check](/guides/keep-skills-updated) as missing — but they are **never installed silently**. The agent lists them and asks; the user confirms. This is one of the product's [trust rules](/concepts/trust).

## Lifecycle

* **Publish** — creates the skill on first publish, adds a version on every subsequent one. See [Publish a skill](/guides/publish-a-skill).
* **Archive** (`unpublish`) — retires the skill org-wide. Devices that still have it installed learn on their next [sync](/cli/sync) and are offered the removal; nothing is deleted from anyone's disk without approval.
* **Yank a version** — panel-only; marks one version as not-installable while leaving the skill live.

## Where skills live on disk

Installed skills have exactly one real copy per machine, in the central store:

```text theme={"dark"}
~/.masterskills/skills/<org>/<slug>/
```

Agent skill directories receive links into the store, flattened to `org--slug` (for example `~/.claude/skills/acme--api-conventions`). One download serves every agent; one update refreshes them all. Skills that live inside a project repo are left alone — the repo is already a distribution mechanism.