Org Knowledge (Skills)

Every skill the agents look up lives in the knowledge base. These endpoints let you read, author, and manage skills via API.

`GET /api/org/knowledge/skills`

List all skills available to a workspace’s nodes.

Request


GET /api/org/knowledge/skills?structure_id=<uuid>
Authorization: Bearer <token>

Response

200 OK:


{
  "skills": [
    {
      "slug": "find-leads",
      "name": "Find Leads",
      "category": "sales",
      "difficulty": "high",
      "tags": ["lead-gen", "outreach", "qualification"],
      "summary": "Build a qualified B2B outbound pipeline...",
      "status": "complete",
      "learned_by": "system",
      "learned_at": "2026-02-15T00:00:00Z",
      "tool_url": null
    },
    ...
  ]
}

The MCP list_skills() tool proxies this.

`GET /api/org/knowledge/skills/{slug}`

Fetch the full markdown body for a single skill.

Response

200 OK:


{
  "slug": "find-leads",
  "frontmatter": { ... },
  "body": "## [triage-seller] Step 0: Triage + Seller Scan\n\n..."
}

`POST /api/org/knowledge/skills`

Author a new skill or update an existing one.

Request


POST /api/org/knowledge/skills
Content-Type: application/json
 
{
  "structure_id": "uuid",
  "slug": "post-to-x",
  "frontmatter": {
    "type": "skill",
    "name": "Post to X",
    "category": "marketing",
    "difficulty": "medium",
    "tags": ["social", "x"],
    "status": "complete",
    "summary": "Post a message to X, capture URL + metrics."
  },
  "body": "## [prereqs] Step 1: ..."
}

Response

201 Created — echoes the stored record. If the slug already exists, returns 200 OK with the updated record.

Status values

draft — visible in the Skills Editor but the agent won’t auto-resolve it on natural-language matches. Invoke by explicit slug.
complete — fully visible, auto-resolvable.
deprecated — hidden from the default catalog. Existing skill references continue to work.

`DELETE /api/org/knowledge/skills/{slug}`

Removes a skill. The markdown file is moved to data/knowledge/<workspace_id>/skills/_deleted/ so it can be restored if needed.

`POST /api/org/knowledge/search`

Search the skill catalog by natural-language query (returns ranked matches).

Request


{
  "structure_id": "uuid",
  "query": "help me list items on Etsy",
  "limit": 5
}

Response

200 OK:


{
  "matches": [
    {
      "slug": "sell-online",
      "score": 0.92,
      "reason": "tags match 'listings', summary mentions Etsy"
    },
    ...
  ]
}

This is the endpoint the agent calls internally when it does skill-lookup on every chat message. Use it directly if you want to inspect what an agent would have matched.

Skill auto-learning

When an agent succeeds at a task without a matching skill, the system:

Detects the skill_learned event in the chat stream.
Calls this endpoint (POST /api/org/knowledge/skills) with status: draft + learned_by: agent.
Surfaces the draft in the workspace’s Skills Editor for operator review.

See Authoring Custom Skills for more on the file format and directory layout.