Agent Skills

Skills are behavioral instructions injected into the agent's system prompt. They define when to act, what to do, and what not to do in specific scenarios. Unlike tools, skills don't execute actions — they guide the agent's decision-making.

How Skills Work

Builder configures skill_config schema
    ↓
load-agent loads skills sorted by priority
    ↓
context-builder injects as prompt sections:
    ## Skill: Destructive Action Guard
    [instructions markdown]

    ## Skill: Error Recovery
    [instructions markdown]
    ↓
LLM reads instructions and follows them during execution

Each skill becomes a ## Skill: {name} section in the system prompt. Higher priority skills appear first.

---

Schema Structure

Skills use the skill_config schema type:

{
  "schema_type": "skill_config",
  "schema_data": {
    "skill": {
      "name": "Destructive Action Guard",
      "instructions": "## Destructive Action Guard\n\nBefore executing any operation...",
      "priority": 100
    }
  }
}

Field	Type	Required	Description
name	string	Yes	Displayed as heading in the prompt (min 3 chars)
instructions	string	Yes	Markdown behavioral instructions (min 50, max 5000 chars)
priority	integer	No	Sort order — higher appears first in prompt (0–1000, default 0)

---

Skill Templates

The platform provides 9 predefined skill templates as starting points. Builders can use them as-is or customize the instructions for their domain.

Available Templates

Retrieve templates via the API:

GET /api/agents/skill-templates

Optional filters: ?category=safety or ?tag=whatsapp

Safety

Template	Description	Tags
destructive_action_guard	Requires explicit user confirmation before irreversible operations (delete, send, update)	crud, api, database
sensitive_data_policy	Rules for masking PII, financial data and credentials in responses	compliance, pii, lgpd
scope_boundary	Defines clear domain limits — prevents the agent from improvising outside its expertise	specialization, guardrail

Communication

Template	Description	Tags
human_escalation	Criteria for when the agent should stop trying and hand off to a human	support, whatsapp, handoff
emotional_awareness	Monitors user tone (frustration, urgency, satisfaction) and adapts communication style	empathy, whatsapp
progressive_data_collection	Collects required fields conversationally (1-2 per message) instead of dumping a form	onboarding, registration

Data

Template	Description	Tags
structured_output	Enforces consistent formatting — tables for lists, key-value for single records, locale-aware numbers	formatting, database, reports

Workflow

Template	Description	Tags
error_recovery	Retry strategy when tools fail — analyze error, correct and retry once, degrade gracefully	resilience, api, mcp
audit_trail	Forces the agent to report every write operation with action, target, result and reference ID	compliance, traceability

---

Using a Template

Step 1 — Fetch the template:

GET /api/agents/skill-templates?category=safety

Step 2 — Create the skill on your agent using the template's schema_data:

POST /api/agents/{agent_id}/schemas
Content-Type: application/json

{
  "schema_type": "skill_config",
  "schema_data": {
    "skill": {
      "name": "Destructive Action Guard",
      "priority": 100,
      "instructions": "## Destructive Action Guard\n\nBefore executing any operation..."
    }
  }
}

Step 3 — Customize the instructions if needed. The template is a starting point — adjust thresholds, add domain-specific rules, or translate to your language.

---

Managing Skills

Skills are managed through the standard schema endpoints:

Endpoint	Method	Description
GET /api/agents/:id/schemas?schema_type=skill_config	GET	List agent skills
POST /api/agents/:id/schemas	POST	Add skill to agent
PATCH /api/agents/:agentId/schemas/:schemaId	PATCH	Update skill instructions
DELETE /api/agents/:agentId/schemas/:schemaId	DELETE	Remove skill
GET /api/agents/:id/validate-schemas	GET	Validate all schemas including skills

Via MCP

Skills can also be managed through the MCP Server using create_schema, update_schema and delete_schema tools with schema_type: "skill_config".

---

Multiple Skills

An agent can have multiple skills active simultaneously. They are sorted by priority (highest first) and injected as separate sections in the system prompt.

Recommended combinations:

Use Case	Skills
Customer support (WhatsApp)	emotional_awareness + human_escalation + scope_boundary
CRUD operations	destructive_action_guard + audit_trail + error_recovery
Data queries & reports	structured_output + error_recovery
Regulated environments	sensitive_data_policy + audit_trail + destructive_action_guard
Onboarding flows	progressive_data_collection + destructive_action_guard

Prompt Budget

Each skill adds to the system prompt length. Keep total skill instructions under 3000 tokens to leave room for the agent's persona, tools and conversation context. The validation endpoint will warn if instructions exceed 5000 characters per skill.

---

Writing Custom Skills

When templates don't fit, write your own. Follow this structure:

## When to act

[Clear trigger conditions — what the agent should watch for]

## What to do

[Step-by-step behavior when triggered]

## What NOT to do

[Explicit boundaries to prevent unwanted behavior]

Good skill instructions are:

• Specific — "after 2 failed attempts" not "after a few tries"
• Observable — based on things the LLM can detect in the conversation
• Actionable — clear steps, not vague guidance
• Bounded — include explicit "do not" rules to prevent over-application

---

Memory Integration

Skills interact with the agent memory system. The skill_config schema type acts as an opt-in flag for memory write access:

Skill config present	Memory behavior
Yes	Agent can read and write user memories (save_memory, recall_memory)
No	Agent can only read system-generated memories (e.g., schedule reports)

This means adding any skill to an agent automatically enables full memory capabilities. The Gerenciador de Memória template (available as a custom skill) provides specific guidelines on when and what to memorize.