技能系统

技能（Skill）是 MateClaw 中对 Agent 能力的高层封装。每个技能通过 SKILL.md 文件定义，包含提示词模板、参数声明和执行逻辑，存储在数据库中统一管理。

核心概念

工具（Tool）是原子操作，技能（Skill）是编排方案。一个技能可以组合多个工具调用、定义交互流程，实现特定领域的复杂任务。

技能 = 提示词模板 + 参数声明 + 工具依赖 + 执行逻辑

SKILL.md 协议

每个技能通过一个 SKILL.md 文件定义，采用 YAML frontmatter + Markdown 正文的格式。

基本结构

markdown

---
name: translate
displayName: 翻译助手
description: 将文本翻译为指定语言
version: 1.0.0
type: custom
author: mateclaw
tags:
  - 翻译
  - 语言
parameters:
  - name: text
    type: string
    required: true
    description: 待翻译的文本
  - name: targetLang
    type: string
    required: true
    default: 英文
    description: 目标语言
tools:
  - WebSearchTool
---

# 翻译助手

你是一名专业的翻译助手。请将以下文本翻译为{{targetLang}}。

## 翻译要求

1. 保持原文的语义和风格
2. 使用自然流畅的目标语言表达
3. 如果遇到专业术语，保留原文并在括号中给出翻译

## 待翻译文本

{{text}}

Frontmatter 字段说明

字段	类型	必需	说明
`name`	string	是	技能唯一标识（英文，用于代码引用）
`displayName`	string	是	显示名称（支持中文）
`description`	string	是	技能描述
`version`	string	是	版本号（语义化版本）
`type`	string	是	类型：`builtin` / `custom` / `mcp`
`author`	string	否	作者
`tags`	string[]	否	标签，用于分类和搜索
`parameters`	object[]	否	参数列表
`tools`	string[]	否	依赖的工具列表
`dependencies`	string[]	否	依赖的其他技能
`security`	object	否	安全配置

参数定义

yaml

parameters:
  - name: query          # 参数名
    type: string         # 类型：string / number / boolean / array
    required: true       # 是否必需
    default: ""          # 默认值
    description: 搜索关键词  # 描述
    enum:                # 可选值枚举
      - option1
      - option2

参数通过模板语法在 Markdown 正文中引用。

技能类型

builtin — 内置技能

随系统预装，不可删除，可禁用。涵盖常见使用场景：

技能	说明
翻译助手	多语言翻译
代码审查	代码质量分析和改进建议
文档摘要	长文档内容提炼
日报生成	根据工作内容生成日报
SQL 助手	自然语言转 SQL

custom — 自定义技能

用户自行创建的技能，完全可控。支持通过 UI 编辑器或 API 创建。

mcp — MCP 技能

通过 MCP 协议从外部服务器发现并注册的技能。技能定义来自 MCP 服务器的能力声明。

Skill Workspace（技能工作区）

每个技能在文件系统上拥有独立的工作区目录，遵循 Maven Local Repository 式的约定结构：

~/.mateclaw/skills/                 # 工作区根目录
├── translate/                      # 技能名对应的子目录
│   ├── SKILL.md                   # 技能定义文件
│   ├── references/                # 参考资料（知识文档等）
│   └── scripts/                   # 脚本文件
├── code-review/
│   ├── SKILL.md
│   └── ...
└── .archived/                     # 已归档的旧版本技能
    └── translate-20260401-143000/

启动时自动同步

应用启动时，SkillWorkspaceBootstrapRunner 会自动扫描 classpath 下 skills/ 目录中的预置技能，同步到工作区根目录。仅在目标目录不存在时同步，不会覆盖用户的本地修改。

配置

yaml

mateclaw:
  skill:
    workspace:
      root: ${user.home}/.mateclaw/skills  # 工作区根目录
      auto-init: true                       # 创建技能时自动初始化目录
      delete-policy: archive                # 删除时归档（archive）或忽略（ignore）
      bundled-skills-path: skills           # classpath 下预置技能路径

技能市场（SkillMarket）

MateClaw 前端提供技能市场页面，用于浏览、安装和管理技能。

功能

浏览技能：按分类和标签筛选
搜索技能：关键词搜索
安装技能：一键安装到系统
从 ClawHub 安装：通过技能市场从 ClawHub 社区仓库浏览和安装技能
管理技能：启用/禁用/删除已安装技能
创建技能：在线编辑器创建自定义技能

创建自定义技能

通过 UI 创建

进入「技能市场」页面
点击「创建技能」
在编辑器中编写 SKILL.md 内容
填写 frontmatter 元信息
编写 Markdown 正文（提示词模板）
点击保存

通过 API 创建

bash

curl -X POST http://localhost:18088/api/v1/skills \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "code-review",
    "displayName": "代码审查",
    "description": "分析代码质量并给出改进建议",
    "type": "custom",
    "version": "1.0.0",
    "tags": ["代码", "质量"],
    "content": "---\nname: code-review\n...\n---\n# 代码审查\n...",
    "tools": ["ReadFileTool"],
    "parameters": [
      {
        "name": "filePath",
        "type": "string",
        "required": true,
        "description": "待审查的文件路径"
      }
    ]
  }'

技能模板示例

周报生成器

markdown

---
name: weekly-report
displayName: 周报生成器
description: 根据本周工作内容自动生成周报
version: 1.0.0
type: custom
tags:
  - 办公
  - 报告
parameters:
  - name: tasks
    type: string
    required: true
    description: 本周完成的工作内容（逐条列出）
  - name: issues
    type: string
    required: false
    description: 遇到的问题和解决方案
  - name: nextWeek
    type: string
    required: false
    description: 下周工作计划
tools:
  - DateTimeTool
---

# 周报生成器

你是一名专业的周报撰写助手。请根据以下信息生成结构清晰的周报。

## 输出格式

使用以下结构：
1. **本周工作总结** — 将工作内容归类整理
2. **关键成果** — 提炼量化的成果
3. **问题与风险** — 列出遇到的问题
4. **下周计划** — 安排下周工作

## 本周工作内容

{{tasks}}

## 遇到的问题

{{issues}}

## 下周计划

{{nextWeek}}

API 文档生成器

markdown

---
name: api-doc-gen
displayName: API 文档生成器
description: 读取 Java 源代码自动生成 API 文档
version: 1.0.0
type: custom
tags:
  - 开发
  - 文档
parameters:
  - name: filePath
    type: string
    required: true
    description: Java Controller 源文件路径
tools:
  - ReadFileTool
---

# API 文档生成器

请读取指定的 Java Controller 文件，分析其中的 REST API 端点，生成 Markdown 格式的 API 文档。

## 要求

1. 列出所有 API 端点（HTTP 方法 + 路径）
2. 说明每个端点的用途
3. 列出请求参数和返回值
4. 给出 curl 请求示例

## 源文件

{{filePath}}

技能运行时管道

技能在被调用时，会经过以下处理管道：

技能调用请求
     ↓
┌──────────────┐
│   Resolve     │  ← 从数据库加载技能定义
└──────┬───────┘
       ↓
┌──────────────┐
│   Security    │  ← 检查调用权限和安全策略
└──────┬───────┘
       ↓
┌──────────────┐
│  Dependency   │  ← 解析并加载依赖的技能和工具
└──────┬───────┘
       ↓
┌──────────────┐
│ Availability  │  ← 检查工具可用性
└──────┬───────┘
       ↓
┌──────────────┐
│   Execute     │  ← 渲染模板 + 调用 Agent 执行
└──────┬───────┘
       ↓
     返回结果

Resolve 阶段

从 mate_skill 表加载技能定义，解析 SKILL.md 的 frontmatter 和 Markdown 正文。

Security 阶段

检查当前用户是否有权调用该技能，验证参数合法性。

Dependency 阶段

如果技能声明了 dependencies，递归加载依赖的技能。加载 tools 中声明的工具。

Availability 阶段

确认所有依赖的工具都已启用且可用。如果有不可用的工具，返回错误提示。

Execute 阶段

将参数值填入模板
将渲染后的 Markdown 作为提示词发送给 Agent
Agent 使用分配的工具执行任务
收集并返回结果

技能管理 API

bash

# 查询所有技能
curl http://localhost:18088/api/v1/skills \
  -H "Authorization: Bearer <token>"

# 查询单个技能
curl http://localhost:18088/api/v1/skills/1 \
  -H "Authorization: Bearer <token>"

# 启用技能
curl -X PUT http://localhost:18088/api/v1/skills/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"enabled": true}'

# 删除技能（仅 custom 类型）
curl -X DELETE http://localhost:18088/api/v1/skills/1 \
  -H "Authorization: Bearer <token>"

下一步

工具系统 — 技能依赖的工具
MCP 协议 — MCP 类型技能的来源
Agent 引擎 — 技能如何被 Agent 使用

技能系统

核心概念

SKILL.md 协议

基本结构

Frontmatter 字段说明

参数定义

技能类型

builtin — 内置技能

custom — 自定义技能

mcp — MCP 技能

Skill Workspace（技能工作区）

启动时自动同步

配置

技能市场（SkillMarket）

功能

创建自定义技能

通过 UI 创建

通过 API 创建

技能模板示例

周报生成器

API 文档生成器

技能运行时管道

Resolve 阶段

Security 阶段

Dependency 阶段

Availability 阶段

Execute 阶段

相关工具

SkillFileTool

SkillScriptTool

技能管理 API

下一步

技能系统 ​

核心概念 ​

SKILL.md 协议 ​

基本结构 ​

Frontmatter 字段说明 ​

参数定义 ​

技能类型 ​

builtin — 内置技能 ​

custom — 自定义技能 ​

mcp — MCP 技能 ​

Skill Workspace（技能工作区） ​

启动时自动同步 ​

配置 ​

技能市场（SkillMarket） ​

功能 ​

创建自定义技能 ​

通过 UI 创建 ​

通过 API 创建 ​

技能模板示例 ​

周报生成器 ​

API 文档生成器 ​

技能运行时管道 ​

Resolve 阶段 ​

Security 阶段 ​

Dependency 阶段 ​

Availability 阶段 ​

Execute 阶段 ​

相关工具 ​

SkillFileTool ​

SkillScriptTool ​

技能管理 API ​

下一步 ​

技能系统

核心概念

SKILL.md 协议

基本结构

Frontmatter 字段说明

参数定义

技能类型

builtin — 内置技能

custom — 自定义技能

mcp — MCP 技能

Skill Workspace（技能工作区）

启动时自动同步

配置

技能市场（SkillMarket）

功能

创建自定义技能

通过 UI 创建

通过 API 创建

技能模板示例

周报生成器

API 文档生成器

技能运行时管道

Resolve 阶段

Security 阶段

Dependency 阶段

Availability 阶段

Execute 阶段

相关工具

SkillFileTool

SkillScriptTool

技能管理 API

下一步