Wisdom Logo
Wisdom Docs
Wisdom Docs

AI Skill 撰写完全指南

系统介绍 AI Skill 的概念、结构与撰写方法，涵盖 Skill 与 Prompt Engineering 的对比、SKILL.md 规范、最佳实践及典型应用场景的完整实战指南

  • AI
  • Skill
  • 方法论
  • AI工程实践
  • Prompt Engineering

一、什么是 Skill？

1.1 Skill 的定义与定位

Skill（技能）是一种模块化、自包含的扩展包，用于为 AI Agent 提供专业化的知识、工作流程和工具支持。它相当于 AI 的”专业培训手册”——将通用 AI 转化为具备特定领域能力的专业助手。

flowchart LR A[通用 AI Agent] -->|加载 Skill| B[专业化 AI] B --> C[Git 管理专家] B --> D[文档撰写专家] B --> E[数据分析专家]

1.2 Skill vs Prompt Engineering 的区别

维度Prompt EngineeringSkill
持久性每次对话需重新输入一次安装，永久使用
复用性低，难以复制高，标准化打包
复杂度适合简单任务适合复杂工作流
维护分散在对话历史中集中管理
工具集成弱强（可包含脚本）
flowchart TD subgraph 能力扩展方式对比 Q2["**理想区**</br>高复用 · 低复杂度"] --- Q1["⭐ **Skill**</br>高复用 · 高复杂度"] Q3["**提示词**</br>低复用 · 低复杂度"] --- Q4["**模板片段**</br>低复用 · 高复杂度"] Q2 --- Q3 Q1 --- Q4 end

1.3 Skill 在 AI 工作流中的角色

sequenceDiagram participant User as 用户 participant Agent as AI Agent participant Skill as Skill System participant Tools as 外部工具 User->>Agent: 请求任务 Agent->>Skill: 检索匹配 Skill Skill-->>Agent: 返回元数据 Agent->>Skill: 加载 SKILL.md Skill-->>Agent: 任务指导 Agent->>Tools: 执行操作 Tools-->>Agent: 返回结果 Agent-->>User: 完成任务

二、Skill 的核心价值

2.1 模块化与可复用性

Skill 采用标准化的目录结构，支持：

  • 一次开发，多次使用
  • 跨项目共享
  • 版本化管理
mindmap root((模块化价值)) 代码复用 脚本重复使用 模板统一管理 配置标准化 知识复用 领域知识库 最佳实践库 规范文档集 工具复用 自动化脚本 API 封装 验证工具

2.2 上下文管理优化

通过渐进式披露（Progressive Disclosure）机制，Skill 避免上下文膨胀：

  • 渐进式披露：像阅读手册一样，先看目录，遇到问题再深入阅读具体章节，而不是一次性加载整本书
  • 上下文膨胀：上下文越长，AI 处理效率越低，重要信息容易被稀释
flowchart TB subgraph 阶段1["层级1: 元数据 (始终加载)"] A1[name + description<br/>~100 words] end subgraph 阶段2["层级2: SKILL.md (触发后加载)"] A2[核心指令<br/>~500 lines] end subgraph 阶段3["层级3: 资源文件 (按需加载)"] A3[scripts/] A4[references/] A5[assets/] end A1 --> A2 --> A3 A2 --> A4 A2 --> A5

2.3 专业化能力扩展

Skill 使 AI 能够：

能力类型说明示例
领域专家垂直领域知识金融、医疗、法律
工具大师专业工具操作Git、Docker、K8s
流程自动化多步骤复杂工作流CI/CD、代码审查
格式规范输出格式标准化文档、报表、代码风格

三、Skill 的技术架构

3.1 必需部分

SKILL.md

每个 Skill 必须包含 SKILL.md 文件，包含两部分：

YAML Frontmatter（元数据）

---
name: skill-name
description: 技能描述（触发条件和使用场景）
---

示例：

---
name: openclaw-git-manager
description: |
  OpenClaw 工作空间 Git 管理工具。
  用于：(1) 初始化 Git 仓库 (2) 提交更改 (3) 创建分支 
  (4) 推送代码 (5) 查看状态
---

description 编写要点：这是 Skill 触发的关键依据，必须清晰说明：

  • 技能功能
  • 触发场景（用户可能怎么说）
  • 适用情境

Markdown 正文

正文是 Skill 的核心指导内容，建议：

  • 简洁明了，< 500 行
  • 包含使用示例
  • 链接到 references/ 文件获取详细文档

3.2 可选部分：

Bundled Resources

graph TD A[skill-name/] --> B[SKILL.md ✓ 必需] A --> C[scripts/ 可选] A --> D[references/ 可选] A --> E[assets/ 可选] C --> C1[可执行脚本] C --> C2[Python/Bash] D --> D1[参考文档] D --> D2[API 文档] D --> D3[领域知识] E --> E1[静态资源] E --> E2[模板文件]

scripts/ - 可执行脚本

  • 用途：需要确定性执行的代码
  • 优势：无需加载到上下文，可直接执行
  • 示例： 
    scripts/
├── rotate_pdf.py
├── deploy.sh
└── validate.sh

references/ - 参考文档

  • 用途：需要时加载到上下文的文档
  • 示例： 
    references/
├── api_schema.md
├── company_policy.md
└── workflow_guide.md

assets/ - 静态资源

  • 用途：最终输出中使用的文件
  • 示例： 
    assets/
├── logo.png
├── template.html
└── frontend-boilerplate/

非标准目录

除官方规定的 scripts/、references/、assets/ 外，Skill 开发者可根据项目需要创建额外目录（如 docs/、templates/、test/）。这些目录不会被自动打包，但可用于项目内部的文档管理、模板存储或测试验证。

四、Skill 命名规范

4.1 命名规则

规则说明示例
字符小写字母、数字、连字符git-manager
长度建议 < 64 字符openclaw-git-manager
格式字母开头，禁止特殊字符✅ abc / ❌ -abc

4.2 命名空间使用

flowchart LR A[工具前缀] --> B[功能描述] subgraph 示例 C[gh-] --> D[address-comments] E[linear-] --> F[address-issue] G[openclaw-] --> H[git-manager] end

4.3 最佳实践

  • ✅ 使用动词短语：git-manager, doc-generator
  • ✅ 简洁明了：pdf-tool 优于 comprehensive-pdf-processing-utility
  • ✅ 统一前缀：openclaw-* 系列

五、Skill 创建流程

5.1 流程概览

flowchart LR A[理解需求] --> B[规划资源] B --> C[初始化模板] C --> D[编辑实现] D --> E[打包发布] E --> F[迭代优化] style A fill:#9f9 style F fill:#9f9

5.2 详细步骤

第一步：理解需求（Concrete Examples）

收集具体使用场景：

## 用户可能这样问：
- "帮我初始化一个 Git 仓库"
- "创建新分支并推送"
- "查看当前状态"

第二步：规划资源内容

资源类型判断标准示例
scripts/代码需确定性执行脚本、CLI 工具
references/需要查阅的文档API 文档、模板
assets/输出中直接使用的文件图片、模板

第三步：初始化模板

scripts/init_skill.py <skill-name> --path <output-dir>

脚本核心逻辑（伪代码）：

# init_skill.py 核心逻辑
def init_skill(name, path, resources):
    create_directory(f"{path}/{name}")
    write_file(f"{path}/{name}/SKILL.md", generate_template(name))
    for res in resources:
        create_directory(f"{path}/{name}/{res}/")

第四步：编辑实现

  • 编写 SKILL.md
  • 实现 scripts/ 脚本
  • 准备 references/ 文档
  • 整理 assets/ 资源

第五步：打包发布

scripts/package_skill.py <path/to/skill-folder>

脚本核心逻辑（伪代码）：

# package_skill.py 核心逻辑
def package_skill(skill_path):
    validate_yaml(skill_path)          # 验证 YAML 格式
    validate_naming(skill_path)        # 验证命名规范
    check_no_symlinks(skill_path)      # 安全检查：禁止 symlink
    zip_files(skill_path, f"{skill_path}.skill")  # 打包成 .skill

生成 .skill 文件（本质是 zip 包）

第六步：迭代优化

根据使用反馈持续改进

六、核心设计原则

6.1 渐进式披露（Progressive Disclosure）

通俗理解：像查字典一样——先看索引定位章节，需要时再深入阅读具体内容，而不是一次性把整本书塞进脑子。

flowchart TB subgraph 原则 A[最小化初始加载] --> B[按需加载详情] B --> C[保持 SKILL.md 精简] end subgraph 实现方式 D[核心流程在 SKILL.md] E[详细文档在 references/] F[代码在 scripts/] end

实践要点：

  • SKILL.md 建议 < 500 行
  • 长内容拆分到 reference 文件
  • 链接形式引导按需加载

6.2 上下文精简原则

通俗理解：上下文就像工作记忆，塞得越多越容易”失忆”——AI 也会因为信息过载而遗漏重点。

pie title 上下文占用分布 "系统提示词" : 30 "对话历史" : 25 "Skill 元数据" : 5 "Skill 正文" : 10 "用户请求" : 20 "其他 Skill" : 10

核心原则：

默认假设：AI 已经很聪明了

只添加 AI 本身不具备的上下文。

6.3 自由度把控

自由度级别适用场景实现方式
高多种方案均可、依赖上下文判断文本指令
中有最佳实践、允许一定变化伪代码/参数化脚本
低操作脆弱、必须精确执行固定脚本+极少参数
flowchart LR A[任务特性] --> B{决策} B -->|多方案可行| C[高自由度] B -->|有最佳实践| D[中自由度] B -->|必须精确| E[低自由度] C --> F[宽泛指令] D --> G[参数化脚本] E --> H[固定流程]

七、实战案例

7.1 openclaw-git-manager 案例

项目结构：

openclaw-git-manager/
├── SKILL.md           # 技能定义
├── config.json        # 配置文件
├── scripts/           # 可执行脚本
│   ├── git_init.sh
│   ├── git_commit.sh
│   └── git_push.sh
├── docs/              # 参考文档（非标准目录）
├── templates/         # 模板文件（非标准目录）
├── demo.sh           # 演示脚本
└── test.sh           # 测试脚本

非标准目录说明：除官方规定的 scripts/、references/、assets/ 外，Skill 开发者可根据项目需要创建额外目录（如 docs/、templates/、test/）。这些目录不会被自动打包，但可用于项目内部的文档管理、模板存储或测试验证。

核心功能：

  • Git 仓库初始化
  • 提交更改管理
  • 分支创建与切换
  • 远程推送
  • 状态查看

开发亮点：

  • 完整错误处理
  • 内存系统集成
  • 心跳系统支持
  • 安全性验证

7.2 skill-creator 模板

使用方式：

# 初始化新 Skill
scripts/init_skill.py my-skill --path ./skills

# 指定资源类型
scripts/init_skill.py my-skill --path ./skills --resources scripts,references

# 打包发布
scripts/package_skill.py ./skills/my-skill

八、最佳实践与避坑指南

8.1 必须避免的错误

❌ 错误做法✅ 正确做法
SKILL.md 超过 1000 行拆分到 references/
包含 README.md只保留 SKILL.md
信息重复存储单一数据源
模糊的 description详细的触发条件说明
缺少示例提供 Concrete Examples

8.2 质量检查清单

## SKILL.md 检查

- [ ] name 符合命名规范（小写+连字符）
- [ ] description 包含触发条件
- [ ] 正文 < 500 行
- [ ] 链接到所有 reference 文件
- [ ] 包含使用示例

## 资源文件检查

- [ ] scripts/ 目录结构清晰
- [ ] references/ 文档内容准确
- [ ] assets/ 文件可用

## 整体检查

- [ ] 可正常打包
- [ ] 无 symlink（安全限制）
- [ ] 目录名与 skill 名一致

8.3 进阶技巧

模式一：领域细分

bigquery-skill/
├── SKILL.md
└── references/
    ├── finance.md
    ├── sales.md
    ├── product.md
    └── marketing.md

模式二：框架变体

cloud-deploy/
├── SKILL.md
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

模式三：条件细节

## 基础用法
使用 docx-js 创建文档

## 进阶功能
- 追踪修订：见 [REDLINING.md](REDLINING.md)
- OOXML 细节：见 [OOXML.md](OOXML.md)

总结

Skill 是 AI 时代软件工程的重要范式，它：

  1. 标准化 - 统一的架构和规范
  2. 模块化 - 解耦与复用
  3. 专业化 - 垂直领域能力扩展
  4. 可扩展 - 持续迭代优化

掌握 Skill 开发，让你的 AI 助手真正成为专业领域的行家里手。

下一步：从简单 Skill 开始实践，尝试运行 init_skill.py 初始化你的第一个 Skill

文档版本：v1.0
最后更新：2026年3月
作者：Wisdom