Skill System

Skills are higher-level capabilities that extend what an agent can do. While tools provide atomic operations (read a file, search the web), skills combine instructions, prompts, and tool sequences into reusable packages defined by the SKILL.md protocol.

Skill Types

MateClaw supports three skill types:

Type	Description	Source
builtin	Ships with MateClaw, maintained by the core team	Code
custom	User-created skills uploaded through the UI or API	User
mcp	Skills backed by an MCP server tool	MCP Server

SKILL.md Protocol

Every skill is defined by a SKILL.md file -- a Markdown document with YAML frontmatter that describes the skill's metadata and behavior.

Structure

---
name: web-researcher
title: Web Researcher
description: Search the web and summarize findings on a given topic
version: 1.0.0
type: custom
author: your-name
tools:
  - WebSearchTool
  - ReadFileTool
tags:
  - research
  - search
parameters:
  - name: topic
    type: string
    required: true
    description: The topic to research
  - name: depth
    type: string
    required: false
    default: brief
    description: Level of detail (brief, detailed, comprehensive)
---

# Web Researcher

You are a web research assistant. When given a topic, you should:

1. Use WebSearchTool to find relevant information about {{topic}}
2. Evaluate source credibility
3. Compile findings into a {{depth}} summary
4. Include source URLs in your response

## Output Format

Present your findings as:
- **Summary**: 2-3 sentence overview
- **Key Facts**: Bullet-point list
- **Sources**: Numbered list of URLs

Frontmatter Fields

Field	Required	Description
name	Yes	Unique identifier (kebab-case)
title	Yes	Human-readable display name
description	Yes	Short description of what the skill does
version	Yes	Semantic version
type	Yes	builtin, custom, or mcp
author	No	Skill author name
tools	No	List of required tool names
tags	No	Categorization tags
parameters	No	Input parameters the skill accepts

Parameter Schema

Each parameter in the parameters array:

Field	Required	Description
name	Yes	Parameter name
type	Yes	string, number, boolean, array
required	No	Whether the parameter must be provided (default: false)
default	No	Default value if not provided
description	Yes	What this parameter controls

Skill Storage

Skills are stored in the mate_skill database table:

Column	Description
id	Primary key
name	Unique skill name
title	Display title
description	Short description
type	builtin / custom / mcp
content	Full SKILL.md content
version	Semantic version
enabled	Whether the skill is active
tags	JSON array of tags
create_time	Creation timestamp
update_time	Last modified timestamp

Runtime Pipeline

When an agent invokes a skill, the following pipeline runs:

1. RESOLVE     Look up the skill by name in the database
       │
       ▼
2. VALIDATE    Check that required parameters are provided
       │
       ▼
3. RENDER      Replace {{parameter}} placeholders in the SKILL.md body
       │
       ▼
4. INJECT      Append the rendered instructions to the agent's system prompt
       │
       ▼
5. BIND TOOLS  Ensure the skill's required tools are available to the agent
       │
       ▼
6. EXECUTE     The agent processes the enriched prompt with access to bound tools

Template Rendering

The skill body supports placeholders:

Research the topic "{{topic}}" at a {{depth}} level of detail.

With parameters {topic: "quantum computing", depth: "detailed"}, this renders to:

Research the topic "quantum computing" at a detailed level of detail.

Skill Workspace

Each skill has its own workspace directory on the filesystem, following a convention-based structure similar to Maven Local Repository:

~/.mateclaw/skills/                 # Workspace root directory
├── translate/                      # Subdirectory named after the skill
│   ├── SKILL.md                   # Skill definition file
│   ├── references/                # Reference materials (knowledge docs, etc.)
│   └── scripts/                   # Script files
├── code-review/
│   ├── SKILL.md
│   └── ...
└── .archived/                     # Archived old skill versions
    └── translate-20260401-143000/

Auto-Sync on Startup

On application startup, SkillWorkspaceBootstrapRunner automatically scans for bundled skills under the skills/ classpath directory and syncs them to the workspace root. It only syncs when the target directory does not exist, so it never overwrites local modifications.

Configuration

mateclaw:
  skill:
    workspace:
      root: ${user.home}/.mateclaw/skills  # Workspace root directory
      auto-init: true                       # Auto-initialize directory when creating a skill
      delete-policy: archive                # Archive on delete (archive) or ignore (ignore)
      bundled-skills-path: skills           # Classpath path for bundled skills

Skill Market

Via the UI

The Skill Market page (/skills) provides:

• Browse all available skills (built-in and custom)
• Search skills by keyword
• Install skills from the marketplace
• Install from ClawHub: Browse and install skills from the ClawHub community repository through the skill market
• Create new custom skills with the built-in editor
• Enable, disable, or delete installed skills

Via the API

List all skills:

curl http://localhost:18088/api/v1/skills \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Create a custom skill:

curl -X POST http://localhost:18088/api/v1/skills \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "title": "Code Reviewer",
    "description": "Review code for bugs, style issues, and improvements",
    "type": "custom",
    "content": "---\nname: code-reviewer\ntitle: Code Reviewer\n...",
    "tags": ["development", "review"]
  }'

Enable/disable a skill:

curl -X PUT http://localhost:18088/api/v1/skills/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Creating a Custom Skill -- Step by Step

1. Define the SKILL.md with frontmatter and instructions
2. Upload through the Skill Market UI or POST to /api/v1/skills
3. Assign the skill to one or more agents
4. Test by sending a message that triggers the skill

Example -- a "Daily Standup" skill:

---
name: daily-standup
title: Daily Standup Generator
description: Generate a daily standup update based on recent git activity
version: 1.0.0
type: custom
tools:
  - ShellExecuteTool
parameters:
  - name: repo_path
    type: string
    required: true
    description: Path to the git repository
---

# Daily Standup Generator

Generate a standup update by analyzing recent git activity.

## Steps

1. Run `git log --oneline --since="yesterday" --author=$(git config user.name)`
   in the directory {{repo_path}}
2. Summarize completed work
3. Identify any work-in-progress branches
4. Format as a standup update:
   - **Yesterday**: What was completed
   - **Today**: What is planned based on open branches
   - **Blockers**: Any merge conflicts or failing tests

Security Considerations

• Skills with dangerous tools (ShellExecuteTool, WriteFileTool) go through ToolGuard approval
• Custom skill content is scanned for common injection patterns before storage
• MCP skills inherit the security constraints of their backing MCP server
• See Security for more on skill security scanning

Next Steps

• MCP Protocol -- MCP-backed skills
• Tool System -- Tools that skills can use
• Agent Engine -- How agents invoke skills