如何写一个 AI Skill

什么是 Skill？

Skill 是一种模块化、自包含的扩展包，用于增强 AI Agent 的能力。

如果你用过 VS Code 的插件、Vim 的 Plugin，或者 ChatGPT 的 GPTs，Skill 的思路与之类似。区别在于 Skill 的核心是"给 AI 的上下文"，而不是传统意义上的"可执行代码"。

Skill 本质上是：给另一个 AI Agent 实例提供专业知识、工作流程和工具集成的"入职手册"。

一个典型的 Skill 可以：

提供专业领域工作流（比如：怎么生成 PDF 报告、怎么操作 Excel）
集成特定平台/服务（比如：腾讯内网 KM、工蜂代码库）
封装可复用脚本（比如：图片处理、数据转换）
注入领域知识（比如：公司代码规范、数据库 schema）

Skill 的目录结构

每个 Skill 是一个目录，结构如下：

my-skill/
├── SKILL.md # 必须，技能核心入口
├── scripts/ # 可选，可执行脚本
│   └── process.py
├── references/ # 可选，参考文档（按需加载）
│   └── api_docs.md
└── assets/ # 可选，输出用资源
    └── template.xlsx

SKILL.md —— 一切的起点

SKILL.md 是唯一的必需文件，由两部分组成：

1. YAML frontmatter（元数据）

---
name: my-skill
description: |
  这个 Skill 用于处理 XXX 任务。当用户需要...时触发使用。
  支持功能：(1) ... (2) ... (3) ...
---

description 非常关键——它是 AI 判断"是否应该使用这个 Skill"的依据。写得越清晰，触发越准确。

2. Markdown 指令（工作流）

这里写的是"给 AI 看的说明书"，详细描述完成任务的步骤、注意事项、如何使用脚本/资源等。

三类可选资源

目录	作用	典型内容
`scripts/`	可执行脚本	PDF 处理、数据转换、API 调用等重复性代码
`references/`	参考文档（按需读入上下文）	API 文档、数据库 schema、业务规则
`assets/`	输出用资源（不读入上下文）	模板文件、图片、字体、样板代码

核心设计原则

原则一：简洁是王道

Skill 加载后会占用 AI 的上下文窗口（Context Window），这是稀缺资源。

问自己：这条信息是 AI 本来就知道的吗？ 如果是，就不必写。只写 AI 不知道的、领域特有的、容易出错的内容。

                ✅ 应该写 vs ❌ 不必写
                ✅ 数据库 schema、公司 API 的特殊鉴权方式、特定格式要求
❌ Python 基础语法、通用的 REST API 调用方式、AI 已知的通用知识

            

原则二：渐进式披露（Progressive Disclosure）

Skill 有三层加载机制，越深越按需加载：

层级	内容	何时加载
第一层	`name` + `description`	始终在上下文中（~100 词）
第二层	`SKILL.md` 正文	Skill 被触发时
第三层	`scripts/`、`references/`、`assets/`	AI 判断需要时才读取

这种设计让 Skill 在不被使用时几乎不消耗上下文，被触发后才按需展开。实践建议：把详细的 API 文档放在 references/api.md，在 SKILL.md 里只写一句"详见 references/api.md"。

原则三：匹配自由度

场景	推荐方式
多种方法都可行，让 AI 灵活决策	自然语言描述（高自由度）
有最佳路径，但允许变体	伪代码 + 参数（中自由度）
操作脆弱、必须精确执行	具体脚本（低自由度）

完整开发流程：手把手示例

以创建一个 web-clipper Skill 为例，演示完整流程。目标：给 AI Agent 一个 URL，自动提取正文并生成结构化摘要卡片。

Step 1：理解用例

在动手前，先明确用户会怎么用这个 Skill：

"帮我总结一下这篇文章：https://example.com/article"
"把这个链接的内容提取出来，给我一份 200 字摘要"
"这个网页讲了什么？"

用例清晰后，确定 Skill 需要支持：提取网页正文 + 生成摘要 + 可选结构化输出。

Step 2：规划可复用资源

分析每个用例的执行路径，确认哪些内容值得沉淀：

分析用例 → 识别重复代码 → 规划 scripts/ → 规划 references/ → 规划 assets/

本例的规划产出：

scripts/fetch_page.py —— 负责抓取和清洗正文（每次都要重写，值得固化）
references/output_format.md —— 约定摘要卡片的输出格式

Step 3：初始化 Skill

使用内置工具初始化 Skill 目录：

python scripts/init_skill.py web-clipper --path ./my-skills/

这会自动生成标准目录结构，包含 SKILL.md 模板和示例文件。删掉不需要的示例文件，开始填充内容。

Step 4：实现 Skill 内容

scripts/fetch_page.py

#!/usr/bin/env python3
"""从 URL 提取网页正文"""

import sys
import requests
from bs4 import BeautifulSoup

def fetch_content(url: str) -> str:
    headers = {"User-Agent": "Mozilla/5.0"}
    resp = requests.get(url, headers=headers, timeout=10)
    resp.raise_for_status()

    soup = BeautifulSoup(resp.text, "html.parser")

    # 移除干扰元素
    for tag in soup(["script", "style", "nav", "footer", "header"]):
        tag.decompose()

    # 优先提取 article 标签
    article = soup.find("article") or soup.find("main") or soup.body
    text = article.get_text(separator="\n", strip=True)

    # 合并多余空行
    lines = [l for l in text.splitlines() if l.strip()]
    return "\n".join(lines)

if __name__ == "__main__":
    url = sys.argv[1]
    print(fetch_content(url))

references/output_format.md

# 摘要卡片输出格式

## 📄 [文章标题]

**来源**：[域名]
**核心主题**：一句话概括

### 主要观点
1. ...
2. ...
3. ...

### 关键结论
> 引用原文中最重要的一句话

**适合人群**：[目标读者]
**阅读时长**：约 X 分钟

SKILL.md

---
name: web-clipper
description: |
  网页内容提取与摘要生成。当用户提供 URL 并希望了解网页内容、
  提取正文、生成摘要卡片时使用。
  支持：(1) 提取任意网页正文 (2) 生成结构化摘要卡片 (3) 内容问答
---

# Web Clipper

从 URL 提取网页内容并生成摘要。

## 工作流程

1. **提取正文**：运行 `scripts/fetch_page.py <url>`
2. **生成摘要**：基于提取内容，按 `references/output_format.md` 格式输出
3. **内容问答**：如果用户有追问，基于已提取内容直接回答

## 注意事项

- 遇到反爬限制（403/429）时，告知用户并建议手动粘贴内容
- 正文超过 10000 字时，只取前 8000 字，并说明内容已截断
- 不支持需要登录的页面，告知用户

Step 5：打包 Skill

python scripts/package_skill.py my-skills/web-clipper/

脚本会自动验证 SKILL.md 格式、frontmatter 字段、目录结构，通过后打包成 web-clipper.skill 文件（本质是 zip，改了后缀）。

Step 6：安装与迭代

把 .skill 文件安装到 AI Agent，然后在真实场景中使用。迭代时关注：

AI 是否准确触发了这个 Skill？（没有则优化 description）
脚本是否在各种情况下都能正常工作？
输出格式是否符合预期？

实战建议

description 写法决定触发准确率

description 里要同时包含功能描述和触发场景，两者缺一不可：

# ❌ 太简短，AI 难以判断何时使用
description: 网页内容提取工具

# ✅ 清晰说明功能和使用时机
description: |
  网页内容提取与摘要。当用户提供 URL 并希望：
  了解网页内容、总结文章、提取正文、生成摘要卡片时触发。
  支持任意公开网页，不支持需要登录的页面。

脚本要实际测试

写完脚本后必须跑一遍，确认输出符合预期。特别注意：

依赖库是否已安装
边界情况（空页面、超时、编码问题）
输出格式是否和 SKILL.md 描述一致

大文件放 references，不要堆在 SKILL.md

如果有详细的 API 文档、数据库 schema、业务规则，统统放到 references/ 目录里，在 SKILL.md 里只写索引和加载时机。

不是所有内容都需要脚本

AI 本身有很强的推理和生成能力。只在以下情况才写脚本：

代码每次都一样，反复生成浪费 token
操作需要确定性（文件处理、API 调用）
脚本的正确性比 AI 生成的更可靠

总结

步骤	核心产出
理解用例	明确触发场景和功能边界
规划资源	确定需要哪些脚本/文档/资源
初始化	生成标准目录结构
实现内容	编写 SKILL.md + 脚本 + 参考文档
打包	`.skill` 文件，可分发安装
迭代	在真实使用中持续优化

Skill 的设计哲学很简单：把重复的、领域特有的、AI 容易出错的部分结构化沉淀下来，让每次任务执行都站在已有积累的肩膀上。

好的 Skill 不会试图替代 AI 的思考，而是把 AI 的注意力集中在真正需要判断的地方。

有问题或建议？欢迎在评论区交流。