FBm 的 AI 编程笔记

Appearance

什么是Skills，用来干什么的？怎么用它？ ​

什么是Agent Skills（技能） ​

Agent Skills 是模块化的能力包，包含元数据，指令，可选资源（脚本、模板），让AI Agent在需要时自动加载和使用。

  • 封装专业知识：将特定领域的最佳实践和操作流程封装成可复用的技能
  • 提供工作流模板：定义标准化的任务处理流程，提高工作效率
  • 扩展 AI 能力：让 AI 助手能够处理更专业、更复杂的任务
  • 团队协作共享：Skills 可以在团队成员间共享专业知识，并可不断的快速迭代升级

假设给新员工做入职培训：

  • ❌ 传统方式：每次都重复讲解相同的工作流程
  • ✅ Skills 方式：准备好工作手册，需要时自己翻阅

简单来说，Skills就是给AI配备的"岗位SOP"。

SOP（标准作业程序）是指将某一事件的标准操作步骤和要求以统一的格式描述出来的指导性文件。它在现代企业管理中是确保工作高效、准确执行的基石。

Skill能力包的目录结构 ​

1 📁 skill-name/
2 ├── SKILL.md           # 核心指令文件，通过自然语言描述（使用场景、使用方式、使用步骤、及注意事项等信息）
3 ├── scripts/           # （可选）可执行脚本（Python/Bash）、预写好的代码，处理复杂任务
4 ├── references/        # （可选）更详细的参考文档，如知识库、技术规范文档
5 └── assets/            # （可选）图片、模版等可能使用到的资源

当需要AI处理某个任务时，它自动加载对应的Skills，按照既定流程执行。用完即走，不占用上下文，将AI的能力模块化和标准化。

Skills VS Prompt？三个关键差异 ​

按需加载，不占空间 ​

传统Prompt无论用不用得上，所有规则都塞在上下文里。随着规则越来越多，模型注意力被分散，很容易出现"指令漂移"——明明写了规则，AI却视而不见。

Skills使用三层加载机制：元数据层、指令层、资源层，实现按需加载。

跨平台通用，一次编写到处使用 ​

以前你为ChatGPT写的提示词，在Claude、Cursor里不一定能用，得重新调整。

Skills是开放标准。一个.md文件，在Claude Code、Cursor、OpenCode、甚至未来的任何AI工具里都能用，不用改一行代码。

这降低了多少迁移成本？想想你有多少个AI工具，每个工具都要重复配置一遍。现在只需要一个技能包，一键装配。

可组合性，形成能力网络 ​

一个Skill解决不了复杂问题？没关系，多个Skills可以协同工作。

AI会自动判断需要哪些技能，比如处理数据分析任务时，可能同时调用"数据清洗"、"统计分析"、"可视化"三个Skills，AI自动组合这些能力，形成完整的工作流。

这就像乐高积木，每个Skill都是一个标准模块，可以自由组合，构建出无限可能的能力。

Skills的技术架构：三层加载机制 ​

Skills 最核心的设计理念：分阶段、按需加载 skills.png

Level 1: 元数据- 总是加载 ​

1 ---
2 name: detailed-design
3 description: 功能详细设计助手。用于根据功能说明书生成详细的技术设计文档。当用户需要：(1) 编写功能详细设计文档，(2) 设计代码架构和模块结构，(3) 定义函数接口和数据流，(4) 规划实现方案和算法时使用此技能。
4 ---
  • 加载内容： 只加载每个技能的名字和一段简短的描述。
  • 作用：让 AI Agent 知道有哪些 Skills 可用，什么时候该用。
  • 结果： AI Agent知道自己 “会什么”，但还不知道 “具体怎么做”。

Level 2: 指令- 触发时加载 ​

1 # detailed-design
2 
3 ## 工作流程
4 
5 ## 关键注意事项
6 ##典型使用场景
7 ##最佳实践
8 ##参考示例（参考 references/function_spec.md了解背景知识）
  • 触发时机： 当你说 “帮我生成详细技术方案” 的时候。
  • 加载内容： AI发现这个任务归 “detailed-design” 这个技能管，AI会去读取skill文件夹里的 SKILL.md 文件内容。
  • 作用： 只有在这个时候，那些详细的操作步骤、最佳实践、注意事项才会进入 AI 的脑子。

Level 3: 资源- 引用时加载 ​

1 pdf-skill/
2 ├── SKILL.md              # Level 2
3 ├── FORMS.md              # Level 3 - 表单填写指南
4 ├── REFERENCE.md          # Level 3 - API 参考文档
5 ├── templates/
6 │   └── report_template.md
7 └── scripts/
8     ├── fill_form.py      # Level 3 - 表单填充脚本
9     └── validate.py       # Level 3 - 验证脚本
  • 加载时机：当 SKILL.md 中的指令引用这些文件时。
  • 参考（reference）： 如果 SKILL.md 中引用了reference.md ，AI会根据需要进一步读取这些文件。
  • 脚本（scripts）：Skill 中可以内置一些可执行的脚本，在 SKILL.md 或者具体的参考文献（reference）下会告诉AI应该调用以及如何调用这些脚本。

为什么需要Skills ​

问题1：重复性工作的低效率问题 ​

现状：每次对话都要重新描述相同的工作流程

  • 用户1："帮我按XX格式生成详细技术方案"
  • 用户2："记得要包含XX部分"
  • 用户3："别忘了XX细节"
  • 用户4：（每次都要重复这个过程）

Skills 方案：

1 ---
2 name: detailed-design
3 description: 功能详细技术文档编写。用于根据功能说明书生成详细的技术设计文档。当用户需要：(1) 编写功能详细设计文档，(2) 设计代码架构和模块结构，(3) 定义函数接口和数据流，(4) 规划实现方案和算法时使用此技能。
4 ---
5 # 生成流程
6 1. 工作流程：
7     步骤1：分析功能说明书
8     步骤2：设计模块结构
9     步骤3：设计接口规范
10 2. 关键注意事项
11 4. 参考示例（参考 references/function_spec.md了解从功能规格到详细设计的完整示例。）
12 5. 根据详细设计文档模板，输出交付物
13 ...

问题2：上下文窗口（Context Window）的浪费 ​

传统方式：所有指令都占用上下文

  • MCP ：单个可能消耗 数万 tokens
  • 详细 Prompt：每次对话都重新加载

Skills 方案：

  • 元数据阶段：仅 ~100 tokens（只知道 Skill 存在）
  • 指令阶段：<5,000 tokens（需要时才加载）
  • 资源阶段：几乎无限（文件不进入上下文）

问题3：专业领域知识的复用困难 ​

场景：

  • 流程文件审查
  • 代码审计规范
  • 参数配置

这些领域知识需要：

  • ✅ 结构化存储
  • ✅ 团队共享
  • ✅ 版本管理
  • ✅ 跨平台使用

总结 ​

Agent Skills 的核心价值在于：

  1. 知识复用：创建一次，跨对话、跨项目使用
  2. 团队协作：标准化工作流程，组织知识沉淀
  3. 简洁易用：使用 Markdown 格式，技术门槛低
  4. Token 效率：渐进式加载机制，按需使用资源
  5. 跨平台：与模型无关，适用于多种AI工具

是不是所有事情都要用 Skill？ ​

简单问答（比如问天气、问某个 AI 技术概念）→ 直接问 AI 就行，不需要 Skill。

Skill = 专业技能

Skills vs MCP ​

维度SkillsMCP
核心能力封装和复用“怎么做”的专业知识和流程连接外部工具和资源
核心定位应用能力层：可复用的业务技能包工具连接层：模型与外部世界的连接
技术门槛低（Markdown + YAML）高（需要服务器开发）
数据访问静态知识、脚本逻辑实时数据、外部API
适用场景标准化工作流、团队规范企业数据集成、实时查询、调用API

选择 Skills：

  • ✅ 有标准化的工作流程
  • ✅ 需要团队知识共享
  • ✅ 重复性任务多
  • ✅ 不需要实时外部数据

选择 MCP：

  • ✅ 需要连接外部系统
  • ✅ 需要实时数据访问
  • ✅ 企业数据集成
  • ✅ 跨系统操作

组合使用：

  • 🎯 MCP 提供数据源 + Skills 定义工作流 = 最佳实践

MCP（Model Context Protocol 模型上下文协议）是一种标准化协议，使AI模型能够与外部工具和资源进行结构化交互，从而提升AI的功能和应用场景。

skill中有script/、references/、/asset目录这些目录都要吗？ ​

简单的场景下一个skill.md就行了

skill本质就是一个提示词来构建的任务模版，为了保证skill.md中prompt简洁，对于比较复杂的skill.md 可以将数据归类到references/scripts/asset目录下。

正常情况简单场景 (只需 skill.md)，比如：提取邮件地址这种简单任务。

1 email-extractor/ 
2 └── skill.md

复杂场景 ，需要完整结构

1 email-extractor/
2 ├── skill.md                    # 核心逻辑
3 ├── scripts/
4    ├── preprocess.js          # 清洗输入
5    └── validate.js            # 验证输出
6 ├── references/ │
7    ├── rfc5322.md             # 邮件标准文档
8 └── assets/
9    ├── output-template.json   # 输出模板
10    └── icon.svg               # Skill 图标
只用 skill.md需要额外目录
提示词 < 500 行提示词 > 500 行或需要分模块
无需编程逻辑需要前/后处理脚本
示例在提示词内就够大量示例数据

Skill把完成某个特定任务所需的领域知识、操作流程、要用到的工具、以及最佳实践全都封装在了一起。当 AI 面对相应请求时，就能像一位经验丰富的专家那样，有条不紊地自主执行。