从addyosmani的Agent Skill模板学写可复用的AI工程能力

上周GitHub上一个叫 addyosmani/agent-skills 的项目一天涨了5.9万星。作者Addy Osmani是Chrome工程经理，他放出了一套“生产级工程技能”的SKILL定义，让AI coding agent能直接调用。

很多人第一反应是“又一个prompt模板合集”。但细看之后我发现，这套东西的价值不在于具体内容，而在于结构设计——它把“让agent做一件事”从临时对话固化成了可复用、可组装、可版本化的能力单元。

这篇文章我把它拆开，给出一套你可以直接复用的模板，附带实际案例和组合技巧。读完你不仅能写自己的skill，还能明白为什么这样写比单纯写prompt有效。

developer coding with AI terminal skill files

这个Skill解决什么具体问题

先问你一个场景：你每天都让AI帮你做代码审查、写单元测试、优化性能。每次你都要把上下文、要求、输出格式重新说一遍。即使你保存了prompt，换一个项目、换一个agent，又得调。

更关键的是，agent没有“能力边界”。你让它“审查这段代码”，它可能跑题去讲设计模式，也可能只给一句“看起来不错”。你希望的是：审查只关注安全、内存泄漏、并发错误三个维度；输出必须是表格+建议优先级；且不修改原始文件。

agent-skills 的解决思路是：把这种固定操作定义成一个”Skill” —— 一个包含触发条件、执行脚本、输出规范的文件夹。Agent检测到匹配条件时自动加载这个Skill，或者由用户明确调用。

个人观点：这种做法本质上是把AI agent从“对话式助手”升级为“可编程工具库”。每个skill就像一个微服务，有明确的接口、输入、输出。组合起来就能处理复杂工作流。这比单纯依赖模型记忆要可靠得多。

Skill的触发条件和适用场景

一个skill必须有明确的触发方式。项目里常见两种：

  • 文件匹配触发：比如用户打开一个.py文件时，自动激活“Python代码审查”skill。
  • 命令触发：用户在聊天中输入 /review 或 !测试 等前缀，执行对应skill。

适合用skill封装的任务特征：

  1. 重复性高 —— 你每周做3次以上的操作
  2. 输出格式固定 —— 比如报告、表格、结构化数据
  3. 需要多步执行 —— 先分析静态代码，再运行测试，最后汇总
  4. 需要领域知识 —— 如安全审计中的OWASP规则，可以直接写死在脚本里，不用每次重复教AI

反之，一次性的创意任务（“写一首诗”）就不适合做skill。

完整Skill结构（SKILL.md模板）

一个标准的skill文件夹包含：

text
1 2 3 4 5 6 
skills/
  your-skill-name/
    SKILL.md      # 描述文件（必须）
    execute.sh    # 执行脚本（可选）
    rules/        # 规则文件（可选）
    examples/     # 示例输入输出（可选）

核心是SKILL.md。下面是一个可直接复用的模板：

markdown
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 
---
name: "代码审查 (Code Review)"
version: "1.0.1"
description: >
  对选中代码进行安全、性能、可维护性三个维度的审查，
  输出带严重等级的表格。
author: "your-name"
triggers:
  - type: file
    pattern: "*.py"
  - type: command
    pattern: "/review"
inputs:
  - name: code_path
    description: "代码文件路径或粘贴的代码块"
    required: true
outputs:
  - format: markdown_table
    columns: ["问题类型", "严重等级", "行号", "描述", "建议修复"]
steps:
  - action: analyze
    description: "静态分析代码结构，识别安全漏洞、内存泄漏、反模式"
    tool: "gpt-4o"
    prompt: |
      你是一位资深代码审查专家。请分析以下{{code}}，按三个维度审查：
      1. 安全问题（SQL注入、XSS、敏感信息泄露等）
      2. 性能问题（重复计算、不必要的IO、内存泄漏等）
      3. 可维护性问题（魔法数字、过长函数、缺乏注释等）
      输出markdown表格：列名为“问题类型|严重等级|行号|描述|建议修复”。
      严重等级使用：Critical, High, Medium, Low。
  - action: summarize
    description: "汇总总共发现的问题数量与分类"
    prompt: |
      基于上一步分析结果，给出一个一句话总结，以及建议优先处理的3个问题。
---

关键字段解析：

  • triggers：定义何时自动激活。文件匹配用glob pattern，命令匹配用正则或固定字符串。
  • inputs：声明这个skill需要哪些参数。让agent可以提示用户补充。
  • outputs：定义输出格式，减少agent自由发挥的空间。
  • steps：多步骤执行逻辑。每步可以指定不同的prompt和工具。这是关键——它把一次推理拆成多个原子步骤，每步有小目标，最终结果更可控。

实际案例演示

我们对比两个prompt，让AI对一段Python代码做安全审查。

差Prompt：

text
1 2 3 4 5 
审查这段代码的安全性：
def login(username, password):
    query = "SELECT * FROM users WHERE name='" + username + "' AND pass='" + password + "'"
    db.execute(query)
    return True

AI可能会输出：“这段代码有SQL注入风险，你应该使用参数化查询。” 然后结束。没有行号、没有严重等级、没有其他维度的检查。

好prompt（使用上面的skill模板）：

text
1 2 3 4 5 6 7 
激活skill：代码审查
code_path: inline
code:
def login(username, password):
    query = "SELECT * FROM users WHERE name='" + username + "' AND pass='" + password + "'"
    db.execute(query)
    return True

AI按照skill定义输出：

问题类型 严重等级 行号 描述 建议修复
安全 Critical 2-3 SQL注入：直接拼接用户输入到查询字符串 使用参数化查询或ORM，如cursor.execute("SELECT * FROM users WHERE name=%s AND pass=%s", (username, password))
安全 High 1 密码明文传输：函数未提示使用HTTPS或哈希 建议至少对密码进行哈希比对，并强制TLS传输
安全 Medium 1 缺乏输入验证 对username和password进行长度和字符限制
可维护性 Low 1 函数未包含类型注解和文档 建议添加类型提示和dosctring

总结：共发现4个问题，优先处理SQL注入和密码明文问题。

为什么好？

  • 通过steps中的第一个prompt，我们明确指定了审查的三个维度和输出列的格式，agent没有自由发挥空间。
  • 通过outputs强制表格输出，方便后续自动解析或人读。
  • 通过triggers，用户只需要用简单的命令（/review）就能激活，不需要每次写长prompt。
  • 多步骤中的第二个step自动生成总结，不用用户再追问。

复用和组合技巧

单个skill很好，但真正强大的用法是组合。比如你想执行“安全审计 + 生成测试 + 更新文档”三个任务，可以定义一个新skill调用三个子skill：

markdown
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 
---
name: "新功能上线前检查 (Pre-release Check)"
version: "1.0.0"
triggers:
  - type: command
    pattern: "/release-check"
steps:
  - action: call_skill
    skill: "安全审查"
    params:
      code_path: "selected"
  - action: call_skill
    skill: "单元测试生成"
    params:
      framework: "pytest"
  - action: call_skill
    skill: "文档更新"
    params:
      output_file: "CHANGELOG.md"
---

这样，一次命令完成整个流程。实际的agent需要支持跨技能调用，目前Cline、Cursor等工具已经开始支持这种嵌套结构。

参数复用技巧：

  • 使用环境变量（如 $PROJECT_ROOT）让skill在多个项目中通用。
  • 定义全局config.yml，里面放常用设置（如语言、代码风格）。Skill可以引用 @config 变量。

版本管理：

  • 每个skill有version字段，更新时标记版本号。
  • 用git管理skills目录，通过tag做版本控制。Agent可以识别不同版本的接口变化。

3个变体扩展：

变体1：针对JavaScript的代码审查skill
只需修改triggers的pattern为*.js和*.ts，改steps中的prompt为检查XSS、原型污染、未处理Promise等JS常见问题，其余结构不变。

变体2：自动化接口文档生成skill
输入：代码路径和HTTP端点列表。输出：OpenAPI 3.0 YAML。核心步骤：解析路由注解 -> 提取请求/响应 -> 生成YAML。

变体3：数据库迁移审查skill
输入：SQL迁移脚本。输出：检查是否包含DROP TABLE、ALTER COLUMN等破坏性操作，是否缺少IF EXISTS，并给出是否安全的建议。

multiple skill files in folder structure

个人观点：这种结构化skill最大的敌人是过度设计。不要一开始就定义20个字段，从最简单的“描述+触发+单步骤prompt”开始，等确实需要多步骤或参数化再扩展。另外，触发条件不要写得太宽泛，比如pattern: "*"会让agent几乎所有上下文都激活这个skill，反而造成干扰。精准匹配，小粒度，是我推荐的最佳实践。

总结

addyosmani/agent-skills项目提供的不是“魔法prompt”，而是一套能力封装标准。用这套标准，你可以：

  • 把高频任务变成可复用的skill
  • 通过触发条件和参数化让agent在正确时间自动加载
  • 通过多步骤拆解保证输出质量和可控性
  • 通过组合构建更复杂的工作流

下一步建议：把你日常工作流中最常做的3件事情写成skill，放到.ai/skills/目录下，然后让agent直接调用。你会立刻感受到“一次定义，多次使用”的效率提升。

（如果你有更好的skill设计思路，欢迎在评论区分享，我会整理成后续文章。）