Skills API

Skills extend what an agent can do. They are defined as Markdown files with YAML frontmatter and are subject to a quarantine/approval workflow before becoming active.

Skill Format

Skills are Markdown documents with YAML frontmatter that describes metadata and parameters:

---
name: web_search
description: Search the web for information
parameters:
  - name: query
    type: string
    required: true
    description: The search query
---

# Web Search

Search the web using the configured search provider.

## Usage

Provide a search query and receive relevant results with titles, URLs, and snippets.

List Skills

GET /v1/agents/{id}/skills

Returns all skills installed for an agent.

Example

curl http://127.0.0.1:3000/v1/agents/researcher/skills

Response (200)

[
  {
    "id": "sk_abc123",
    "name": "web_search",
    "description": "Search the web for information",
    "status": "active",
    "installed_at": "2025-03-15T10:00:00Z"
  },
  {
    "id": "sk_def456",
    "name": "file_reader",
    "description": "Read and parse local files",
    "status": "quarantined",
    "installed_at": "2025-03-16T14:30:00Z"
  }
]

Skill Status

Status	Description
active	Skill is approved and available for use
quarantined	Skill is installed but awaiting approval

Install Skill

POST /v1/agents/{id}/skills/install

Install a skill from a URL or provide it inline as Markdown content.

Request (From URL)

{
  "url": "https://github.com/user/moxxy-skills/blob/main/skills/web_search.md"
}

Request (Inline Markdown)

{
  "content": "---\nname: greeting\ndescription: Greet the user\n---\n\n# Greeting\n\nGreet the user warmly."
}

Response (201)

{
  "id": "sk_ghi789",
  "name": "greeting",
  "description": "Greet the user",
  "status": "quarantined",
  "installed_at": "2025-03-17T09:00:00Z"
}

Newly installed skills enter the quarantined state by default and must be approved before the agent can use them. This prevents untrusted skills from executing without review.

Delete Skill

DELETE /v1/agents/{id}/skills/{skill_id}

Removes a skill from the agent.

Example

curl -X DELETE http://127.0.0.1:3000/v1/agents/researcher/skills/sk_abc123

Response (204)

No content.

Quarantine and Approval

When a skill is installed, it enters quarantine. While quarantined, the agent cannot invoke the skill. This gives operators a chance to review the skill's Markdown source, parameters, and any referenced primitives before granting access.

Approval is managed through the agent's configuration. Once approved, the skill's status changes to active and becomes available during runs.

MCP Servers

In addition to Markdown skills, agents can connect to external tool providers via the Model Context Protocol (MCP).

List MCP Servers

GET /v1/agents/{id}/mcp

Response (200)

[
  {
    "id": "mcp_abc",
    "name": "filesystem",
    "transport": "stdio",
    "status": "connected"
  }
]

Add MCP Server

POST /v1/agents/{id}/mcp

Supports both stdio and sse transport types.

Stdio Transport

{
  "name": "filesystem",
  "transport": "stdio",
  "command": "mcp-filesystem",
  "args": ["/home/user/documents"]
}

SSE Transport

{
  "name": "remote-tools",
  "transport": "sse",
  "url": "http://localhost:8080/mcp/sse"
}

Response (201)

{
  "id": "mcp_def",
  "name": "filesystem",
  "transport": "stdio",
  "status": "connected"
}

Remove MCP Server

DELETE /v1/agents/{id}/mcp/{id}

Response (204)

No content.