# Creating Skills

> Create skills directly on inference shell — no CLI or local tooling required.

**URL:** https://inference.sh/docs/skills/creating
**Last updated:** 2026-10-30

---

Create skills directly on inference shell — no CLI or local tooling required.

---

## The Web Editor

Go to [My Skills](https://inference.sh/my/skills) and click **Create Skill**.

The editor has four sections:

### Info

| Field | What it does |
|-------|--------------|
| **Name** | Unique identifier (kebab-case, e.g. `code-review`). Immutable after creation |
| **Description** | What this skill does and when to use it. The agent sees this to decide whether to load the skill — make it specific |
| **Category** | Optional grouping for the registry (e.g. "development", "writing") |
| **Repo URL** | Link to source repo if the skill lives elsewhere too |

### Instructions

The core content agents load when they call `skill_get`. Write this in markdown — it can include:

- Step-by-step instructions
- Rules and guidelines
- Reference information
- Examples and templates
- Links to supporting files (e.g. `[see API reference](references/api-docs.md)`)

This is the body of the `SKILL.md` file in the [Agent Skills standard](https://agentskills.io).

### Files

Supporting files organized by purpose:

| Prefix | What goes here |
|--------|---------------|
| `references/` | Domain docs, API specs, technical references |
| `scripts/` | Executables the agent can run (`.py`, `.sh`, `.js`) |
| `examples/` | Example outputs showing expected format |
| `templates/` | Templates for the agent to fill in |
| `assets/` | Images, data files, other resources |

Agents load these on demand via `skill_get("my-skill", "references/api-docs.md")`. Keep large reference material here instead of inlining it in the instructions — only what's needed gets loaded.

### Metadata

| Field | What it does |
|-------|--------------|
| **License** | License name or reference (e.g. MIT, Apache-2.0) |
| **Allowed tools** | Space-separated list of pre-approved tools (e.g. `Bash(git:*) Read Write`). Experimental |
| **Compatibility** | Environment requirements — intended product, system packages, network access |

---

## The SKILL.md Format

Under the hood, the editor produces a spec-compliant `SKILL.md` file. If you're curious what that looks like:

```yaml
---
name: code-review
description: Guidelines for reviewing pull requests, including security, performance, and style checks.
license: MIT
compatibility: Designed for Claude Code (or similar products)
allowed-tools: Read Grep
---

# Code Review Guidelines

When reviewing a pull request, check for:

1. Security vulnerabilities (injection, XSS, auth bypass)
2. Performance issues (N+1 queries, unnecessary allocations)
3. Code style consistency with the existing codebase

[see full checklist](references/checklist.md)
```

### Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | yes | Lowercase alphanumeric and hyphens, max 64 characters |
| `description` | yes | What the skill does and when to use it — agents see this to decide whether to load it |
| `namespace` | no | Target namespace for CLI/API publish (admin accounts only; regular users publish under their workspace username) |
| `license` | no | License name or reference to a bundled license file (e.g. `MIT`, `Apache-2.0`) |
| `compatibility` | no | Environment requirements — intended product, system packages, network access |
| `metadata` | no | Arbitrary key-value pairs for custom data |
| `allowed-tools` | no | Space-separated list of pre-approved tools the skill may use (experimental) |

The markdown body after `---` is what gets loaded as instructions. You never need to write this by hand — the web editor assembles it from your form fields.

For full spec details, see [agentskills.io](https://agentskills.io).

---

## Versioning

Every time you save changes, a new version is created. The skill's URL always serves the latest version — agents automatically get updates without reconfiguration.

Previous versions are listed in the **Versions** section of the editor for reference, or from the CLI with `belt skill versions <namespace>/<name>` (requires `belt login`).

---

## Visibility

| Setting | Who can see it |
|---------|---------------|
| **Private** | Only you |
| **Team** | Everyone in your workspace |
| **Org** | Every workspace in your organization |
| **Unlisted** | Anyone with the link |
| **Public** | Anyone — listed in the [skill registry](/skills) |

Set visibility in the editor's **Visibility** section or from your [skills list](/my/skills).

To give one person, another workspace of your organization, or the whole organization access without changing visibility, share the skill. A `read` share lets them open it and load it into an agent; a `write` share also lets them edit it. See [Visibility and sharing](/docs/api/rest/overview#visibility-and-sharing).

---

## Bulk import from GitHub

Import an entire skills repository in one request — useful when skills already live in GitHub with the [Agent Skills](https://agentskills.io) layout (`SKILL.md` per directory).

1. **Discover** skill directories: `POST /skills/import/github/discover`
2. **Import** selected paths: `POST /skills/import/github` (batch JSON response)
3. For large repos or CI pipelines, use **`POST /skills/import/github/stream`** — returns NDJSON with one result per line as each skill completes

See [Skills API — Import from GitHub](/docs/api/rest/skills#import-from-github) for request fields, response shapes, and curl examples.

Imported skills stay linked to their GitHub source and live in your workspace under names like `anthropics-frontend-design` (GitHub owner + skill name). To pull upstream changes, run `belt skill use` on the GitHub ref again or re-run import — your team's copy updates when content changed. Legacy system-owned registry skills still use automatic 24-hour background refresh; team copies do not.

---

## From the CLI

Publish or update a skill from a local directory that contains `SKILL.md`:

```bash
belt skill upload ./my-skill/
```

The skill name comes from the `name` field in frontmatter (or the directory name). Uploading again under the same name creates a new version; identical content is skipped.

Each published version stores **exactly** the files you upload in that request — not a merge with the previous version. If the current version has supplementary files under `references/`, `scripts/`, or `examples/`, upload the skill **directory** so those paths are included. Uploading only `SKILL.md` (or a folder missing some files) would drop the rest unless you mean to remove them.

`belt skill upload` and `belt know upload` (for skills) compare your upload against the current version before publishing. If any existing supplementary files would be left out, the command fails and lists the paths. Changed files replace the old copy automatically; you do not need a flag for updates. Pass `--prune` when you intentionally removed or renamed files and want the new version published without them. First-time uploads are not checked.

**Namespace:** By default, skills publish under your workspace's username (for example `yourteam/code-review`). Admin accounts can set `namespace` in `SKILL.md` frontmatter (or in a root `knowledge.yml`) to publish to a managed namespace such as `belt-sh/` without switching workspaces:

```yaml
---
name: code-review
namespace: belt-sh
description: Guidelines for reviewing pull requests.
---
```

For non-skill knowledge (observations, references, concepts), use `belt know upload` instead — it reads `namespace` from frontmatter or `knowledge.yml` the same way. See [CLI setup — Knowledge](/docs/extend/cli-setup#knowledge-cli).

For time-sensitive observations that may go stale, set `"lifecycle": "decay"` when creating via the [Knowledge API](/docs/api/rest/knowledge#create-knowledge) — see [Lifecycle](/docs/api/rest/knowledge#lifecycle).

---

## Tips

**Write good descriptions.** The description is what the agent sees in the tool listing. A vague "docs" tells the agent nothing. "API documentation for the payment service, including endpoints, authentication, and error codes" gives the agent enough to decide when to load it.

**Keep skills focused.** One skill per topic. Instead of one massive "everything" skill, split into `code-review`, `security-checklist`, and `api-reference`. The agent loads only what it needs.

**Use supporting files for bulk.** Put large reference docs, API specs, and detailed examples in `references/` or `examples/`. The main instructions should be a concise guide that references these files when the agent needs detail.

**Link between files.** In your instructions, use relative paths like `[see reference](references/api-docs.md)`. The agent can load these via `skill_get` — same paths work on the filesystem for local agents.