一、什么是 AI 中的 Skill？

Skill（技能） 是 AI Agent（智能体）在执行任务时，能够调用的一个可重复执行的、特定功能的模块或能力。

Skill 通常：

• 有明确的输入/输出
• 可以被单独调用
• 可以被组合完成复杂任务
• 可以是内置的或第三方的/自定义的

二、Skill 在 AI 系统中的位置（结构）

用户 → AI Agent（大脑/调度器） → 选择/组合 Skill → 执行 → 返回结果

• AI Agent：决定什么时候、用什么 Skill、怎么组合
• Skill：执行具体的“原子能力”

三、如何使用SKILL.md

SKILL.md 不是直接在命令行执行的脚本，而是 AI 助手的配置文件,它是给 AI 看的说明书。它是在chat中使用；

四、SKILL.md 文件完整信息说明

SKILL.md 是用于为 AI 智能体（如 Claude Code、Cursor 等）提供专业知识和工作流程的核心文件

1、核心价值

SKILL.md 的本质是知识注入机制的载体，它解决了传统 Prompt 的三大痛点：

维度	           传统Prompt	            SKILL.md 技能包
确定性	       每次输出结果可能不同	     固化流程，输出可复现
上下文	       需一次性提供大量信息	     渐进式披露，按需加载
可移植性	       绑定特定对话场景	         跨工具（Claude/Cursor/OpenClaw）一致执行
工程化	       难以版本控制和复用	         可版本化、可共享、可组合

2、目录结构规范

一个完整的 Skill 是一个文件夹，核心是 SKILL.md 文件：

my-skill/
├── SKILL.md          # 必需：核心指令文件（YAML frontmatter + Markdown）
├── scripts/          # 可选：可执行脚本（Python/Shell等）
├── references/       # 可选：参考文档（API文档、规范等，按需加载）
├── assets/           # 可选：模板和静态资源
└── examples/         # 可选：示例文件

3、SKILL.md 文件结构

SKILL.md 由 YAML Frontmatter（元数据配置）和 Markdown 正文（执行指令）两部分组成：

---
name: skill-name
description: 这个技能是干什么的，什么时候用
license: Apache-2.0
compatibility: Python 3.8+
metadata:
  author: your-org
  version: "1.0"
allowed-tools: bash read
---

# 技能标题

## 概述
详细介绍技能的使用场景、技术背景等

## 前置条件
需要什么环境配置、依赖项

## 执行步骤
1. 第一步...
2. 第二步...

## 输出格式
...

## 注意事项
...

4、YAML Frontmatter 字段详解

字段	      是否必需	         说明	                 限制
name	         是	      技能唯一标识符	          1-64字符，仅小写字母、数字、连字符
description      是	      功能描述和触发场景	      最长1024字符，要包含触发关键词和时序定位
license          否	      许可证名称或文件路径	  如 Apache-2.0, MIT
compatibility    否	      环境要求	最大500字符，  标注系统依赖、网络访问等
metadata         否	      自定义元数据	          任意键值对，如版本、作者等
allowed-tools    否	      预批准的工具列表	      空格分隔（实验性功能）

五、Markdown 正文结构建议

推荐的四层骨架

Skill 的正文应该按分层逻辑组织，对应 Agent 加载和执行的四个阶段：

层级	              内容    	      Agent行为	             示例
第一层：概述	     能力边界声明	    确认是否匹配任务	   "本Skill封装了xxx工具的全部能力，支持A、B、C功能"
第二层：前置条件	 环境依赖、准备工作	检查环境是否就绪	   "需要 Python 3.8+，已安装依赖库"
第三层：操作指南	 具体执行步骤和命令	按指令执行操作	    给出多场景的具体命令示例
第四层：补充说明	 实现细节、兜底逻辑	处理异常情况	       "若工具未安装，自动执行安装脚本"

六、渐进式披露机制

Agent Skills 采用四阶段渐进式披露来管理上下文窗口：

启动阶段：扫描所有 Skill → 只读取 name + description（~100 tokens/个）
    ↓
激活阶段：匹配成功 → 加载完整 SKILL.md（建议 < 5000 tokens）
    ↓
执行阶段：按需读取 references/ 和 assets/ 目录文件
    ↓
脚本阶段：按需执行 scripts/ 目录中的脚本

这种设计确保 Agent 的上下文窗口保持精简，同时在需要时能获取深度领域知识

七、编写最佳实践总结

DO（推荐做法）

✅ description 要略微"pushy"，列出各种触发短语

✅ 给多场景的具体命令示例，不要只给抽象模板

✅ 用具体的示例输出训练 Agent 的格式预期

✅ 补充说明要包含异常处理和兜底逻辑

✅ 将项目 Skill 提交到版本控制，团队共享

DON’T（避免做法）

❌ description 不要太模糊或太简短

❌ 不要在概述层塞操作细节（会干扰匹配判断）

❌ 不要做多个 Skill 的"瑞士军刀"——一个 Skill 只做一件事

❌ 不要让 Agent"自由发挥"的地方太多，尽量固化到脚本

❌ 不要在 Skill 中包含敏感信息（密码、Token 等）