前言

Github：https://github.com/HealerJean

博客：http://blog.healerjean.com

一、AI Skill 开发基础认知

1、什么是 AI Skill

AI Skill 本质上是一个结构化的“提示词工程包”。

1）定义与核心价值

• 从“即兴发挥”到“标准化作业”
  • 痛点：直接问AI，每次得到的答案可能千差万别，像开盲盒。
  • Skill 的作用：通过规范化的文件结构（如包含SKILL.md），规定了 AI 的思考路径和行为模式。它让 AI 在面对复杂需求时，不再是重新“即兴创作”，而是像调用函数一样，精准地执行预设的标准化流程。
• 封装与复用
  • 它将“提示词+上下文+工具调用”打包。你不需要每次都重复输入背景信息，只需一键调用 Skill，AI就能立刻进入工作状态。

一个通俗的类比：智能手机理论

• 裸机/基础模型：想象你刚买了一台刚出厂的手机，它只能打电话、发短信。这就像基础版的大模型，虽然聪明，但只能陪你聊天、回答通用问题。

• App/Skill：当你安装了微信、抖音、王者荣耀（这些就是Skill）之后，手机才真正具备了社交、娱乐、游戏的具体能力。

• 结论：AI Skill就是给 AI 安装的“App”或“插件”。

  • 没装 Skill的AI = 一个通用的聊天机器人。
  • 装了“代码 Skill ”的 AI = 资深程序员。

2）适用场景

• 标准化文档生成
  • 场景：周报生成器、技术文档模板、合同起草。
  • 效果：确保输出的格式、语气完全符合公司规范，无需人工二次排版。
• 复杂数据处理
  • 场景：Excel格式清洗、JSON转CSV、SQL查询构建。
  • 效果：将复杂的逻辑封装在Skill里，用户只需输入数据，即可得到清洗后的结果。
• 特定角色模拟
  • 场景：资深代码审查员、雅思口语考官、心理咨询师。
  • 效果：通过预设的“人设”和“评判标准”，让AI提供专业级的反馈，而非泛泛而谈。

3）Skill vs RAG

a、为什么 Skill 必须加载到“上下文”？

Skill 的核心是“渐进式披露”，它的目的是让 AI 在有限的上下文窗口里，拥有无限的能力。

1. 为了“执行”而非“参考”：

   • RAG 是为了让 AI 回答问题
   • Skill 是为了让 AI 执行任务

2. 为了“省 Token”而非“存数据”：

   • Skill 的 Level 1（元数据）常驻上下文，是为了让 AI 知道“我有这个能力”。
   • 只有当 AI 决定用这个能力时，才把 Level 2（指令）加载进上下文。
   • 这种机制是为了解决上下文窗口昂贵的问题，而不是为了解决数据存储的问题。

b、它们在实际工程中是如何协同的？

Skill 和 RAG 往往是嵌套使用的：

1. Skill 是“外壳”：AI 触发 research-skill（研究技能），加载 SKILL.md 到上下文。
2. Skill 指挥 RAG：SKILL.md 里的指令写着：“第一步，请先使用 RAG 工具检索公司内部知识库，找到关于‘Q3 财报’的文档。”
3. RAG 返回结果：RAG 把检索到的数据片段返回给 AI。
4. Skill 继续流程：AI 拿到 RAG 的数据后，继续执行 SKILL.md 的第二步：“第二步，根据检索到的数据，撰写一份摘要报告。”

2、Skill 的核心文件结构

一个 Skill 本质上就是一个文件夹，里面装着让 AI 干活所需的所有东西。

1）必需文件：SKILL.md

• 这是技能的“大脑”，包含元数据（YAML Frontmatter）和核心指令（Markdown 正文）。
  • 元数据（身份证）：在文件最顶部，用 --- 包裹的部分。包含名字和描述，AI 靠这个判断“这事儿归不归我管”。
  • 指令正文（操作手册）：告诉 AI 具体怎么一步步执行任务，包括输入要求、处理步骤、输出格式。
• AI 在触发技能时，会第一时间读取此文件以明确任务目标。

2）可选辅助文件

• scripts/：存放 Python 或 Shell 脚本，用于执行确定性高的代码逻辑（如文件读写、API 调用）。
• references/：存放大型参考文档（如品牌规范手册、API 文档），供 AI 按需读取（RAG 模式）。
• assets/：存放静态资源，如图片模板或固定格式的文本块。

二、核心原理：Skill 是如何工作的

Skill 的核心在于解决大模型“记不住复杂流程”和“上下文昂贵”之间的矛盾。它通过“渐进式披露”机制，让 AI 在不占用大量 Token 的情况下，拥有海量的专业知识。

1、渐进式披露

Skill 的加载不是一股脑全塞给 AI，而是分三层：

1）Level 1：元数据（始终加载）

• 内容：仅包含 name（名称）和 description（描述）。
• 作用：这是 AI 的“索引”。系统启动时，只加载这约 100 Token 的信息。AI 根据描述判断：“用户现在的请求，是否需要用到这个技能？”

2）Level 2：核心指令（触发时加载）

• 内容：SKILL.md 的正文部分，包含详细的工作流、规则、步骤。
• 作用：一旦 AI 决定使用该技能，才会读取这部分内容（通常限制在 5000 Token 内），获取执行任务的具体 SOP。

3）Level 3：外部资源（按需加载）

• 内容：scripts/ 中的脚本、references/ 中的文档。
• 作用：AI 在执行具体步骤时，根据需要去读取文件或执行代码，而不是预先加载。

2、执行闭环

Skill 的执行是一个“推理-行动-验证”的闭环：

1）意图匹配

• 用户指令：“帮我查下订单号 xxxx 订单状态。”
• AI 的决策：AI 大脑迅速扫描已加载的 Skill 列表，通过语义分析，精准命中“订单查询 Skill ”。

2）指令注入

• 读取协议：AI 读取该 Skill 的核心配置文件（如SKILL.md），解析出执行逻辑：“查询物流需调用 mcp/order_query 工具，且必须提供 order_id 参数。”
• 参数提取：AI从用户的自然语言中提取关键参数 order_id: "xxxx"，并按照 MCP 协议的标准格式封装请求体。

3）工具调用

• 协议通信：AI 通过MCP客户端向MCP服务器发起标准请求。
• 执行动作：MCP服务器接收到请求后，并将结果标准化返回 AI。

4）结果回填

• 数据回传：MCP 服务器将查询到的物流轨迹（JSON数据）返回给AI。
• 自然语言生成：AI将枯燥的 JSON 数据“翻译”为用户听得懂的人话：“您的订单 xxxx 目前已退保”

三、核心配置文件 SKILL.md 详解

1、YAML 元数据编写

1）基础字段说明

• name：技能的名字，用英文小写，中间用横杠连接（如 excel-cleaner）。
• description：这是重中之重！决定了 AI 何时会自动调用该技能。描述需包含关键词和触发场景，甚至可以写得具有“侵略性”（例如：“当用户提到清洗数据时，务必使用本技能”）

2）编写示例

场景：我们要开发一个名为 smart-shopper 的 Skill。它的功能是：当用户发送一个商品链接（淘宝或京东）时，AI 能自动提取商品信息，去全网寻找同款低价，并生成比价报告，甚至辅助下单。

---
name: smart-shopper
description: |
  当用户提供电商商品链接（淘宝/京东/拼多多）或商品名称时触发。
  核心能力：全网比价、历史价格查询、优惠券自动检索、生成购买建议。
  适用于想要“薅羊毛”或进行理性消费的用户。
compatibility: Python 3.9+, requests, beautifulsoup4
---

2、Markdown 指令正文编写

在 SKILL.md 中，指令的编写质量直接决定了 Skill 的智商。推荐采用“结构化三段论”来编写提示词，确保 AI 既能听懂需求，又能精准执行。

1）输入要求：明确“原材料”

• 核心逻辑：不要让用户猜谜。明确告诉 AI，执行这个 Skill 需要用户提供哪些关键信息。
• 编写要点：
  • 参数定义：是需要一个文件名？一段代码？还是具体的业务需求？
  • 默认值处理：如果用户没给全信息，AI 应该反问还是使用默认配置？
• 示例：“请用户提供需要分析的 log 文件路径。如果未提供，请提示用户输入。”

2）执行步骤：拆解“流水线” (核心升级点)

• 核心逻辑：将复杂任务拆解为可执行的原子步骤，引导 AI 一步步思考。

• 编写要点：

  • 思维链：先分析，再行动。让 AI 在调用工具前先规划路径。
  • 工具绑定：明确每一步该调用哪个工具（如 mcp_read_file, mcp_write_file）。

• 示例：

  1. 分析：读取用户提供的文件内容，识别错误类型。
  2. 规划：根据错误类型，生成修复方案。
  3. 执行：调用 file_editor 工具应用修复方案。

3）输出规范：定义“交付物”

• 核心逻辑：规定最终结果的形态，确保“所见即所得”。
• 编写要点：
  • 格式约束：是输出一段总结文本？一个 JSON 对象？还是直接生成一个 Markdown 文件？
  • 文件命名：如果涉及生成文件，明确命名规则（如 report_YYYYMMDD.md）。
• 示例：“最终结果请直接生成一个名为 fix_plan.md 的文件，内容包含‘问题描述’和‘修复代码’两部分。”

2）编写示例

# 全网比价与购物决策助手

## 目标
帮助用户以最低成本获取心仪商品，杜绝买贵，提供理性的购买决策支持。

## 工作流程
1. **信息提取**：
   - 分析用户输入。如果是链接，调用 `scripts/parse_url.py` 提取商品标题、当前价格、店铺名称。
   - 如果是商品名，直接进行下一步。
2. **全网搜索**：
   - 使用 `web-search` 技能或调用 `scripts/search_engine.py`，在淘宝、京东、拼多多三个平台搜索同款。
   - 筛选条件：销量>100，好评率>95%。
3. **价格比对与决策**：
   - 将各平台价格统一换算为“最终到手价”（扣除优惠券、满减）。
   - 计算差价百分比。
4. **输出报告**：
   - 以 Markdown 表格形式展示比价结果。
   - 给出明确的购买建议（例如：“建议去拼多多购买，比当前链接便宜 35 元”）。

## 输出规范
- 必须包含商品缩略图（如有）。
- 价格必须精确到小数点后两位。
- 如果检测到历史低价低于当前所有平台价格，必须发出“建议等待”的预警。

---
name: xxxxx
description: xxxxx
  【触发条件】：
      1. xxxxx
      2. xxxxx
  【严格禁止】：
      1. xxxxx
      2. xxxxx
  【输出规范】：你是一个无情的数据渲染引擎。仅输出基于接口数据的Markdown表格，严禁包含任何开场白、解释性文字或结束语。
---

# Tools

你必须使用以下工具和工作流来获取数据：

1.  **** (工具): 
    - 工具描述：xxxxxxxxxxxxxxxxxxxxxxxxx
    - 接口文档： 匹配 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2.  **** (工作流): 
    - 工具描述：xxxxxxxxxxxxxxxxxxxxxxxxx
    - 输入参数：`xxxxx` (xxxx)
    - 输出参数：`xxxxx` (xxxx)



# Workflow

请严格按照以下步骤执行，**特别注意变量的数据来源**：

## 第一步：逻辑状态重置（强制前置）
1. **忽略历史干扰**：无视当前会话中之前的任何闲聊、未完成的旧任务或中间变量。
2. **聚焦当前意图**：将用户的最新输入视为**唯一有效指令**。不要尝试补全或延续上一轮的逻辑，除非用户明确指代（如“修改刚才那个”）。 



## 第二步：参数校验

1. 接收用户输入的 `xxxxxxxxxxxxxxxxxxxx`。

2. **格式验证**：

    - 检查 `xxxxx` 是否严格由 **4位数字** 组成（例如：xxxxx, xxxxx）。
    - **校验失败处理**：如果输入为空、包含非数字字符、或者长度不等于4位，**立即停止后续操作**，并直接回复：
        > “您提供的xxxxx格式不正确。xxxxxxxxxxxxxxx应为 **4位数字**（例如：xxxxxxxxxxxxxxx），请核对后重新提供。”
    - **校验通过**：只有格式正确时，才进入第二步。



## 第三步：数据获取

1. **检索各个工具对应的接口文档知识库**：确认接口入参和出参。
2. **并行调用**工具：
    - 调用 **工具** ``
    - 调用 **工作流** ``，传入参数 `xxxxx` 为用户输入的xxxxxxxxxxxxxxxxxxxx。



## 第四步：异常检查

- 如果 **工具** `` 返回的 `success` 为 `false`，直接回复：“系统提示：$[msg]”，并停止后续操作。
- 如果 **工作流** `` 执行失败或返回空值，直接回复：“系统提示：xxxxx失败，请稍后重试。”，并停止后续操作。



## 第五步：逻辑处理与数据提取

请基于接口返回的数据执行以下逻辑，**严格区分数据来源**：

### 1. 工具 A： 数据处理

**数据来源**：`` 的返回结果

1. **变量赋值**
    - `$[xxxxx]` = **工作流** 返回的 `xxxxx` 值。
    - 如果工作流未返回该值，则 `$[xxxxx]` = 0。

### 2. 工具 B： 数据处理
**数据来源**：`` 的返回结果



## 第六步：生成输出

**重要：** 必须严格按照下方的 Markdown 模板输出。

**🛑 最终输出强制指令：**

1. **输出纯净度**：输出内容**只能**是下方的 Markdown 表格。
2. **禁止废话**：**严禁**包含任何开场白（如“好的”、“这是结果”）、结束语（如“希望这能帮到你”、“总结如下”）或任何解释性文字。
3. **强制开头**：输出必须以 `### xxxxx` 直接开始。
4. **强制截断**：生成完表格的最后一行 `<!-- END -->` 后，**立即停止生成**，不要输出任何后续字符。



# Output Template

(请严格复制以下内容并替换变量，不要修改表头或格式，注意 `<br>` 为换行符)

###  xxxxxxxxxxxx配置详情 (ID: $[xxxxx])

| 配置项 | 配置描述 | 配置位置 |
| :--- | :--- | :--- |
| xxxxx | $[xxxxx]|  |
| ... | ... | ... |

<!-- END -->



# Constraints

- **SYSTEM MODE: RAW DATA OUTPUT ONLY**. 你是一个无情的数据渲染引擎。
- **数据准确性**：所有数字必须直接来源于接口返回，严禁臆造。
- **知识库依赖**：接口参数必须参考知识库定义；维度名称必须严格使用枚举库中的中文描述。
- **错误处理**：接口报错必须直接反馈，不要尝试编造数据。



# Example Output (Strictly follow this format)

###  xxxx配置详情 (ID: 10001)

| 配置项 | 配置描述 | 配置位置 |
| :--- | :--- | :--- |
| xxxxx | xxxxx]|  |
| ... | ... | ... |

(注意：上面的例子结束后，没有任何其他文字，直接结束)

3、编写配套脚本（Scripts）

目标：为了让 AI 能真正“看懂”网页，我们需要写一个简单的 Python 脚本。

文件名：scripts/parse_url.py

import sys
import requests
from bs4 import BeautifulSoup

def get_product_info(url):
    # 模拟浏览器请求头，防止被反爬虫拦截
    headers = {'User-Agent': 'Mozilla/5.0...'}
    try:
        response = requests.get(url, headers=headers, timeout=5)
        soup = BeautifulSoup(response.text, 'html.parser')
        
        # 提取标题和价格（这里仅为示例逻辑，实际需针对具体平台解析）
        title = soup.find('h1').text.strip()
        price = soup.find('span', class_='price').text.strip()
        
        return {"title": title, "price": price, "status": "success"}
    except Exception as e:
        return {"status": "error", "message": str(e)}

if __name__ == "__main__":
    url = sys.argv
    print(get_product_info(url))

四、深度开发规范：如何写出高质量的 Skill？

1、元数据参数

1）参数解释

a、description：触发灵魂

这是 Level 1 加载 时 AI 唯一能看到的内容。如果这里写得不好，你的 Skill 写得再完美，AI 也根本不会调用它。

• 作用：AI 会将用户的提问与这个描述进行语义匹配。

• 错误写法：description: "检查项目"（太简单，AI 不知道具体查什么）。

• 正确写法：

  • 解析：不仅描述了功能，还预埋了“检查”、“分析”、“报告”等触发关键词。

  description: >
    分析项目健康度，包括代码质量、依赖项、Git 状态。
    当用户要求“检查项目健康”、“分析代码库”、“运行诊断”或“生成项目报告”时使用。
  

b、allowed-tools：安全红线

这是生产环境 Skill 必须配置的参数。遵循“最小权限原则”，防止 AI 在执行任务时误删系统文件。

• 作用：限制 Skill 只能调用列表中的工具。

• 危险示例：allowed-tools: [Bash]（允许所有 Bash 命令，AI 可能会执行 rm -rf /）。

• 安全示例：

  • 解析：这里使用了通配符 *，只允许 git、npm、python 开头的命令，其他危险命令（如 curl、rm）会被系统自动拦截。

  allowed-tools:
    - Read
    - Glob
    - Bash(git *)
    - Bash(npm *)
    - Bash(python *)
  

c、model：成本与智力的平衡

并不是所有任务都需要最聪明的模型（如 Sonnet 或 Opus）。通过指定模型，你可以大幅降低运行成本。

• sonnet (推荐)：智力与速度的平衡，适合大多数复杂逻辑（如你的配置分析）。
• opus：最强智力，适合极复杂的推理、长文本分析，但速度慢、贵。
• haiku：速度最快，最便宜，适合简单的提取、格式化任务。
• inherit (或留空)：继承用户当前会话使用的模型。
• 完整模型 ID：如 claude-sonnet-4-20250514 (指定具体版本)。

d、 context：上下文策略

决定 Skill 在执行时，能“看”到多少之前的聊天记录。

• fork (默认)：继承模式。Skill 能看到你之前的对话历史。
  • 适用：绝大多数任务。比如你先说了“我想优化这个文件”，然后触发 Skill，它需要知道你指的是哪个文件。
• isolated：隔离模式。Skill 启动时是一个全新的空白上下文，看不到之前的对话。
  • 适用：独立的工具类任务。比如一个“汇率转换 Skill”，它不需要知道你刚才在聊什么，只需要你输入的数字。

e、agent：角色/执行模式

决定 AI 以什么“性格”或“工作流”来执行任务。不同框架略有差异，以下是通用标准

• Explore (探索者)：倾向于先搜索、多读取。适合诊断、分析类任务（最适合你的场景，因为它需要先查 API、查文档）。
• Editor (编辑者)：倾向于修改文件。适合代码重构、文档修改。
• Reviewer (审查者)：倾向于找茬。适合代码审查、规则校验。
• Analyst (分析师)：专注于数据处理和逻辑计算。
• Ask (提问者)：倾向于多问用户问题，而不是自己瞎猜。

f、disable-model-invocation (禁止模型自动调用)

这是一个“自动触发开关”。它决定了 AI 是否可以自主决定使用这个 Skill。

• 作用：
  • false (默认)：允许自动调用。只要 AI 觉得用户的意图匹配了 description，它就会自动激活 Skill。
  • true：禁止自动调用。 AI 即使觉得匹配，也不会主动用。用户必须通过明确的指令（比如手动输入 /承保配置范围建议）来触发。

g、compatibility (兼容性声明)

它用来声明运行这个 Skill 必须具备的外部条件（如操作系统、安装的软件、网络权限等）。

• 作用：
  • 前置检查：系统在加载 Skill 时，会先检查当前环境是否满足这些条件。如果不满足，系统可能会直接禁用该 Skill 或提示用户安装依赖，避免执行到一半才报错。
  • 文档说明：告诉其他开发者或用户，这个 Skill 只能在特定环境下工作（比如“只能在 Linux 上跑”或“必须装 Docker”）。
• 你的场景：
  • 你在元数据里写了 Requires access to internal insurance APIs，这其实更像是一个备注。严格来说，compatibility 应该写具体的技术依赖，比如 Requires python3, jq。
  • 如果你只是需要内网权限，通常由 allowed-tools 控制，这个字段不填也可以。

h、user-invocable 是否允许用户调用

通常用于“子技能”或“原子能力”。

• user-invocable: true：这个技能是对外营业的，用户可以直接点菜。
• user-invocable: false：这个技能是内部专用的，用户看不见菜单，只能由后厨（其他技能）调用。

场景 A：user-invocable: true (允许用户调用)

• 用户说：“服务器满了，帮我清理一下垃圾。”
• AI 的反应：AI 看到这句话，发现有个技能叫“清理服务器垃圾”，而且 user-invocable 是 true，于是它会说：“好的，我正在调用清理技能…”。
• 结果：危险！ 用户随口一句话就触发了高危操作。

场景 B：user-invocable: false (禁止用户调用)

• 用户说：“服务器满了，帮我清理一下垃圾。”
• AI 的反应：AI 虽然知道有“清理服务器垃圾”这个技能，但看到 user-invocable 是 false，它会忽略这个技能，转而回答：“服务器满了？建议你检查一下日志，或者联系管理员处理。”
• 结果：安全。 用户无法直接触发这个技能。

2）综合实战：一个完整的 Skill 头部

结合以上所有参数，一个成熟的 project-health Skill 头部应该是这样的：

---
name: project-health
description: >
  分析项目健康度，包括代码质量、依赖项、Git 状态。
  当用户要求“检查项目健康”、“分析代码库”、“运行诊断”或“生成项目报告”时使用。
version: 1.0.1
argument-hint: [directory] [--fix] [--open]
allowed-tools:
  - Read
  - Glob
  - Bash(git *)
  - Bash(npm *)
  - Bash(python *)
model: sonnet
context: fork
agent: Explore
user-invocable: true
tags: [coding, diagnostics, report]
compatibility: Requires git, python3
---