Documentation

Skills Development Guide

Skills are markdown files that shape how the voice agent behaves. Unlike plugins (which add new capabilities), skills modify the agent’s personality, response style, and decision-making by injecting instructions into the LLM’s system prompt.

How Skills Work

1. You create a SKILL.md file with YAML frontmatter and markdown instructions
2. The server discovers all skills at startup
3. All skill content is appended to the LLM’s system prompt
4. The LLM follows the skill instructions during every conversation

Skills are always active— they influence every response. Use them for behaviors you want the agent to consistently exhibit.

Directory Structure

Skills live inside the configured plugin directory (default: server/plugins/):

server/plugins/
└── skills/
    └── my-skill/
        └── SKILL.md       # Required — the skill definition

SKILL.md Format

A skill file has two parts: YAML frontmatter (metadata) and markdown content (instructions).

SKILL.md

---
name: polite-assistant
description: Makes the agent respond politely and professionally
version: 1
triggers:
  - greeting
  - farewell
plugins:
  - calendar.create_event
---

# When to use
Always apply these rules when responding to users.

# Instructions
- Be polite and professional
- Use the user's name when known
- End conversations warmly

# Avoid
- Don't be overly casual
- Don't use slang

Frontmatter Fields

Field	Required	Description
name	Yes	Unique identifier (kebab-case)
description	Yes	What this skill does
version	Yes	Integer version number
triggers	No	Keywords that hint when the skill is relevant
plugins	No	Plugin names this skill references

Creating a Skill

Example 1: Personality Skill

Make the agent respond in a specific style.

mkdir -p server/plugins/skills/friendly-assistant

server/plugins/skills/friendly-assistant/SKILL.md

---
name: friendly-assistant
description: Makes the agent warm, approachable, and conversational
version: 1
---

# Personality
You are a warm, friendly assistant. Speak naturally as if having a real conversation.
Use casual but professional language.

# Response Style
- Keep responses concise — aim for 1-3 sentences when possible
- Use conversational fillers naturally ("Sure thing!", "Great question!")
- Mirror the user's energy level
- If the user is excited, match their enthusiasm
- If the user is serious, be more measured

# Avoid
- Don't be robotic or overly formal
- Don't use bullet points or structured formats in speech
- Don't hedge excessively ("I think maybe perhaps...")
- Don't apologize unnecessarily

Example 2: Domain Expert Skill

Make the agent an expert in a specific domain.

server/plugins/skills/tech-support/SKILL.md

---
name: tech-support
description: Technical support agent for a SaaS product
version: 1
triggers:
  - help
  - problem
  - error
  - not working
---

# Role
You are a technical support agent for Acme Cloud Platform. You help users
troubleshoot issues with their accounts, deployments, and integrations.

# Troubleshooting Steps
1. Ask what the user is trying to do
2. Ask for any error messages they're seeing
3. Guide them through the most common fix first
4. If that doesn't work, escalate to specific diagnostics
5. Always confirm the issue is resolved before ending

# Avoid
- Don't guess at solutions — ask for specifics
- Don't share internal infrastructure details
- If you don't know, say "Let me connect you with our engineering team"

Example 3: Skill That References Plugins

Guide the LLM on when to use specific tools.

server/plugins/skills/schedule-meeting/SKILL.md

---
name: schedule-meeting
description: Guides the agent through scheduling meetings using calendar tools
version: 1
triggers:
  - schedule
  - meeting
  - appointment
plugins:
  - calendar.create_event
  - calendar.check_availability
---

# Steps
1. Ask who the meeting is with (if not specified)
2. Ask for the preferred date and time
3. Use calendar.check_availability to verify the time slot
4. If the slot is taken, suggest the nearest available time
5. Use calendar.create_event to book the meeting
6. Confirm the details back to the user

# Confirmation
Always read back the meeting details before creating the event:
"I'll schedule a meeting with [person] on [date] at [time]. Sound good?"

# Avoid
- Don't create events without confirming with the user first
- Don't assume timezone — ask if unclear

How Skills Are Injected

At server startup, the plugin manager:

1. Scans plugins/skills/ for folders containing SKILL.md
2. Parses the YAML frontmatter to extract metadata
3. Extracts the markdown content after the frontmatter
4. When a pipeline starts, concatenates all skill content and appends it to the LLM’s system prompt

The injection looks like this in the system prompt:

[Original system prompt from config.toml]

--- Plugin Skills ---

[Skill: friendly-assistant]
# Personality
You are a warm, friendly assistant...

[Skill: tech-support]
# Role
You are a technical support agent...

Combining Skills

Multiple skills can be active simultaneously. They’re all appended to the system prompt, so they combine naturally:

friendly-assistant + tech-support = A friendly technical support agent
multilingual + schedule-meeting = A meeting scheduler that speaks multiple languages

Avoiding Conflicts

Keep skills focused on one concern each
Don’t give contradictory personality instructions across skills
Test skill combinations by having conversations with the agent

Testing Skills

1. Restart the Server

Skills are loaded at startup. After creating or modifying a skill:

cd server && go run main.go

Check the logs for:

loaded skill: friendly-assistant
loaded skill: tech-support
loaded 0 plugins, 2 skills

2. Talk to the Agent

Connect via the web client and have a conversation to verify the skill is working. Try triggering specific behaviors you defined in the skill.

3. Troubleshooting

Verify the SKILL.md has valid YAML frontmatter (between --- delimiters)
Check that the file is in the right location: plugins/skills/<name>/SKILL.md
Look at server logs for loading errors

Best Practices

Keep it short

The entire skill is injected into the system prompt. Long skills consume context window and can dilute other instructions. Aim for under 50 lines of markdown.

Be specific

Vague instructions like "be helpful" don't add value. Give concrete rules the LLM can follow.

Test with voice

Skills affect spoken responses. What reads well may not sound natural when spoken aloud.

Use sections

Organize with headers (# When to use, # Steps, # Avoid). This helps the LLM parse the instructions.

Define boundaries

Always include an "Avoid" section to prevent unwanted behaviors.

One concern per skill

A skill for personality and a separate skill for domain expertise combine better than one monolithic skill.

Version your skills

Bump the version field when you make changes to track what's deployed.

Built-in Skills

Skill	Purpose
friendly-conversationalist	Warm, natural conversational style
polite-assistant	Professional, courteous interaction
tool-savvy	Guides agent to use tools instead of guessing
concise-responder	Short responses optimized for voice delivery
error-recovery	Graceful error handling in voice conversations
vision-assistant	Camera image analysis guidance
gmail-assistant	Email read/send with confirmation flows

Plugin guide →Client SDKs →Quickstart →