Create skills directly on inference shell — no CLI or local tooling required.
The Web Editor
Go to 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.
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:
1---2name: code-review3description: Guidelines for reviewing pull requests, including security, performance, and style checks.4license: MIT5compatibility: Designed for Claude Code (or similar products)6allowed-tools: Read Grep7---89# Code Review Guidelines1011When reviewing a pull request, check for:12131. Security vulnerabilities (injection, XSS, auth bypass)142. Performance issues (N+1 queries, unnecessary allocations)153. Code style consistency with the existing codebase1617[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.
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 |
Set visibility in the editor's Visibility section or from your skills list.
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.
Bulk import from GitHub
Import an entire skills repository in one request — useful when skills already live in GitHub with the Agent Skills layout (SKILL.md per directory).
- Discover skill directories:
POST /skills/import/github/discover - Import selected paths:
POST /skills/import/github(batch JSON response) - 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 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:
1belt 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:
1---2name: code-review3namespace: belt-sh4description: Guidelines for reviewing pull requests.5---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.
For time-sensitive observations that may go stale, set "lifecycle": "decay" when creating via the Knowledge API — see 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.