技能开发指南

技能(Skill)是 Skills Agent 的能力单元,每个技能封装了特定领域的系统提示词、工具权限和生命周期钩子。

它的核心目的只有一个:把一类专业能力的"知识 + 行为规则 + 可用工具"打包成一个可被发现、可被执行、可被复用的独立单元,让 Agent 在合适的时机自动启用它。

没有技能时,Agent 只能依赖一个巨型的系统提示词”硬记”所有能力:能力越多,提示词越臃肿,意图越容易混淆,维护和扩展都举步维艰。

# ✅ 一份声明式技能:意图清晰、边界分明、运行时按需加载
name: code-review
description: Review code changes for bugs, security issues, and style violations
version: "1.0.0"
triggers:
  keywords: [review, 审查]
tools: [file_read, web_search]
permissions: [read_filesystem]

Skills Agent

1. 概述

技能是 Skills Agent 的基本能力单元。它把”某个领域该怎么思考、能用哪些工具、在加载/出错时做什么”全部收敛在一个文件里,让 Agent 的能力从”写死在系统提示词里”变成”按需插拔的模块”。

一个设计良好的技能应当满足三点:

特性 说明
自包含 提示词、工具、钩子都在技能内,不依赖外部隐式状态
可发现 通过关键词、文件路径或上下文触发,运行时自动匹配
可隔离 只声明自己真正需要的工具与权限,遵循最小权限原则

2. 快速开始

技能有两种写法,按复杂度选择:简单技能用 YAML 声明式,复杂技能用 Python 类。

2.1 方式一:YAML 声明式(推荐简单技能)

在 skills/<name>/skill.yaml 中创建即可,无需写任何代码:

name: my-first-skill
description: 帮助用户完成某项任务的技能
version: "0.1.0"
author: your-name

triggers:
  keywords:
    - keyword1
    - 中文关键词
  context:
    - git_diff
    - code_review

tools:
  - file_read
  - web_search

dependencies: []
permissions:
  - read_filesystem

2.2 方式二:Python 类(推荐复杂技能)

当技能需要自定义钩子、动态逻辑或专属工具时,在 skills/<name>/skill.py 中继承 Skill:

from src.skills import Skill
from src.models import SkillTrigger

class MySkill(Skill):
    name = "my-skill"
    description = "What this skill does"
    version = "0.1.0"

    triggers = SkillTrigger(
        keywords=["keyword1", "关键词"],
        context_hints=["git_diff"],
    )

    dependencies = []
    required_permissions = ["read_filesystem"]

    def system_prompt(self) -> str:
        return (
            "You are an expert at [domain]. Follow these rules:\n"
            "1. Rule one\n"
            "2. Rule two\n"
        )

    def tool_names(self) -> list[str]:
        return ["file_read", "web_search"]

    async def on_load(self, context):
        """技能加载时执行一次"""
        pass

    async def on_unload(self, context):
        """技能卸载时清理"""
        pass

    async def on_error(self, error, context):
        """处理执行中的错误"""
        return "Recovery message or None to propagate"

两种写法如何选择?

  • 技能只是”一段提示词 + 几个工具”,没有自定义逻辑 → 用 YAML,声明即生效。
  • 技能需要在加载时初始化、在出错时降级、要挂专属工具 → 用 Python 类,逻辑更自由。

3. 技能定义规范

无论用哪种写法,一份完整的技能定义都离不开下面这些字段。

3.1 name(必填)

  • 格式:kebab-case(小写字母 + 数字 + 连字符)
  • 唯一,不可与已有技能重名
  • 示例:code-review、deploy-check、api-doc-gen

3.2 description(必填)

  • 一句话描述技能功能
  • 用于技能列表展示和 LLM 意图分类
  • 示例:"Review code changes for bugs, security issues, and style violations"

3.3 triggers(必填)

定义技能何时被激活。三种触发方式按优先级排列:

方式 字段 说明 示例
关键词 keywords 在用户输入中匹配 ["review", "审查"]
Glob 模式 patterns 文件路径匹配 ["*.diff", "*.patch"]
上下文 context_hints 会话上下文中的标记 ["pull_request"]

3.4 tools(可选)

技能需要的工具列表。只声明工具名,Agent 运行时自动绑定:

  • file_read — 读取文件
  • file_write — 写入文件
  • web_search — 搜索网页
  • shell_exec — 执行命令
  • http_request — HTTP 请求
  • clock — 获取时间

最小权限原则

工具不是”声明得越多越安全”,而是”用得到才声明”。无关工具一旦声明,就扩大了技能的攻击面。只读工具永远优于写工具,写工具必须配合权限声明。

3.5 system_prompt(Python 类必填)

当技能激活时,这段内容会被注入到 LLM 的系统提示词中。写好它的核心原则有四个:

  1. 角色定义:明确技能扮演的角色
  2. 规则约束:列出具体的行为规则
  3. 输出格式:指定期望的输出结构
  4. 边界说明:明确技能不做什么

3.6 hooks(可选)

生命周期钩子让技能在关键节点介入运行:

on_load    → 技能加载到会话时
on_execute → 技能执行前(可用于 enrich context)
on_error   → 执行出错时(返回恢复消息或 None)
on_unload  → 技能卸载时清理资源

4. 最佳实践

4.1 Prompt 工程

系统提示词要”说清规则”,而不是”笼统地提一句”。对比两种写法:

✅ 好:
"You are a code review expert. Check for:
 1. Logic errors (off-by-one, null dereference)
 2. Security issues (SQL injection, XSS)
 3. Performance (N+1 queries, unnecessary allocation)
 Report as: [severity] file:line — description"

❌ 差:
"Review the code and tell me if there are problems."

4.2 工具选择

  • 只声明技能实际需要的工具(最小权限原则)
  • 读操作优先于写操作
  • shell_exec 只在绝对必要时使用,并指定 timeout

4.3 错误处理

  • 始终实现 on_error 提供优雅降级
  • 返回人类可读的错误恢复消息
  • 不要吞掉错误而不记录

别让错误静默消失

on_error 返回 None 表示把异常向外传播。如果你直接吞掉异常又不记录,问题会像回调地狱里的 if (err) 被漏写一样——表面风平浪静,实则已经偏离预期。

4.4 技能粒度

  • 过细:每个小功能一个技能 → 路由混乱
  • 过粗:一个技能做所有事 → 失去模块化优势
  • 合理:一个技能覆盖一个清晰的领域边界

4.5 测试技能

技能写完后应当有对应的测试,覆盖”能否被发现”和”关键词能否命中”两条核心链路:

# tests/test_my_skill.py
import pytest
from src.skills.registry import skill_registry
from src.skills.loader import SkillLoader

async def test_skill_discovery():
    loader = SkillLoader()
    count = await loader.scan_and_register()
    assert count > 0

def test_skill_keyword_match():
    matches = skill_registry.match_by_keyword("帮我审查这段代码")
    assert "code-review" in matches

5. 技能示例

参考项目中的示例技能,作为你动手写第一个技能的蓝本:

  • skills/example_skill.py — Code Review 技能的完整 Python 实现

先想清边界,再写提示词

一个技能只解决一个领域的问题,提示词里的规则也要对应这个边界,避免贪多。

触发条件宁窄勿滥

关键词太宽泛会导致技能被误唤醒,抢占更合适的技能。先用窄条件跑通,再按需放宽。

工具与权限配对声明

每声明一个工具,就要想清楚它对应的权限是否必要,从源头收敛风险。

钩子要可重入

on_load 可能在同一会话里被多次调用路径触发,初始化逻辑要幂等,避免重复副作用。


附:核心字段速查

字段 必填 作用
name 是 唯一标识符,kebab-case
description 是 一句话描述,驱动意图分类
triggers 是 关键词 / 路径 / 上下文,决定何时激活
tools 否 技能可使用的工具名列表
system_prompt 类必填 激活时注入的提示词
permissions 否 技能所需的权限声明
hooks 否 加载 / 执行 / 出错 / 卸载的生命周期钩子

一句话总结:技能把”专业能力”封装成了可插拔的模块——声明式写法负责简单场景,Python 类负责复杂逻辑;而清晰的边界、精准的触发和最小化的权限,才是写好一个技能的关键。