Skill 是给 AI 注入标准化工作流、领域知识与可执行能力的可复用模块。

Skill 核心概念

什么是 Skill

• 一句话理解：AI 原本不知道该怎么专业完成一件事，Skill 就是教会它这套固定流程；写好之后，只在命中场景时才加载。
• 普通 Prompt 的痛点是每次对话都要重复写步骤，上下文冗余、输出不稳定、容易幻觉；Skill 解决的核心问题就是经验固化、流程复用、执行一致性。
• Skill 的本质是一份可复用、可按需加载的操作说明书，把领域工作流程、专业规则封装成 AI 可以自动调用的能力包，类似编程里的函数。

Skill 的完整定义

• Skill = 元数据层（SKILL.md） + 引擎层（scripts/） + 资源层（assets/ + references/） + 版本管理
• 它不是单一脚本，而是一套面向 Agent 的领域扩展包，本质是知识工程：把人的隐性经验，变成 AI 可读、可执行的规范。

Skill 加载三阶段

• Skill 采用懒加载机制，和一次性把全部内容塞进 Prompt 有本质区别：

1. 发现 Discovery：启动时只加载所有 Skill 的 name 和 description，模型靠描述判断当前任务匹配哪个技能；
2. 激活 Activation：用户请求命中某个 Skill 的描述语义时，才把完整 SKILL.md 载入上下文；
3. 执行 Execution：按照 SOP 执行，按需读取脚本、参考文档、模板资源。

• 优势：大幅节省 Token、减少无关噪音，降低幻觉概率。

文件目录结构

• 基础最简结构

skill-name/
├── SKILL.md        # 必须，YAML元数据 + Markdown指令入口
├── scripts/        # 可选：可执行脚本 Python/Bash/JS
├── references/     # 可选：长规则文档、schema、说明笔记
└── assets/         # 可选：模板、数据表、静态资源

工程化完整版（推荐正式项目使用）

skill-name/
├── SKILL.md                # AI读取的入口说明书
├── README.md               # 给人看的快速上手文档
├── .gitignore
├── scripts/
│   ├── version.json        # SemVer版本、更新地址、依赖清单
│   ├── check_update.py     # 自动更新检测
│   └── *.py / *.sh
├── assets/
│   ├── templates/
│   ├── fonts/
│   └── data/
├── references/
│   ├── category_rules.md
│   ├── data_schema.md
│   └── known_issues.md
└── tests/                  # 单元&端到端测试
    ├── fixtures/
    └── test_*.py

assets：代码运行时加载的文件（Excel模板、静态码表）
references：AI 理解业务时查阅的规则文档（分类词典、约束说明）

Skill 生命周期

• 安装 → 触发 → 执行 → 更新 → 退役

1. 安装：Zip / Git 部署，校验目录、依赖、权限
2. 触发：description 语义匹配，命中后加载 SKILL.md
3. 执行：AI 按 SOP 调度脚本、读取资源、输出结果
4. 更新：读取 version.json，对比语义版本，静默检测更新
5. 退役：移除目录、清理缓存、通知用户迁移方案

Skill 的触发机制

• 触发的核心：description 是 Skill 的唯一入口。AI 遍历所有已安装 Skill 的 description，做语义匹配，匹配成功才加载完整技能。

description 写作规范

• 一段合格的 description 需要同时回答三件事：

1. 这个技能是做什么的（领域+能力）
2. 在什么场景下才应该触发
3. 用户会用哪些自然语言提问（触发词）

• ✅ 口诀：一句领域 + 一句能力 + 一句输出 + 一串触发词

description: >
  个人月度消费分析。从支付宝/微信/招商银行等多平台交易流水中解析、标准化、去重、分类打标，生成 Excel + Markdown 消费分析报告。
  触发词包括：”消费分析”、”月度消费”、”账单分析”、”交易流水”、”记账分析”、”消费报告”、”支出分析”、”看看花了多少钱”等。

• 常见错误：描述模糊、范围太宽泛、缺少触发词、触发词太少。

1. T1 精确触发词（高置信度，写进description）：消费分析、月度消费报告
2. T2 场景触发词（中置信度，补充进description）：花了多少钱、帮我记账
3. T3 模糊触发词（低置信度，不写入description，交给AI语义推理）：支付宝明细、微信账单整理

触发域控制

• 用来避免误触发、避免大技能无意义加载。手段：

1. 在 description 写明适用边界、排除场景
2. 使用组合触发词，而不是单个宽泛词汇
3. SOP 第一步增加前置条件校验（目录、文件是否存在）

SKILL.md 设计规范

YAML 元数据头（Front Matter）

• 放在文档最顶部，固定字段：

---
name: spending-analysis
description: >
  个人月度消费分析。从支付宝/微信/招商银行等多平台交易流水中解析、标准化、去重、分类打标，生成 Excel + Markdown 消费分析报告。
  触发词包括：”消费分析”、”月度消费”、”账单分析”、”交易流水”、”记账分析”、”消费报告”、”支出分析”、”看看花了多少钱”等。
version: 1.0.0
license: LICENSE
compatibility: Python 3.9+
metadata:
  author: 展望江莱
allowed-tools:
  - Read
---

name 强制规则：小写字母、数字、横杠；不能以横杠开头结尾、不能连续横杠；必须和外层文件夹同名，全局唯一。

SOP 工作流设计（SKILL.md 核心）

• SOP 是给 AI 执行的步骤，遵循4条原则：

1. 步骤控制在 3–5 步，步骤过多容易遗漏；
2. 每一步写可执行指令，优先写脚本命令，拒绝模糊描述；
3. 显式定义每一步的输入、输出；
4. 必须包含异常分支（文件缺失、解析失败、重复文件等）。

• 示例流程：

1. 准备账单文件
2. 解析、标准化为统一JSON
3. 分类、计算指标，输出报告

知识分层策略

• 高频、每次执行都要读取的核心规则：直接写在 SKILL.md
• 体量巨大、不每次都要读取、变更频繁的规则：放到 references 目录

Skill 的创建方式

AI 直接生成

• 对话中直接让AI生成整套技能目录、SKILL.md、配套脚本；适合快速搭建。
• 示例prompt：创建技能 pdf-extract-images，用户要求从PDF提取图片时触发，脚本放在scripts/extract_pdf_images.py，输出到images文件夹，细节不确定向我确认，不要自行编造。
• 也支持把当前对话的工作流、一次纠错结果直接保存为Skill。

手动编写

• 第一步：创建和name同名的文件夹
• 第二步：编写SKILL.md元数据和SOP
• 第三步：按需增加scripts / assets / references / tests
• 第四步：校验、测试

复用社区现成Skill

• 从 skillsmp.com、官方社区等渠道下载完整文件夹，直接放到对应skill目录即可。
• 技能过大时，建议拆分成多个小型Skill。

✅ 拆分收益：Token更少、触发更精准、能力可自由组合。
✅ 拆分判断标准：步骤太多、一句话说不清触发场景、文档行数过长（>150行）。
✅ 例子：写作大技能拆分为选题、初稿、润色、配图四个独立小技能。