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

# Publish a skill

> From a local folder to a versioned @org/slug package — with the manifest always shown first.

## What a publishable folder looks like

Any folder with a `SKILL.md` at its root:

```text theme={"dark"}
skills/review-checklist/
├── SKILL.md              # frontmatter: name + description, then the instructions
├── references/
│   └── standards.md
└── templates/
    └── review-note.md
```

The `name` in the SKILL.md frontmatter becomes the default registry slug. Keep the `description` sharp — it's what tells agents *when* to load the skill.

## Through your agent

> **You:** publish the skill I wrote in ./skills/review-checklist to the team
> **Agent:** Package ready — needs your approval:
> **@acme/review-checklist** · visibility **private** · version **v3 → v4**
> 6 files, 34 KB · security scan: clean
> ⚠️ `config.local.json` found — **excluded from the package.**
> Publish it?
>
> **You:** yes
> **Agent:** Published `@acme/review-checklist` v4.

You can go further and have the agent *write* the skill first: "turn what we just did into a skill and publish it." It drafts the folder, shows you the content, and only then starts the publish flow.

Under the hood this is the two-phase flow — the agent never skips the approval step:

```bash theme={"dark"}
masterskills prepare ./skills/review-checklist --org acme --json   # manifest + draftId, uploads NOTHING
masterskills publish-draft <draftId>                               # uploads the approved draft
```

## From the CLI, one shot

For humans working directly, `publish` runs the same pipeline interactively — it shows the manifest and asks before uploading:

```bash theme={"dark"}
masterskills publish ./skills/review-checklist --org acme
```

Useful flags (full list: [`masterskills publish`](/cli/publish)):

| Flag            | Effect                                                                    |
| --------------- | ------------------------------------------------------------------------- |
| `--org <org>`   | Target namespace; defaults to your device's organization                  |
| `--slug <slug>` | Override the slug from SKILL.md frontmatter                               |
| `--public`      | Make the skill public — default is always private                         |
| `--group <kit>` | File the published skill into a kit, creating it if missing               |
| `-y, --yes`     | Skip the confirmation — for [CI](/guides/publish-from-ci), not for agents |

## What the scan does

Files that look like secrets (`.env`, keys, tokens, local config) are excluded client-side and **listed in the manifest** — never silently dropped. After upload, the server runs its own authoritative scan; findings reject the publish with a `422` before any version is created. Details: [Trust & approvals](/concepts/trust).

## Adopt-on-publish

If the folder you publish lives inside an agent's **global** skills directory (say `~/.claude/skills/review-checklist`), the CLI *adopts* it: the content moves into the MasterSkills store and a link takes its place. From then on it versions and updates like any registry skill. Skills inside project repos are never touched — the repo is already a distribution mechanism.

## Versioning

There is no version to bump by hand. First publish creates v1; each publish with changed content increments the integer version, computed from a content hash. The target version is always part of the manifest you approve.