ARTICLE · 1086211
AI Skills 开发完全指南
AI Skills 开发完全指南
从触发机制到性能优化，从测试到安全，覆盖 Skill 开发的完整知识体系。以个人月度消费为例，CodeBuddy驱动，串起来skill开发流程。预计阅读时间：约 25 分钟
一、Skill 核心概念
1.1 什么是 Skill
Skill 是一个领域扩展包，为 AI 助手注入特定领域的专业知识、标准化工作流（SOP）和可执行工具。它不是单一脚本，而是一个有结构的软件包：
Skill = 元数据层（SKILL.md） + 引擎层（scripts/） + 资源层（assets/ + references/） + 版本管理核心设计理念：让 AI 继承你的领域知识。当你编写一个 Skill，本质上是在做一个知识工程——把隐性的领域经验显式化为可被 AI 读取和执行的规范文档。
1.2 文件结构深度解析
skill-name/├── SKILL.md # 入口说明书——AI 每次触发 Skill 时最先读取├── README.md # 给人看的文档（快速开始、FAQ）├── .gitignore│├── scripts/ # 引擎层：可执行脚本│ ├── version.json # 版本元数据（SemVer + 远程更新 URL）│ ├── check_update.py # 自动更新检查模块│ └── *.py / *.sh # 核心业务脚本│├── assets/ # 资源层（机器消费）│ ├── templates/ # Excel 模板、HTML 模板│ ├── fonts/ # 字体文件（避免宿主环境缺失）│ └── data/ # 静态数据（城市码表、节假日表等）│└── references/ # 知识层（人 + AI 共同消费）├── category_rules.md # 分类规则词典├── data_schema.md # 中间格式 JSON Schema├── platform_notes.md # 各数据源注意事项└── known_issues.md # 已知问题清单
各目录角色：
SKILL.md | |||
scripts/ | |||
assets/ | |||
references/ |
区分 assets/ 与 references/：
assets/放的是「代码运行时需要的文件」——模板被 openpyxl 加载、字体被渲染引擎引用 references/放的是「AI 理解领域时查阅的文档」——分类规则让 AI 知道某笔交易归入哪类
1.3 Skill 的生命周期
安装 触发 执行 更新 退役───→ ──────────→ ───────────────→ ───────────→ ─────────→zip/Git description AI→SOP→Scripts version.json 移除目录部署 文本匹配 逐步执行 SemVer 比较 清理配置
理解生命周期有助于设计每个阶段的关注点：
.gitignore | |
description文本质量、触发词精准度 | |
1.4 Skill 安装级别
Skill 支持四种安装级别，从底层到表层构成一个优先级覆盖链：
优先级（高→低）：项目级 > 用户级 > 插件级 > 内置级~/.codebuddy/skills/ | |||
<project>/.codebuddy/skills/ |
同名 Skill 覆盖规则：
高优先级级别的同名 Skill 会覆盖低优先级级别。例如：
项目级 spending-analysis v2.0 ← 实际生效（高优先级）用户级 spending-analysis v1.0 ← 被静默覆盖，不生效
这个机制的核心价值：在用户级放默认版本，在特定项目级放定制版本。
选择建议：
注意：内置级和插件级由平台管理，开发者自己编写的 Skill 通常落位在用户级或项目级。本文后续讨论以这两个级别为主。
二、Skill 触发机制
2.1 触发原理
Skill 的触发基于文本匹配：AI 在处理每个用户请求时，会将请求内容与所有已安装 Skill 的 description 字段进行语义匹配。匹配成功时，SKILL.md 的完整内容会注入到 AI 的上下文中。
用户输入 ”帮我分析上个月花了多少钱”│▼遍历所有 Skill 的 description 字段 ── 语义匹配│▼匹配到 spending-analysis：description 含”消费分析””月度消费””花了多少钱”等触发词│▼加载 SKILL.md 完整内容到上下文│▼AI 按照 SKILL.md 中定义的工作流（SOP）逐步执行
关键认知：description 字段是 Skill 的唯一入口。如果 description 写不好，Skill 可能永远不会被触发，或者在不该触发的时候被误触发。
2.2 description 写作技巧
description 需要同时回答三个问题：
这个 Skill 做什么（功能描述） 什么时候触发（触发条件） 用户可能怎么提问（自然语言触发词）
优秀示例（spending-analysis）：
description: >个人月度消费分析。从支付宝/微信/招商银行等多平台交易流水中解析、标准化、去重、分类打标，生成 Excel + Markdown 消费分析报告。触发词包括：”消费分析”、”月度消费”、”账单分析”、”交易流水”、”记账分析”、”消费报告”、”支出分析”、”看看花了多少钱”等。
拆解这个 description 的设计思路：
description 写作口诀：
一句领域 + 一句能力 + 一句输出 + 一串触发词
常见写作错误：
2.3 Skill 触发域控制
为什么要控制触发域：防止 Skill 被不该触发的请求误触发，也防止一个超大的 SKILL.md 在不需要的时候占用上下文窗口。这里的「触发域」指 Skill 对哪些用户输入作出响应，与 1.4 节讨论的「安装级别」（Skill 对哪些项目可见）是两个正交的概念。
触发域控制策略：
bills/{月份}/ 目录存在 |
触发域边界示意（以 spending-analysis 为例）：
┌── 触发域 ────────────────┐│ ”消费分析”、”月度消费” ││ ”账单分析”、”花了多少钱” ││ ”消费报告”、”支出分析” ││────────────────────────││ 能力域 ││ 支付宝 CSV / 微信 XLSX ││ 招行 PDF → 标准化 → 报告 │└────────────────────────┘↓┌── 非触发域 ─────────────┐│ ”投资收益分析” ││ ”股票持仓” ││ ”贷款计算” ││ ”汇率换算” │└────────────────────────┘
2.4 触发词设计进阶
触发词分层模型：
T1 精确触发词（高置信度）→ 用户明确要这个 Skill→ 例：”消费分析”、”账单分析”、”月度消费报告”T2 场景触发词（中置信度）→ 用户描述了典型使用场景→ 例：”花了多少钱”、”帮我记账”、”看月度支出”T3 模糊触发词（低置信度，需 AI 判断）→ 不显式列出，靠 AI 语义推理→ 例：”支付宝明细”、”微信账单整理”
实践建议：
T1 触发词必须显式写在 description 中 T2 触发词根据实际用户反馈持续补充 T3 不写入 description，而是通过 SKILL.md 中的「概述」部分让 AI 自行判断
三、SKILL.md 设计
3.1 元数据头规范
SKILL.md 以 YAML front matter 开头，这是 AI 读取的第一个信息块：
---name: skill-name# 唯一标识，建议用英文小写 + 连字符description: ># 多行文本用 > 或 |功能 + 场景 + 触发词version: 1.0.0# SemVer，与 version.json 保持一致---
name 命名规范：
spending-analysis | SpendingAnalysis | |
asset-allocation | asset | |
pdf-merger | adobe-pdf | |
meal-calorie-tracker | a-comprehensive-meal-and-diet-calorie-tracking-system |
3.2 工作流 SOP 设计
SOP（Standard Operating Procedure）是 SKILL.md 的核心内容，告诉 AI 应该按什么步骤执行。好的 SOP 设计遵循以下原则：
原则 1：步骤数量 3-5 步。太多 AI 容易遗漏，太少指令不够明确。spending-analysis 的 3 步设计是一个好的参照：
Step 1: 准备账单文件 → Step 2: 解析标准化 → Step 3: 生成报告原则 2：每步配可执行命令。AI 需要具体的、可直接复制执行的命令，不是含糊的自然语言描述。
# ✅ 好的写法python scripts/parse_bills.py --dir bills/2607# ❌ 差的写法使用解析脚本处理账单文件
原则 3：明确输入输出。每步结束后输出什么、下一步需要什么输入，必须在 SOP 中显式声明。
Step 1 输出 → 用户确认账单文件 → Step 2 输入Step 2 输出 → _normalized.json → Step 3 输入Step 3 输出 → 消费报告 exceld + .md
原则 4：覆盖异常路径。SOP不只是「正常情况下怎么做」，还要覆盖「出了问题怎么做」：
3.3 知识层设计
知识层是 SKILL.md 中分类规则、指标体系、已知限制等内容的统称。这些内容不直接可执行，但对 AI 做正确决策至关重要。
三层知识结构：
SKILL.md（内嵌核心规则）├── 分类体系（主分类 + 子分类 + 关键词映射）├── 去重策略（匹配规则 + 优先级 + 保留逻辑）└── 指标定义（计算公式 + 合理范围 + 消减建议）references/（外部参考文档）├── category_rules.md —— 完整分类词典（超出 SKILL.md 容纳量的部分）├── data_schema.md —— 中间格式 JSON 的字段定义和类型约束└── platform_notes.md —— 各数据源的特殊注意事项
何时放入 SKILL.md vs references/：
四、脚本引擎设计
4.1 管道式架构
核心设计模式：单向数据流管道。每个阶段只做一件事，通过标准化中间格式解耦。
原始文件（CSV/XLSX/PDF）│▼ Stage 1: parse_bills.py标准化 JSON（_normalized.json）│▼ Stage 2: classify_report.py├── 去重（三级匹配）├── 分类（规则链）├── 指标计算└── 报告生成（Excel + Markdown）
为什么用管道而非单体脚本：
中间格式设计要点：
{”date”: ”2026-08-01”, // ← 统一日期格式 YYYY-MM-DD”amount”: -35.80, // ← 正负号统一（支出为负）”merchant”: ”瑞幸咖啡”, // ← 商户名标准化（去公司后缀）”platform”: ”支付宝”, // ← 来源平台标记”payment_method”: ”花呗”, // ← 支付方式”original_category”: ””, // ← 保留原始分类（用于校验）”remark”: ”” // ← 保留原始备注（用于子分类）}
4.2 错误处理与容错
容错三原则：
不要 crash：任何单条数据出错都不应阻塞整个流程 记录问题：出错时输出足够多的诊断信息 可恢复：用户不需要从头开始
编码自动检测（实际案例）：
ENCODINGS = [”utf-8-sig”, ”utf-8”, ”gbk”, ”gb2312”, ”gb18030”]for enc in ENCODINGS:try:with open(filepath, ”r”, encoding=enc) as f:content = f.read()return contentexcept UnicodeDecodeError:continue# 所有编码都失败 → 输出诊断信息print(f”⚠️ 无法解码 {filepath}，尝试了: {ENCODINGS}”)return None# 返回 None 而非 crash
容错设计清单：
4.3 配置管理
多层配置优先级（高 → 低）：
命令行参数 > 环境变量 > version.json > 代码默认值--no-update SKILL_NO_ update_url 硬编码 fallbackUPDATE_CHECK
version.json 设计规范：
{”skill”: ”spending-analysis”, // 与 SKILL.md name 一致”version”: ”1.2.3”, // SemVer”release_date”: ”2026-08-02”, // ISO 日期”update_url”: ”https://...version.json”, // 远程版本文件 raw URL”changelog”: {”1.2.0”: ”新增信用卡关联去重”,”1.1.0”: ”新增消费指标与消减分析”,”1.0.0”: ”初始版本”},”min_python”: ”3.9”, // 可选：最低运行时版本”dependencies”: [”openpyxl”, ”pdfplumber”] // 可选：依赖声明}
五、Skill 成本分析与性能优化
5.1 Token 成本分析
每次触发 Skill，SKILL.md 的完整文本会被注入 AI 上下文，这直接消耗 token。理解成本模型是设计高效 Skill 的前提。
成本构成模型：
单次 Skill 触发成本 = SKILL.md token 数 + 脚本输出 token 数 + 中间对话 token 数实际测量（以 spending-analysis 为例）：
优化策略：
SKILL.md 瘦身：将长篇幅的分类词典移到 references/category_rules.md，SKILL.md 中只保留摘要表格脚本输出控制：输出 summary 而非 full dump，提供 --verbose开关用于调试关键信息前置：把最重要的指令放在 SKILL.md 前面，因为 LLM 对文档首尾的注意力更高
5.2 性能优化策略
CPU/IO 密集型优化的常见手段：
实际案例：_normalized.json 作为缓存：
首次执行:CSV → parse → 300 条 ├─→ _normalized.json（写入磁盘）XLSX → parse → 200 条 ┤PDF → parse → 50 条 ┘→ classify_report 读取 _normalized.json修改分类规则后重跑:跳过 parse 阶段（源文件未变）→ classify_report 直接读取已有的 _normalized.json→ 节省约 60% 总耗时
5.3 宿主资源消耗
需要注意的资源上限：
六、Skill 测试
6.1 测试策略
Skill 的测试分三层：
L1 单元测试：独立函数测试→ parse_amount(”¥35.80”) == 35.80→ 编码检测返回正确字符串L2 集成测试：管道阶段测试→ 输入 fixtures/sample_alipay.csv → 输出标准化 JSON→ 输入 fixtures/_normalized.json → 输出 Excel 报告L3 端到端测试：完整流程→ 目录中有 3 个平台文件 → 跑全流程 → 验证报告生成
推荐的测试结构：
skill-name/├── tests/│ ├── fixtures/ # 测试数据│ │ ├── alipay_sample.csv│ │ ├── wechat_sample.xlsx│ │ ├── cmb_sample.pdf│ │ └── expected_output.json│ ├── test_parse.py # L1 + L2│ ├── test_classify.py # L1 + L2│ └── test_e2e.py # L3
6.2 测试数据管理
fixtures 设计原则：
spending-analysis 测试用例示例：
# tests/test_parse.pydef test_parse_amount():assert parse_amount(”¥35.80”) == 35.80assert parse_amount(”1,234.56”) == 1234.56assert parse_amount(””) == 0.0assert parse_amount(”-99.00”) == -99.00def test_parse_alipay_csv():result = parse_alipay(”fixtures/alipay_sample.csv”)assert len(result) == 15assert result[0][”platform”] == ”支付宝”assert result[0][”date”].startswith(”2026-”)def test_encoding_detection():# GBK 编码文件能被正确识别content = detect_encoding(”fixtures/alipay_gbk.csv”)assert ”交易记录” in content
6.3 自动化测试集成
CI 友好的测试配置：
# 通过环境变量禁用需要网络/交互的功能SKILL_NO_UPDATE_CHECK=1 # 跳过自动更新检查SKILL_TEST_MODE=1 # 跳过耗时操作
# CI 中跑测试SKILL_NO_UPDATE_CHECK=1 pytest tests/ -v
七、版本管理
7.1 SemVer 策略
MAJOR.MINOR.PATCHMAJOR → 不向后兼容的变更（分类体系重构、JSON 格式变化）MINOR → 向后兼容的新功能（新增指标、新增平台支持）PATCH → 向后兼容的 Bug 修复（金额解析修正、编码问题）
实际版本演进示例：
1.0.0 初始版本：三平台解析 + 分类 + 报告1.1.0 新增：消费指标分析 + 可消减建议（向后兼容）1.2.0 新增：信用卡关联去重（向后兼容）1.2.1 修复：招行 PDF 金额符号解析错误2.0.0 重构：分类体系从 10 类变成新的分类标准（Breaking Change）
7.2 自动更新机制
更新检查流程：
用户执行脚本│├── 检查环境变量 SKILL_NO_UPDATE_CHECK│ └──=1 → 跳过更新检查│└── 读取 version.json├── 获取本地版本号 (1.0.0)└── HTTP GET → 远程 version.json (超时 5s)├── 网络不通 → 静默跳过（不阻塞用户操作）├── 版本相同 → 静默跳过└── 远程更新 (1.1.0) → 打印更新提示:🔔 spending-analysis 有新版本可用！当前版本: v1.0.0 → 最新版本: v1.1.0更新方式: git pull
设计要点：
绝对静默：网络失败、超时不应打扰用户 非阻塞：更新检查不能拖慢核心功能 可关闭：提供环境变量 SKILL_NO_UPDATE_CHECK=1版本比较可靠：MAJOR → MINOR → PATCH 逐级比较，而非字符串比较
7.3 Changelog 管理
两种 Changelog：
Changelog 规范：
## v1.2.0 (2026-08-15)### 新增- 信用卡还款自动关联：检测招行信用卡还款记录，关联到当月消费- 新增「周末vs工作日」消费节奏对比### 改进- 微信 XLSX 表头行检测更鲁棒，兼容更多导出格式- PDF 解析从 pdfplumber 迁移到 PyMuPDF，速度提升 3x### 修复- 金额为 0 的记录不再被错误分类为「支出」
八、安全与权限控制
8.1 文件系统安全
常见风险和防御：
../../etc/passwd） | bills/{月份}/，拒绝 .. |
report/{月份}/，不写入项目外 | |
~/.ssh/、.env 等 | |
工作目录边界控制：
# ✅ 安全：限定在项目子目录bills_dir = Path(”bills”) / monthreport_dir = Path(”report”) / month# ❌ 不安全：接受任意绝对路径bills_dir = Path(user_input)# 可能指向 /etc/
8.2 网络与外部依赖安全
HTTP 请求安全清单：
timeout=5 | |
# ✅ 安全的 HTTP 请求req = Request(update_url, headers={”User-Agent”: ”skill-updater/1.0”})with urlopen(req, timeout=5) as resp:data = json.loads(resp.read())
8.3 敏感数据处理
# ❌ 不要硬编码 API Key 或 TokenAPI_KEY = ”sk-1234567890abcdef”# ✅ 从环境变量读取import osAPI_KEY = os.environ.get(”SKILL_API_KEY”)# ✅ 输出前脱敏print(f”使用 API Key: {API_KEY[:4]}****”)
敏感数据保护原则：
8.4 SSH 与 Git 安全
密钥管理最佳实践：
# 为 Skill 创建专用密钥（不要复用个人 GitHub 密钥）ssh-keygen -t ed25519 -C ”skill-sync” -f ~/.ssh/id_ed25519_skill# 配置专用 HostHost skill-repoHostName gitee.comUser gitIdentityFile ~/.ssh/id_ed25519_skillIdentitiesOnly yes
安全清单：
使用 ed25519 而非 RSA（更短更安全） 一个 Skill 一个密钥（最小权限原则） 仓库设为私有（如不需要公开） .gitignore排除密钥文件
九、分发与生态
9.1 分发方式对比
9.2 Zip 打包规范
# 打包（排除不必要的文件）cd skill-name/zip -r ../skill-name-v1.0.0.zip . \-x ”.git/*” ”__pycache__/*” ”*.pyc” ”.DS_Store” \”tests/*” ”bills/*” ”report/*”# 验证unzip -l ../skill-name-v1.0.0.zip
9.3 README.md 写作建议
README 面向人类用户，回答：
一句话简介——这是什么？ 快速开始——我最快怎么用上？ 常见问题——可能会遇到什么问题？ 依赖安装——需要什么环境？