1. 这个 Skill 解决什么具体问题
如果你写过 AI 代理（Agent），一定遇到过这些场景：
- 同一个代码审查提示词，每次都要重写一遍
- 想让代理执行“先查文档再写代码”的流程，但顺序总乱
- 团队里不同项目用到相同的能力（如API封装、日志分析），但没有统一标准
Skill 就是解决方案：将一次性的 prompt 升级为可复用的能力模块，带有明确的触发条件、输入输出格式和上下文注入逻辑。就像把散装的螺丝刀、扳手整理成工具箱，需要哪个直接取用。
使用 Skill 后，你的代理不再是“你问我答”的聊天窗口，而是能根据任务自主调用能力的队友。每个 Skill 就是一个独立的任务处理器，你可以像拼乐高一样把它们组合成复杂工作流。
2. Skill 的触发条件和适用场景
触发条件通常有两种：
- 显式触发：用户明确说“帮我对这段代码做代码审查” → 对应“代码审查” Skill
- 隐式触发：系统检测到新提交了代码 → 自动触发“代码审查” Skill
适用场景很广，只要任务具有重复性、可标准化、输入输出格式明确的特点，就应该封装成 Skill。典型案例：
- 代码审查 / 重构建议
- API 接口文档生成
- 日志异常检测与报告
- 数据库迁移脚本生成
- 依赖包版本检查与升级建议
什么时候不该用 Skill？当任务需要极高创造性、输入极度模糊、或一次性探索性任务时，直接对话更灵活。Skill 适合需要“稳定输出”的场景。
3. 完整 Skill 结构（SKILL.md 示例）
一个 Skill 通常以一个文件夹存在，核心是 SKILL.md 文件，里面定义了技能的所有元信息。下面是我推荐的最小化结构（也是 multica 项目采用的方式）：
my-skill/
├── SKILL.md # 技能定义：触发词、描述、输入输出
├── prompt.md # 主要AI提示词（可选，也可以直接在SKILL.md里）
├── tools/ # 工具函数（如API调用、文件读写）
│ └── fetch.js
└── examples/ # 示例输入输出，用于测试
└── input.jsonSKILL.md 完整模板（可直接复制使用）：
# Skill: Code Review Reviewer
## 描述
对提交的代码进行同行评审，输出结构化报告：覆盖率、代码规范、潜在bug、改进建议。
## 触发关键词
["review", "code review", "代码审查"]
## 输入格式
```yaml
diff: string # git diff 内容, 或完整文件内容
language: string # 编程语言 (如 python, javascript)
context: string # 项目背景（可选）输出格式
summary: string # 整体评价
issues: # 问题列表
- line: int
severity: enum[low, medium, high]
message: string
suggestion: string
score: int # 0-100 分
approved: boolean # 是否允许合并系统提示词 (system prompt)
你是一个精通 {{ language }} 的高级代码审查员。
严格按照输出格式返回 JSON，不要额外解释。
步骤
- 分析输入代码/ diff
- 检查语法、逻辑、安全、性能、可读性
- 按照输出格式生成报告
示例
// input
{
"diff": "+function add(a,b) { return a+b }",
"language": "javascript"
}
// output
{
"summary": "简单函数，无问题",
"issues": [],
"score": 95,
"approved": true
}
**为什么这样写有效？**
- 明确的输入输出格式：降低 AI 理解偏差，让输出可被下游程序直接消费
- 示例：few-shot 样例，减少 CoT 漂移
- 步骤：结构化思维链，引导 AI 按顺序处理，而不是跳步
- 触发关键词：避免无关对话唤醒 Skill
## 4. 实际案例演示：差 Prompt vs 好 Prompt
**差的 Prompt（直接聊天模式）**
```text
请帮我审查这段 Python 代码：def foo(): pass效果：AI 可能随意输出一段文字，有时给JSON有时不给，格式不统一，无法自动化。
好的 Skill 封装
# SKILL.md 内容（使用上面的模板）
触发词: ["review", "review python"]
输入格式:
code: string
language: "python"
输出格式:
issues: list[{ line, severity, message }]
score: int
approved: bool
系统提示词:
你是严格的 Python 代码审查专家。
严格按照 JSON 格式返回。
步骤:
1. 读取 code 字段
2. 识别所有函数/类定义
3. 检查 PEP8 规范
4. 检查安全漏洞（SQL注入、eval等）
5. 输出 JSON调用后返回：
{
"issues": [
{ "line": 1, "severity": "low", "message": "函数名 foo 不符合 snake_case", "suggestion": "改为 foo_bar" }
],
"score": 85,
"approved": false
}对比差在哪？
- 差 prompt 没有格式约束，你无法程序化处理返回结果
- 好 Skill 定义了输入输出，并强制 JSON 输出，可以集成到 CI/CD 流程中
- 好 Skill 加入了步骤和示例，AI 表现更稳定
5. 复用和组合技巧
技巧1：链式组合
前一个 Skill 的输出作为后一个 Skill 的输入。例如：
- Skill A：从代码仓库提取变更文件列表 → 输出 JSON
- Skill B：代码审查（输入 JSON 中的 diff 字段）→ 输出审查报告
- Skill C：根据审查报告自动创建 GitHub Issue
技巧2：条件分支
根据 Skill 输出中的 approved 字段，决定是否触发下一个 Skill。例如：
- 如果
approved: false，自动触发“代码修复建议” Skill - 如果
approved: true，触发“合并请求批准” Skill
技巧3：参数化 Skill
通过环境变量或配置注入不同上下文，让同一个 Skill 适配不同项目。例如：
context: "project A coding standards"vscontext: "project B conventions"- 在 system prompt 里用
{{ context }}占位符，运行时替换
实际代码片段（伪代码）
// 组合调用示例
async function runWorkflow(agent, task) {
const result1 = await agent.invokeSkill('list-changed-files', task.repo);
const files = JSON.parse(result1.output);
for (const file of files) {
if (file.extension === '.py') {
const review = await agent.invokeSkill('code-review-python', {
code: file.content,
language: 'python'
});
if (!review.output.approved) {
await agent.invokeSkill('create-github-issue', {
repo: task.repo,
title: `Review failed: ${file.filename}`,
body: review.output.issues
});
}
}
}
}扩展变体
- 日志分析 Skill：输入日志文本，输出按时间线整理的关键事件 + 异常级别
- SQL 生成 Skill：输入自然语言描述，输出 SQL 查询和 explain 分析
- Docker 合规 Skill：输入 Dockerfile，输出是否遵循 best practices 和优化建议
每个变体只需修改 SKILL.md 中的输入输出示例、system prompt 里的角色描述、以及步骤细节，核心结构完全复用。
写在最后
Skill 的本质是把 AI 从“临时工”变成“正式员工”——它知道自己的职责、怎么做、产出什么格式。别再每次手动写 prompt 了，从今天开始把你最常用的 3 个任务封装成 Skill，你的代理就会从“有点笨”变成“靠谱队友”。
如果你已经在用 multica 或类似平台，直接套用上面的模板；如果你是自己写代理框架，也可以按这个思路定义你的 Skill 文件。
