API Reference

API: Skills

REST endpoints for installing, browsing, syncing, and attaching skills (skill_md, openapi_action, mcp_registry) to agents and runners.

Skills are reusable bundles installed at the org level and attached to any agent or runner. Three sources are supported:

Source	Provides	Effect
`skill_md`	The body of a `SKILL.md` from a GitHub repo	Appended to the agent's system prompt
`openapi_action`	An OpenAPI 3.x spec	Each operation becomes a callable REST tool
`mcp_registry`	A remote MCP server pulled from the registry	Tools loaded over HTTP/SSE at runtime

When a skill is attached and enabled, its content is composed into the agent's system prompt and tool list at the next message — no restart needed.

All endpoints accept Authorization: Bearer fj_live_.... See Authentication.

Browse the marketplace

GET /api/skills/browse?q=<query>&source=<source>&limit=<n>&cursor=<cursor>

Returns a unified catalog across all sources. Already-installed entries carry an installedId.

{
  "skills": [
    {
      "key": "skill_md:anthropics/skills/superpowers/git",
      "name": "Git Superpowers",
      "description": "...",
      "source": "skill_md",
      "sourceUrl": "https://github.com/anthropics/skills",
      "sourceRef": "anthropics/skills/superpowers/git",
      "iconUrl": null,
      "author": "anthropics",
      "version": null,
      "category": null,
      "tags": ["git", "version-control"],
      "authType": null,
      "installedId": null
    }
  ],
  "nextCursor": "..."
}

Param	Type	Description
`q`	`string?`	Free-text search
`source`	`skill_md \| openapi_action \| mcp_registry`	Restrict to a single source
`limit`	`number?`	Max per source (default 20, max 50)
`cursor`	`string?`	Pagination cursor (MCP registry)

List installed skills

GET /api/skills?source=<source>

Returns Skill[] — every skill installed in the caller's org. Optional source filter.

Install a skill

POST /api/skills
Content-Type: application/json

{
  "source": "skill_md" | "openapi_action" | "mcp_registry",
  "sourceUrl": "<source URL>",
  "sourceRef": "<source-specific reference>",
  "name": "<override>",          // optional
  "description": "<override>"    // optional
}

Source	`sourceUrl`	`sourceRef`
`skill_md`	GitHub repo URL (`https://github.com/owner/repo`)	`owner/repo/path` (path inside the repo)
`openapi_action`	OpenAPI spec URL (JSON or YAML)	(unused — defaults to `sourceUrl`)
`mcp_registry`	Registry server URL	Registry server ID

Returns 201 Created with the new Skill, or:

409 SKILL_ALREADY_INSTALLED — duplicate
404 REGISTRY_SERVER_NOT_FOUND — for mcp_registry
422 STDIO_TRANSPORT_UNSUPPORTED — for mcp_registry servers that only support stdio

Get / uninstall a skill

GET    /api/skills/{skillId}
DELETE /api/skills/{skillId}

Uninstall also detaches the skill from any agents/runners it was attached to.

Re-sync source content

POST /api/skills/{skillId}/sync

Re-fetches the upstream SKILL.md body or OpenAPI spec. mcp_registry skills sync via the MCP server's tool cache (this endpoint is a no-op for them).

Returns { "ok": true, "syncedAt": "<ISO>" }. On a fetch failure the skill's status is set to error and 502 SYNC_FAILED is returned.

Attach to an agent

GET    /api/agents/{agentId}/skills
POST   /api/agents/{agentId}/skills
DELETE /api/agents/{agentId}/skills

POST body:

{
  "skillId": "<id>",
  "promptOverride": "<override>",  // optional, replaces skill prompt for this agent only
  "credentialId": "<id>"           // optional, for OAuth / API-key skills
}

GET returns AttachedSkill[] with the joined skill summary inline.

DELETE body: { "skillId": "<id>" }.

Attach to a runner

GET    /api/runners/{runnerId}/skills
POST   /api/runners/{runnerId}/skills
DELETE /api/runners/{runnerId}/skills

Identical shape to the agent endpoints.

Skill object

type Skill = {
  id: string;
  name: string;
  slug: string;
  description: string | null;
  iconUrl: string | null;
  author: string | null;
  version: string | null;
  source: 'skill_md' | 'openapi_action' | 'mcp_registry' | 'custom';
  sourceUrl: string | null;
  category: string | null;
  tags: string[];
  authType: 'none' | 'api_key' | 'oauth' | 'bearer' | null;
  status: 'active' | 'disabled' | 'error';
  lastSyncedAt: string | null;
  createdAt: string;
};