Skills: how agents take action in the outside world

Skills are the mechanism through which agents interact with external services and take action in the world. When Curia sends an email, searches the web, creates a calendar event, or looks up a contact, it is invoking a skill. Agents don’t call APIs directly — they invoke skills, which handle authentication, validation, and output sanitization on their behalf. The LLM never sees raw credentials.

Two types of skills

Curia supports two types of skills, and agents work with both using the same interface — they cannot tell the difference at runtime.

Local skills
MCP skills

Local skills live in the skills/ directory as a folder containing a manifest and handler:

skills/
  email-send/
    skill.json      # manifest: name, inputs, outputs, permissions, sensitivity
    handler.ts      # implementation
    handler.test.ts # tests

The manifest declares everything the execution layer needs to validate, authorize, and invoke the skill. The handler implements the actual logic.

MCP skills connect to external Model Context Protocol servers over HTTP or stdio. At startup, Curia connects to each configured MCP server, discovers its tools via tools/list, and registers them in the skill registry alongside local skills.

# config/skills.yaml
mcp_servers:
  - name: google-workspace
    transport: http
    url: https://mcp-server.example.com/mcp
    headers:
      Authorization: "Bearer <token>"
    action_risk: low
    permissions: ["workspace:read", "workspace:write"]

Supported transports are http (StreamableHTTP, recommended for hosted servers) and stdio (local subprocess).

The skill manifest

Every local skill includes a skill.json manifest that the execution layer validates at startup. Here is a real example from the email-send skill:

{
  "name": "email-send",
  "description": "Send a new email via the configured email account",
  "version": "1.0.0",
  "sensitivity": "normal",
  "action_risk": "medium",
  "inputs": {
    "to": "string",
    "cc": "string?",
    "subject": "string",
    "body": "string"
  },
  "outputs": {
    "message_id": "string",
    "to": "string",
    "subject": "string"
  },
  "permissions": [],
  "secrets": [],
  "timeout": 30000
}

Manifest fields

Field	Description
`name`	Unique identifier used by agents and the skill registry
`description`	Human-readable description — shown to the LLM and in the registry
`sensitivity`	`normal` or `elevated` — controls first-use approval behavior
`action_risk`	Risk level used by the autonomy engine — see below
`inputs`	Input schema — validated before the handler is called
`outputs`	Output schema — documents what the skill returns
`permissions`	Declared capabilities, validated at load time
`secrets`	Vault secret keys this skill may request via `ctx.secret()`
`timeout`	Per-invocation timeout in milliseconds (default: 30,000)
`install.requires_secrets`	Optional. Vault keys that must exist before the skill can be installed or enabled (see Skill lifecycle)

Action risk levels

Every skill declares an action_risk value that indicates its potential impact on the world. This field is required — Curia will not start if any skill manifest omits it.

Level	Min autonomy score	Capability class
`none`	0	Read-only, no external effects (web search, summarization)
`low`	60	Internal state writes — memory, contacts
`medium`	70	Outbound communications — sending email or Signal messages
`high`	80	Calendar writes, commitments made on behalf of the CEO
`critical`	90	Financial, destructive, or irreversible actions

The autonomy engine uses these values to determine whether a given skill can run at the current autonomy score. See Autonomy engine for the full picture.

Sensitivity and first-use approval

The sensitivity field controls what happens the first time an agent tries to use a skill it was not explicitly configured with:

normal — the skill is auto-approved if the agent has allow_discovery: true
elevated — skills like payment processing or bulk deletion require your explicit approval the first time an agent requests them; once approved for that agent, they do not ask again

This means you review elevated-sensitivity skills once, not on every invocation.

Secrets: credentials the LLM never sees

Skills that need API keys, passwords, or tokens declare them in their secrets array. At runtime, the execution layer provides a scoped ctx.secret() accessor that resolves the value from the encrypted vault:

// Inside a skill handler
const apiKey = ctx.secret("nylas_api_key");

The execution layer validates that the calling skill’s manifest declared the requested secret. If a skill tries to access a secret it did not declare, the call fails. Agents and LLMs never see secret values — only the skill handler does, and only through this scoped accessor. Every secret access is audit-logged (which skill, which task, when, and whether the value came from the vault or an env fallback) — but values are never written to the log.

Skill lifecycle: install and enable

Skills live in a DB-backed registry. A skill present on disk is not automatically active — it must be installed and enabled before agents can call it, and only enabled skills are loaded at startup. This gives you a single place to turn capabilities on and off, and a gate for required credentials. When a skill declares install.requires_secrets, the registry refuses to install or enable it until every listed vault key is present. The bundled web-search skill declares tavily_api_key, so it stays disabled until you provision a Tavily key. Enable and disable skills from the Settings registry in the console; changes take effect on restart.

Output sanitization

Every skill result is sanitized before the LLM sees it. This prevents tool outputs from being used as injection vectors:

XML and HTML tags are stripped — they cannot be interpreted as system instructions
Outputs longer than 200,000 characters are truncated with a [truncated] marker
Patterns matching known secret formats (API keys, tokens, passwords) are redacted
Error strings are wrapped in a structured format that prevents them from being read as instructions

Nothing from the outside world reaches the LLM unfiltered.

Built-in skills

Curia ships with more than 50 built-in skills across several categories:

email-send, email-reply, email-list, email-get, email-archive, email-draft-save — send, reply, browse, and draft emails via the Nylas API across multiple configured accounts.

Calendar

calendar-list-calendars, calendar-list-events, calendar-create-event, calendar-update-event, calendar-delete-event, calendar-find-free-time, calendar-check-conflicts, calendar-register — full calendar management via Nylas.

Contacts

contact-create, contact-lookup, contact-list, contact-link-identity, contact-set-role, contact-merge, contact-find-duplicates, contact-grant-permission, contact-revoke-permission, contact-unlink-identity, contact-set-trust — manage contacts and their trust levels.

Web research

web-search, web-fetch, web-browser — search the web via Tavily, fetch static pages, or use a full Playwright-backed browser for JavaScript-rendered sites.

Knowledge and memory

entity-context, context-for-email, memory-store, memory-query, memory-confirm, decay-warnings-list, config-store, query-relationships, delete-relationship, extract-facts, extract-relationships — query, write to, and manage the knowledge graph.

Scheduling

scheduler-create, scheduler-list, scheduler-cancel, scheduler-report — create and manage recurring or one-shot scheduled tasks.

Communication templates

template-doc-request — structured outbound email template for document requests. Scheduling email (meeting requests, reschedules, cancellations) is now composed directly by the Calendar Specialist.

Agent coordination

delegate, bullpen, skill-registry, held-messages-list, held-messages-process, signal-send — inter-agent delegation, the Bullpen discussion space, skill discovery, and held-message management.

Autonomy

get-autonomy, set-autonomy — read and update the global autonomy score. Pinned to the Coordinator only.

Recommended MCP integrations

These MCP servers are not bundled with Curia but are documented as first-class integrations:

Server	Purpose
Google Workspace	Drive, Docs, Sheets, Gmail read/search/write
Filesystem	Scoped local file access (read/write/search)
GitHub	Repository management, issues, pull requests
Brave Search	Additional web search for research agents
Fetch	Web fetching with robots.txt compliance

To connect any MCP server, add it to config/skills.yaml using the mcp_servers block shown above. Curia will discover and register its tools automatically at startup.

Building custom skills

Build a local skill from scratch with a manifest and handler.

Autonomy

See how action_risk values gate skill execution by autonomy score.

​Two types of skills

​The skill manifest

​Manifest fields

​Action risk levels

​Sensitivity and first-use approval

​Secrets: credentials the LLM never sees

​Skill lifecycle: install and enable

​Output sanitization

​Built-in skills

​Recommended MCP integrations

Building custom skills

Autonomy

Two types of skills

The skill manifest

Manifest fields

Action risk levels

Sensitivity and first-use approval

Secrets: credentials the LLM never sees

Skill lifecycle: install and enable

Output sanitization

Built-in skills

Recommended MCP integrations