Skills & Agents

xbot has two extension mechanisms that work together: Skills provide knowledge, and Agents provide execution capacity. Both are plain Markdown files — the AI can create and manage them for you.

Tip

Just tell the agent what you want. You don’t need to write files manually. Say “create a skill for debugging Go concurrency bugs” or “make a security reviewer agent” — the AI handles everything from creation to activation.

A Skill is a capability pack — a Markdown document that instructs the agent how to handle a specific type of task. Think of it as a playbook: “when debugging, follow this checklist,” or “before committing, run these checks.”

Skills are loaded on demand. When your conversation matches a skill’s domain, the agent automatically loads the relevant guidance. You can also trigger skills explicitly:

• Type /skill-name in conversation (e.g., /debug, /plan)
• Or describe your need naturally — the agent matches the right skill

~/.xbot/skills/          ← User-level (available in all projects)
└── my-skill/
    └── SKILL.md         ← Skill definition file

Skills can also be embedded in projects for team sharing:

<project>/.xbot/skills/  ← Project-level (committed to git)
└── project-skill/
    └── SKILL.md

Each skill is a directory containing a SKILL.md file:

---
name: my-skill
description: A one-line summary of what this skill does
---

# Skill Title

## Goals
...

## Steps
...

The --- delimited section is frontmatter (metadata). Everything below is the guidance document — plain instructions for the AI.

A SubAgent is an independent assistant with its own context, tools, and role. You delegate tasks to it, and it works autonomously.

• Need a specialist role: “Have the security expert review this code”
• Need parallel work: “Review this PR from security, performance, and style perspectives simultaneously”
• Need isolated context: “Explore this module without cluttering the current conversation”

xbot ships with 10 role-specific agents modeled after the Three Departments and Six Ministries of classical Chinese governance:

Just talk to xbot naturally:

“Explore how this module works”

“Have the security expert review this code”

“Review this PR from security, performance, and style perspectives”

The agent automatically selects the right SubAgent and delegates the task.

Each agent is a Markdown file stored in ~/.xbot/agents/:

---
role: my-role
description: A one-line summary of what this agent does
tools: Read, Grep, Glob, Shell
model: swift
---

# Agent Role Description

You are XXX, specializing in XXX...

~/.xbot/agents/
├── explore.md          # Code exploration
├── chancellery.md      # Plan review
├── secretariat.md      # Architecture planning
└── ...

Group Chat is a moderated multi-agent discussion. You create a group, invite agents, and control who speaks via @mentions.

1. Create a group with CreateChat(type="group", members=[...])
2. Send messages — messages without @mentions just add to the history
3. Trigger speakers — @agent:role/instance in your message triggers that agent to respond
4. Full context — triggered agents see the entire discussion history plus your message
5. All responses preserved — every agent reply is added to the history for future reference

1. CreateChat(type="group", members=["agent:reviewer/r1", "agent:tester/t1"])
   → returns "group:g1"

2. SendMessage(to="group:g1", message="Let's discuss the API design.")
   → No agent triggered. Just adds to history.

3. SendMessage(to="group:g1", message="@agent:reviewer/r1 What do you think?")
   → Reviewer responds with full context.

4. SendMessage(to="group:g1", message="@agent:tester/t1 Any concerns?")
   → Tester responds, seeing reviewer's earlier reply too.

Note

Groups auto-close after max_rounds moderator messages with @mentions (default 10). Use SendMessage(to="group:...", message="...") to continue the discussion.

xbot supports publishing, browsing, and installing skills and agents:

Skill ideas:

• Code review checklist for your team’s standards
• Deployment checklist with environment-specific steps
• API documentation generator for your codebase
• Onboarding guide for new team members
• Debugging workflow for common error patterns

Agent ideas:

• security-reviewer — analyze code for security issues
• test-writer — generate unit tests for new code
• doc-writer — create documentation from code
• data-analyst — analyze CSV/JSON data files

Ask the agent: “Create a skill for [your workflow]” or “Create a [role] agent.”

• Built-in Tools — all available tools
• MCP — external tool integration
• Tips & Tricks — SubAgent delegation patterns