Skills

Manage and access skills via REST.

Skills are indexed in the skills search collection. Discover public skills via GET /suggest or filter with GET /search?collection=skills. Browse approved registry listings with GET /store/skills — see Store API.

List responses use cursor pagination. See REST overview — response format.

Write endpoints (create, update, delete, supersede, transfer, visibility, sharing, GitHub import) require the knowledge:write scope, as do general knowledge entries (observations, references, preferences). See Knowledge API.

→ Store API · Search concept · Search API · Skill registry

List Skills

GET /skills or POST /skills/list

Returns skills with cursor-based pagination.

Query Parameters

Response

Responses may include RFC 8288 Link headers (rel="next", rel="prev") with the same cursors.

Example:

1{2  "items": [3    {4      "id": "skill_abc123",5      "namespace": "myteam",6      "name": "code-review",7      "description": "Guidelines for reviewing pull requests",8      "version_id": "ver_xyz789",9      "version": {10        "id": "ver_xyz789",11        "instructions": { "path": "SKILL.md", "uri": "https://..." },12        "files": [{ "path": "references/checklist.md", "uri": "https://..." }],13        "content_hash": "a3f5c9e2b1d4...",14        "tags": ["development"],15        "license": "MIT"16      },17      "visibility": "public",18      "created_at": "2026-01-15T10:30:00Z"19    }20  ],21  "next_cursor": "abc123",22  "has_next": true,23  "has_previous": false,24  "items_per_page": 5025}

The paginated object is returned under data. See REST overview — response format.

Get Skill

GET /skills/{id}

Returns a single skill by ID.

Version content_hash

Each version includes content_hash — a hash over the SKILL.md instructions and supporting files. Use it to detect when a skill changed without comparing full content.

GET /knowledge/{namespace}/{name} and related knowledge ref routes set ETag from this hash and support If-None-Match (304 Not Modified). See Knowledge API — Content hash and conditional GET.

Get References

GET /skills/{id}/references

Returns the same ReferencesResponse as Get References on knowledge entries — outgoing and incoming content reference edges for the skill. Requires read access to the skill.

1curl https://api.inference.sh/skills/skill_abc123/references \2  -H "Authorization: Bearer inf_your_key"

Content reference edges use graph edge type references (namespace/name mentions in markdown). See Get References for the response shape.

Get Lineage

GET /skills/{id}/lineage

Returns the same SkillLineageResponse as Get Lineage on knowledge entries — parents, siblings, forks, duplicates, and fork_depth.

1curl https://api.inference.sh/skills/skill_abc123/lineage \2  -H "Authorization: Bearer inf_your_key"

Get Skill by Ref

GET /skills/{namespace}/{name}

Returns a skill by namespace and name.

1curl https://api.inference.sh/skills/myteam/code-review \2  -H "Authorization: Bearer inf_your_key"

Get Skill Content

GET /skills/{namespace}/{name}/content

Returns the raw SKILL.md content as text/markdown.

1curl https://api.inference.sh/skills/myteam/code-review/content

No authentication required for public skills.

Get Skill File

GET /skills/{namespace}/{name}/files/{path}

Returns a supporting file (redirects to CDN).

1curl -L https://api.inference.sh/skills/myteam/code-review/files/references/checklist.md

Resolve Skill

GET /skills/resolve?ref={ref}

Resolves a skill from the registry or GitHub. The API looks up ref in your team's store first; if nothing matches, it fetches from GitHub.

GitHub fallback and team copies

When the skill is fetched from GitHub:

Use the team copy's ref (myteam/anthropics-frontend-design) for later GET /skills/{namespace}/{name}/content calls and agent URLs.

Response

1{2  "source": "store",3  "namespace": "myteam",4  "name": "anthropics-frontend-design",5  "content": "# Frontend Design\n...",6  "files": [{ "path": "references/checklist.md", "uri": "https://..." }]7}

GitHub auto-refresh (legacy registry copies)

When a legacy system-owned registry skill is already in the store and linked to GitHub (repo_url or version source_url contains github.com), resolve checks whether the current version is older than 24 hours. If it is stale:

1. The API returns the cached store content immediately (this request is not blocked).
2. A background re-import from GitHub runs in the background (concurrent requests for the same skill are deduped).
3. If upstream content changed, a new version is published; identical content is skipped (no duplicate version).
4. The next resolve returns the updated content.

Team-owned copies (skills you imported or resolved into your workspace) do not refresh in the background. Pull upstream changes by calling resolve again (with knowledge:write) or re-running Import from GitHub.

CLI: belt skill use <ref> calls this endpoint (including GitHub refs like github.com/org/repo or org/repo:skill-name). When logged in with a key that can write knowledge, GitHub resolves create or update the team copy described above.

Note: GET /skills/{namespace}/{name}/content always serves the latest stored version but does not fetch from GitHub. Use resolve (or belt skill use) when you want upstream changes pulled into your team's copy.

Create Skill

POST /skills

Requires knowledge:write scope. Creates a new skill or new version of an existing skill.

Each version stores only the files in the request — supplementary files from an earlier version are not carried forward unless you include them again. The REST API accepts whatever you send; belt skill upload and skill uploads via belt know upload refuse partial uploads that would drop existing supplementary files unless you pass --prune.

Accepts application/json (web UI) or multipart/form-data (belt skill upload). Multipart fields mirror the JSON body; upload files as files with relative paths as filenames (for example SKILL.md, references/checklist.md).

Request

1{2  "namespace": "belt-sh",3  "name": "code-review",4  "description": "Guidelines for reviewing pull requests",5  "instructions": "# Code Review Guidelines\n\nWhen reviewing...",6  "files": [7    { "path": "references/checklist.md", "content": "## Checklist\n..." }8  ],9  "license": "MIT",10  "allowed_tools": "Read Grep",11  "compatibility": "Claude Code",12  "repo_url": "https://github.com/myteam/skills"13}

Multipart form fields: namespace, name, description, license, allowed_tools, compatibility, disable_model_invocation, user_invocable, context, plus files uploads. The CLI reads namespace from SKILL.md frontmatter when present.

Response

Returns the created SkillDTO.

Update Skill

POST /skills/{id}

Creates a new version of an existing skill. Same request body as create.

Delete Skill

DELETE /skills/{id}

Soft-deletes a skill. The entry is removed from the skills search collection, so it no longer appears in /suggest or other discovery results.

Requires knowledge:write scope.

CLI: belt skill delete <id or namespace/name> — resolves refs, then deletes via the knowledge delete API (same behavior as removing a skill-type entry with belt know delete). Destructive: prompts unless --yes / -y. To point users at a replacement instead of removing the old skill, use Supersede Skill (belt skill supersede).

Supersede Skill

POST /skills/{id}/supersede

Mark an older skill as replaced by the skill at {id}. Creates a graph edge of type supersedes from the replacement skill to the outdated one. The superseded skill is excluded from suggest and other discovery results; the replacement skill is unchanged.

Requires knowledge:write scope.

1{2  "superseded_id": "skill_old123"3}

1curl -X POST https://api.inference.sh/skills/skill_new456/supersede \2  -H "Authorization: Bearer inf_your_key" \3  -H "Content-Type: application/json" \4  -d '{"superseded_id": "skill_old123"}'

Response:

1{"status": "ok"}

Use this when you publish a replacement under a new name instead of versioning in place. The CLI equivalent is belt skill supersede <old> <new> — see Skills (CLI). Python SDK: GraphEdgeType.SUPERSEDES in inferencesh.types matches the edge type string.

Import from GitHub

GitHub import endpoints require knowledge:write and a signed-in workspace. Each imported skill is stored in your team's namespace with name <github-owner>-<skill> (same rules as resolve). Re-importing the same skill adds a version when content changed.

Query parameter: keep_namespace

Append ?keep_namespace=true to discover, batch import, or streaming import to store skills under the GitHub owner's namespace with the upstream skill name (legacy curated layout). Platform admins only. Everyone else, including workspace API keys, gets 403 forbidden (keep_namespace is for admins). GitHub resolve does not accept this parameter; it always imports into your team namespace unless you use the import endpoints below.

Discover Skills

POST /skills/import/github/discover

Scan a GitHub repository for SKILL.md files.

1{2  "url": "https://github.com/anthropics/skills"3}

Response

namespace is your team username. Each skills[].name is the target name after applying the <owner>-<skill> prefix.

1{2  "namespace": "myteam",3  "repo_url": "https://github.com/anthropics/skills",4  "skills": [5    {6      "path": "frontend-design",7      "name": "anthropics-frontend-design",8      "description": "Guidelines for frontend design",9      "file_count": 3,10      "exists": false11    }12  ]13}

Import Skills

POST /skills/import/github

Import discovered skills from a GitHub repository. Requires knowledge:write scope.

Request body:

1{2  "url": "https://github.com/anthropics/skills",3  "paths": ["frontend-design", "api-docs"]4}

Response:

1{2  "results": [3    {4      "path": "frontend-design",5      "name": "anthropics-frontend-design",6      "namespace": "myteam",7      "skill_id": "skill_abc123",8      "version_id": "ver_xyz789",9      "created": true,10      "index": 1,11      "total": 212    },13    {14      "path": "api-docs",15      "name": "anthropics-api-docs",16      "namespace": "myteam",17      "error": "SKILL.md not found",18      "index": 2,19      "total": 220    }21  ]22}

Errors: 403 (keep_namespace without admin, or missing team/write scope), 404 (repository or path not found), 429 (GitHub API rate limit), 400 (invalid request).

Import Skills (streaming)

POST /skills/import/github/stream

Same request body and scope as the batch import. Instead of waiting for the full batch, the API streams one JSON object per line (NDJSON) as each skill finishes importing.

Response: Content-Type: application/x-ndjson

Each line is a SkillGitHubImportEntry with the same fields as a single item in the batch results array above.

1{"path":"code-review","name":"code-review","namespace":"myteam","skill_id":"skill_abc123","version_id":"ver_xyz789","created":true,"index":1,"total":2}2{"path":"api-docs","name":"api-docs","namespace":"myteam","skill_id":"skill_def456","version_id":"ver_ghi789","created":true,"index":2,"total":2}

Use the streaming endpoint when importing many skills from CI pipelines or when building a UI with per-skill progress bars. For small batches, the non-streaming import is simpler.

Example (process each line as it arrives):

1curl -N -X POST https://api.inference.sh/skills/import/github/stream \2  -H "Authorization: Bearer inf_your_key" \3  -H "Content-Type: application/json" \4  -d '{"url": "https://github.com/myteam/skills-repo"}' \5  | while IFS= read -r line; do echo "$line" | jq .; done

Imported skills keep their GitHub repo_url. To pull upstream changes into your team's copy, call resolve again or re-run import — team copies are not updated by the legacy 24-hour background refresh. Only legacy system-owned registry skills use that background re-import.

Visibility

POST /skills/{id}/visibility

1{2  "visibility": "public"3}

Sharing

A skill is a knowledge entry, so it is shared through the knowledge routes with the skill's id: GET /knowledge/{id}/shares, POST /knowledge/{id}/share, DELETE /knowledge/{id}/share/{userId}, DELETE /knowledge/{id}/team-share, DELETE /knowledge/{id}/org-share. A read share shows the skill and opens its content and files, including loading it into an agent. use is the same as read; write also allows editing it and managing its shares. → Visibility and sharing

JavaScript SDK

1import { inference } from '@inferencesh/sdk';23const client = inference({ apiKey: 'inf_your_key' });45const { items } = await client.skills.list({ limit: 50 });6const skill = await client.skills.getByName('myteam', 'code-review');7const content = await client.skills.getContent('myteam', 'code-review');89await client.skills.create({10  name: 'my-skill',11  description: 'My custom skill',12  instructions: '# Instructions\n\nDo the thing.',13});1415const { items: storeSkills } = await client.skills.listStore({ limit: 20 });

→ JavaScript SDK · SDK overview

cURL Examples

1# List public skills2curl https://api.inference.sh/skills34# Get skill content5curl https://api.inference.sh/skills/myteam/code-review/content67# Create a skill8curl -X POST https://api.inference.sh/skills \9  -H "Authorization: Bearer inf_your_key" \10  -H "Content-Type: application/json" \11  -d '{12    "name": "my-skill",13    "description": "My custom skill",14    "instructions": "# Instructions\n\nDo the thing."15  }'1617# Import from GitHub (batch)18curl -X POST https://api.inference.sh/skills/import/github \19  -H "Authorization: Bearer inf_your_key" \20  -H "Content-Type: application/json" \21  -d '{"url": "https://github.com/myteam/skills-repo"}'2223# Import from GitHub (streaming NDJSON)24curl -N -X POST https://api.inference.sh/skills/import/github/stream \25  -H "Authorization: Bearer inf_your_key" \26  -H "Content-Type: application/json" \27  -d '{"url": "https://github.com/myteam/skills-repo", "paths": ["code-review"]}'