Skills HTTP API

The REST endpoints for skills. Most people reach these through the pm-skills CLI, which is the supported path — these pages are for building your own integration.

Reading skills

whoami, resolve, by-name, diff — find and fetch a skill.

→

Bundles

Download a whole skill directory as a zip.

→

Discovery

List skills across a project or an organisation.

→

Publishing

Make new content the active version.

→

INFO

Authentication, error codes and publishing flows are shared with the prompt API and documented once, under Prompt Manager → HTTP API. Everything there applies here.

Availability

Endpoint	SaaS	On-prem
GET /skills/whoami	✅	✅
GET /skills/resolve	✅	✅
GET /skills/by-name/{name}	✅	✅
GET /skills/diff	✅	✅
GET /skills/bundle/{skill_id}/{sha}	✅	✅
GET /skills/discover — marketplace search	✅	❌
GET /skills — list	❌	✅
POST /skills/active-version — publish	❌	✅

✅ available · ❌ not on this deployment

Listing and publishing are on-prem features; the read path is on both. Marketplace search is the one thing SaaS has and on-prem does not.

Two transports, and one exception

Every read endpoint accepts the key either way:

curl -s "$IM_URL/skills/resolve?project_id=$PID" -H "X-API-Key: $IM_KEY"
curl -s "$IM_URL/skills/resolve?project_id=$PID&api_key=$IM_KEY"

POST /skills/active-version reads the header only

The query parameter is not accepted on the publish endpoint, and using it returns 401 API key required — which looks like a rejected key rather than a misplaced one. This is the single most likely thing to catch you out when moving from reading to writing.

Two authorization rules

Endpoint	Authorises on
resolve, by-name, diff, GET /skills	membership of the project
bundle	read access to the skill
POST /skills/active-version	write scope + project membership + the approver tag on review_required

Project membership means being on the project, not merely in its organisation. Super Admins count as members of every project in their organisation, resolved per request rather than stored.

Where skills differ from prompts

The two APIs are deliberately parallel, so the differences are worth stating plainly:

• Skills are tiered — project → organization → global — and reads return the effective set after resolution. Prompts have one tier.
• Skills are not environment-gated. resolve accepts an environment and echoes it straight back. The identical-looking parameter on the prompt read endpoint filters, and can produce a 409.
• Skills carry a security scan. Prompts have no equivalent. It is skipped on API publishes by default — see Publishing.
• Skills have bundles. A skill is a directory, not a string, so there is a zip endpoint.

Next

Authentication

Keys, scopes, and the approver tag. Shared with prompts.

→

Publishing flows

What a publish does, and the AI review handshake.

→

Errors

Every code, and what is safe to retry.

→