Skills

Skills are reusable, callable handlers that extend what an agent can do — web search, code execution, API calls, and more. Skills can be scoped to the platform, an organization, or a project, and assigned to one or more agents.

Base path: /api/skills

All endpoints require Authorization: Bearer <token>.

---

Scope Cascade

Skills are resolved in order: project → organization → platform. A skill defined at the project level overrides a same-named skill at the organization level.

Pass scope headers to control visibility:

X-Scope-Organization-Id: org_01J...
X-Scope-Project-Id: proj_01J...

---

List Skills

GET /api/skills

Returns all skills visible to the current scope.

Query parameters:

Parameter	Type	Description
scope	string	platform, organization, project
search	string	Search by name or description
limit	number	Default 20, max 100
offset	number	Default 0

Response:

{
  "success": true,
  "data": [
    {
      "id": "sk_01J...",
      "name": "web-search",
      "description": "Search the web using a query string",
      "scope": "platform",
      "handler": "https://skills.acrobi.com/web-search",
      "schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        },
        "required": ["query"]
      },
      "createdAt": "2026-01-10T08:00:00Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 12 }
}

curl:

curl "https://api.cortex.acrobi.com/api/skills?scope=platform" \
  -H "Authorization: Bearer <token>"

---

Create Skill

POST /api/skills

Request body:

{
  "name": "send-email",
  "description": "Send an email via the configured SMTP provider",
  "handler": "https://workers.acrobi.com/skills/send-email",
  "schema": {
    "type": "object",
    "properties": {
      "to": { "type": "string", "format": "email" },
      "subject": { "type": "string" },
      "body": { "type": "string" }
    },
    "required": ["to", "subject", "body"]
  },
  "scope": "organization"
}

Field	Type	Required	Description
name	string	Yes	Unique kebab-case identifier within scope
description	string	Yes	What the skill does
handler	string	Yes	URL or function reference the agent calls
schema	object	No	JSON Schema describing the skill's input
scope	string	No	platform, organization, project (default organization)

Response: 201 Created

{
  "success": true,
  "data": {
    "id": "sk_01J...",
    "name": "send-email",
    "scope": "organization",
    "createdAt": "2026-04-03T12:00:00Z"
  }
}

curl:

curl -X POST "https://api.cortex.acrobi.com/api/skills" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "send-email",
    "description": "Send an email via SMTP",
    "handler": "https://workers.acrobi.com/skills/send-email",
    "scope": "organization"
  }'

---

Get Skill

GET /api/skills/:id

Response:

{
  "success": true,
  "data": {
    "id": "sk_01J...",
    "name": "send-email",
    "description": "Send an email via the configured SMTP provider",
    "handler": "https://workers.acrobi.com/skills/send-email",
    "schema": { ... },
    "scope": "organization",
    "assignedAgents": ["email-agent", "notifier"],
    "createdAt": "2026-04-03T12:00:00Z",
    "updatedAt": "2026-04-03T12:00:00Z"
  }
}

---

Update Skill

PATCH /api/skills/:id

Request body:

{
  "description": "Send emails with optional CC and attachments",
  "handler": "https://workers.acrobi.com/skills/send-email-v2"
}

Response: 200 OK — returns updated skill object.

---

Delete Skill

DELETE /api/skills/:id

Removes the skill. Agents currently using this skill will lose access to it.

Response:

{ "success": true }

---

Test Skill Handler

Sends a test invocation to the skill's handler URL and returns the result. Useful for verifying connectivity and schema validation before assigning to an agent.

POST /api/skills/:id/test

Request body:

{
  "input": {
    "to": "test@example.com",
    "subject": "Test from Cortex",
    "body": "This is a handler connectivity test."
  }
}

Response: 200 OK

{
  "success": true,
  "data": {
    "handlerResponse": {
      "sent": true,
      "messageId": "msg_abc123"
    },
    "durationMs": 312,
    "httpStatus": 200
  }
}

TIP

If the handler returns a non-2xx status, the success field will be false and data.error will contain the handler's error message.