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 and detail responses use cursor pagination or bare DTOs when you send X-API-Version: 2 (recommended). See REST overview — API version.

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

List Skills

GET /skills or POST /skills/list

Returns skills with cursor-based pagination.

Query Parameters

Field	Type	Description
`cursor`	string	Pagination cursor
`limit`	integer	Max results (default 50, max 100)

Response

Field	Type	Description
`items`	array	Skill objects
`next_cursor`	string	Cursor for the next page
`prev_cursor`	string	Cursor for the previous page
`has_next`	boolean	More results available
`has_previous`	boolean	Previous page available
`items_per_page`	number	Items returned in this page
`total_items`	number	Total matching skills

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

Example:

json

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        "tags": ["development"],14        "license": "MIT"15      },16      "visibility": "public",17      "created_at": "2026-01-15T10:30:00Z"18    }19  ],20  "next_cursor": "abc123",21  "has_next": true,22  "has_previous": false,23  "items_per_page": 50,24  "total_items": 12025}

Send X-API-Version: 2 for this bare JSON shape. Official SDKs and belt send the header automatically. Without it, the paginated object is wrapped: { "success": true, "data": { "items": [...], "next_cursor": "...", ... } }.

Get Skill

GET /skills/{id}

Returns a single skill by ID.

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.

bash

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

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.

bash

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.

bash

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.

bash

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

bash

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. Falls back to GitHub if not found in the store.

Parameter	Description
`ref`	Skill reference (e.g. `myteam/code-review`)
`skill`	Optional skill name within a repo

Response

json

1{2  "source": "store",3  "namespace": "myteam",4  "name": "code-review",5  "content": "# Code Review Guidelines\n...",6  "files": [{ "path": "references/checklist.md", "uri": "https://..." }]7}

Create Skill

POST /skills

Requires authentication. Creates a new skill or new version of an existing skill.

Request

json

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

Field	Required	Description
`name`	yes	Kebab-case, immutable after creation
`description`	yes	What the skill does
`instructions`	yes	Markdown content (SKILL.md body)
`files`	no	Supporting files with path and content
`license`	no	License identifier (MIT, Apache-2.0)
`allowed_tools`	no	Space-separated pre-approved tools
`compatibility`	no	Environment requirements
`repo_url`	no	Source repository URL

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.

Import from GitHub

Discover Skills

POST /skills/import/github/discover

Scan a GitHub repository for SKILL.md files.

json

1{2  "url": "https://github.com/myteam/skills-repo"3}

Response

json

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

Import Skills

POST /skills/import/github

Import discovered skills from a GitHub repository.

json

1{2  "url": "https://github.com/myteam/skills-repo",3  "paths": ["code-review", "api-docs"]4}

Visibility

POST /skills/{id}/visibility

json

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

Value	Description
`public`	Listed in the skill registry
`private`	Only visible to your team

cURL Examples

bash

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 GitHub18curl -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"}'