全面掌握 AI Skills：从概念理解到实战落地的完整指南

一、什么是 Skills？

1.1 概念定义

Skills（技能）是 AI 编程助手中的一种能力扩展机制 ，它将某一类任务的经验、流程、标准、模板和注意事项整理成一个结构化的配置文件（SKILL.md），使 AI 在遇到匹配的任务时能够自动按照预定义的流程执行。

通俗地说：

普通 Prompt 是你每次都要重新教 AI 怎么做一件事。 Skills 是你提前写好一份"岗位培训手册"，AI 遇到相关任务就自动照着手册执行。

1.2 一个直觉类比

把 AI 想象成一个聪明但没经验的实习生：

你的做法	等价于	效果
每次口头交代任务	普通 Prompt	每次理解可能不同，容易遗漏
写一份固定的口头禅/偏好	Rule	告诉 AI "我一直喜欢这样做"
给 AI 一把新工具	MCP / Tools	让 AI 能做之前做不了的事
写一份完整的工作手册	Skill	让 AI 按标准流程执行特定任务

1.3 实际案例

假设你经常需要把技术文章改成公众号风格。没有 Skill 时，每次你都要说：

python 复制代码

帮我把这篇文章改成公众号风格，语言要自然一点，标题吸引人一点，
分段要合理，加个导语，最后用 Markdown 格式输出......

一旦要求变多，就容易漏掉某个条件。而有了 Skill 之后，你只需要说：

复制代码

使用「技术文章转公众号」Skill 处理这篇文章

AI 就会自动按照你提前写好的完整流程执行，不会遗漏任何步骤。

二、为什么需要 Skills？

2.1 AI 的"健忘症"问题

AI 大语言模型有一个根本性的特点：每次对话都是独立的。这意味着：

同一个提示词，今天和明天生成的结果可能风格迥异
复杂要求容易被遗忘或误解
没有"肌肉记忆"，每次都要从零开始理解

这就是 AI 的"健忘症"------它不会因为你上次让它用某种风格写文章，这次就自动延续那个风格。

2.2 Skills 解决的四个核心问题

python 复制代码

                    Skills 的核心价值

    ┌─────────────────────────────────────────────┐
    │                                             │
    │   稳定性 ──→ 每次输出风格一致、质量可控          │
    │                                             │
    │   效率   ──→ 不用反复描述需求，一键触发          │
    │                                             │
    │   专业性 ──→ 融入行业经验、最佳实践              │
    │                                             │
    │   可复用 ──→ 写一次，团队共享，永久生效          │
    │                                             │
    └─────────────────────────────────────────────┘

稳定性：没有 Skill 时，AI 的输出全凭"运气"。有了 Skill，每次输出都遵循同一套标准和流程，质量波动被控制在最小范围内。

效率：把重复性的指令编写工作从"每次对话"压缩到"一次编写，永久复用"。对于高频任务，效率提升尤为显著。

专业性：Skill 中可以融入你的行业经验、踩坑总结、最佳实践。AI 不再是一个通用工具，而是一个经过专业培训的助手。

可复用：Skill 文件可以版本管理、团队共享、持续迭代。一个人编写的 Skill，整个团队都能受益。

2.3 Skills 的适用场景

Skills 特别适合以下场景------只要满足"经常重复做、又希望标准统一"这两个条件，就值得做成 Skill：

内容创作类：

技术博客/公众号文章写作
论文润色与改写
课程设计与教案编写
PPT 内容生成
文档翻译

开发工程类：

代码审查（Code Review）
命名规范检查
单元测试生成
API 文档生成
Git Commit 信息规范化

办公效率类：

日报/周报/月报生成
会议纪要整理
邮件撰写
简历优化
销售话术生成

数据处理类：

CSV/JSON 数据清洗
日志分析
数据可视化描述生成

三、Skills 与 Prompt、Rule、MCP/Tools 的区别

3.1 四者关系总览

在 AI 编程助手的生态中，有四种核心交互机制，它们各司其职，解决不同层面的问题：

python 复制代码

                    AI 协作机制全景图

        ┌─────────────────────────────────────────┐
        │                                         │
        │  Prompt（临时交代）                       │
        │  "这次帮我做这个，要求是......"                 │
        │  一次性、即时、灵活                        │
        │                                         │
        ├─────────────────────────────────────────┤
        │                                         │
        │  Rule（长期偏好）                         │
        │  "我一直都希望你这样做......"                  │
        │  持久、简单、全局生效                      │
        │                                         │
        ├─────────────────────────────────────────┤
        │                                         │
        │  MCP / Tools（外部能力）                  │
        │  "你现在可以访问数据库、调用 API......"         │
        │  扩展能力边界、连接外部系统                 │
        │                                         │
        ├─────────────────────────────────────────┤
        │                                         │
        │  Skills（专业流程）                       │
        │  "遇到这类任务，按这份手册执行"              │
        │  结构化、可复用、场景驱动                   │
        │                                         │
        └─────────────────────────────────────────┘

3.2 逐一解析

3.2.1 普通 Prompt（临时交代）

普通 Prompt 是最基础的交互方式，就是你每次临时给 AI 交代任务：

复制代码

帮我把这篇文章改成公众号风格，语言要自然一点，标题吸引人一点。

特点：

一次性使用，对话结束即失效
灵活但不稳定，每次理解可能不同
适合临时性、非重复性的任务

问题：要求一复杂就容易遗漏，且无法保证一致性。

3.2.2 Rule（长期偏好）

Rule 是你设定的长期偏好，类似于告诉 AI "这是我一直喜欢的风格"：

python 复制代码

# Rule 示例
- 代码注释使用中文
- 函数命名使用驼峰命名法
- 回答问题时先给结论，再展开解释

特点：

全局生效，每次对话都会自动加载
适合简短的偏好设置
无法表达复杂的多步骤流程

局限：Rule 更像是"个人习惯声明"，无法承载复杂的任务流程。

3.2.3 MCP / Tools（外部能力）

MCP（Model Context Protocol）或 Tools 是给 AI 接入外部能力的机制：

python 复制代码

# MCP 示例
- 连接数据库，执行 SQL 查询
- 调用浏览器，抓取网页内容
- 操作文件系统，读写本地文件
- 接入 API，获取第三方数据

特点：

扩展 AI 的能力边界
解决的是"AI 能不能做某个动作"的问题
不涉及"怎么做"的方法论

局限：有了锤子不代表会钉钉子。MCP 给了 AI 工具，但没有教它怎么用好这些工具。

3.2.4 Skills（专业流程）

Skills 是一套完整的任务执行方案：

python 复制代码

# Skill 示例：代码审查
## 使用场景
当用户提交代码要求审查时使用。

## 审查流程
1. 先检查代码风格是否符合团队规范
2. 检查潜在的 Bug 和安全漏洞
3. 评估代码的可读性和可维护性
4. 给出具体的修改建议和代码示例

## 输出格式
- 问题等级：🔴 严重 / 🟡 建议 / 🟢 优秀
- 问题描述
- 修改建议
- 示例代码

特点：

场景驱动，按需加载
包含完整的流程、标准和模板
解决的是"AI 应该按照什么方法做"的问题

3.3 对比总结

维度	Prompt	Rule	MCP / Tools	Skills
本质	临时口令	长期偏好	外部工具	操作手册
生命周期	一次性	持久	持久	持久
复杂度	简单到中等	简单	中等	中等到复杂
解决的问题	这次做什么	一直怎么做	能做什么	按什么流程做
适用场景	临时任务	个人习惯	能力扩展	标准化流程
可复用性	低	中	中	高
团队共享	困难	容易	容易	容易

一句话总结：

Prompt 是临时交代，Rule 是长期偏好，MCP 是外部能力，Skills 是专业流程。

四、Skills 的核心机制：按需加载与渐进式披露

4.1 机制说明

Skills 采用的核心工作机制叫做 按需加载（On-demand Loading）+ 渐进式披露（Progressive Disclosure）。

这意味着 AI 不会在对话开始时就把所有 Skill 的完整内容加载到上下文中，而是分三步完成：

4.2 三步工作流程

python 复制代码

    Skills 工作流程

    第一步：发现（Discovery）
    ─────────────────────────
    AI 扫描所有已安装的 Skill，
    读取每个 Skill 的 name 和 description，
    建立一个"能力索引"。
              │
              ▼
    第二步：激活（Activation）
    ─────────────────────────
    当用户的任务描述与某个 Skill 的
    description 匹配时，AI 打开该
    Skill 的完整 SKILL.md。
              │
              ▼
    第三步：执行（Execution）
    ─────────────────────────
    AI 按照 SKILL.md 中定义的步骤、
    模板、规则和输出格式完成任务。
    如有需要，还会按需读取引用的
    模板、示例、脚本等辅助文件。

4.3 详细说明

第一步：发现（Discovery）

AI 在对话开始时，只会读取每个 Skill 文件夹中的 name 和 description 字段。它建立的是一张"能力索引表"：

python 复制代码

已安装 Skills 索引：

  [1] python-naming-standard
      → Python 代码命名规范检查

  [2] wechat-article-writer
      → 技术文章转公众号风格

  [3] code-review-expert
      → 代码审查与质量评估

  [4] weekly-report-generator
      → 周报自动生成

这一步不会消耗大量上下文空间，AI 只需要知道"我有哪些能力"。

第二步：激活（Activation）

当用户的任务描述触发了某个 Skill 的匹配条件时，AI 才会读取该 Skill 的完整内容。

例如，用户说：

复制代码

帮我把这篇技术文章改成公众号风格

AI 在索引表中匹配到 wechat-article-writer 的 description："当用户需要将普通素材整理成公众号文章时使用"，于是激活这个 Skill，读取完整的 SKILL.md。

第三步：执行（Execution）

AI 按照 SKILL.md 中的工作流程逐步执行任务。如果 Skill 中引用了其他文件（模板、示例、脚本等），AI 会根据需要按需读取：

python 复制代码

# 在 SKILL.md 中引用其他文件

如果用户需要公众号文章结构，请参考 templates/article-template.md。

如果用户要求判断文章质量，请参考 examples/good-example.md。

如果需要批量清洗文本，可以执行 scripts/process.py。

这种设计的好处是：AI 不需要一次性把所有资料都读进上下文，而是用到什么读什么，既节省上下文空间，又保证了响应的精准性。

五、SKILL.md 的基本结构

5.1 文件组织

一个 Skill 的最小组成就是一个文件夹加一个 SKILL.md 文件：

python 复制代码

my-skill/
└── SKILL.md

5.2 SKILL.md 的内部结构

一个标准的 SKILL.md 由两部分组成：

python 复制代码

---
# 【第一部分：元数据（YAML Front Matter）】
# 告诉 AI 这个 Skill 叫什么、什么时候用
---
name: skill-name
description: 一句话说明功能和适用场景
---

# 【第二部分：正文指令（Markdown Body）】
# 告诉 AI 具体怎么做

## 使用场景
## 工作流程
## 输出格式
## 质量标准
## 注意事项

5.3 最小可用示例

下面是一个最简单的、可以直接使用的 SKILL.md：

python 复制代码

---
name: article-polisher
description: 用于将普通文章润色成结构清晰、表达自然、适合公众号发布的文章。当用户要求润色、改写或优化文章时使用。
---

# 文章润色 Skill

## 使用场景

当用户要求润色文章、改写文章、优化公众号文案时，使用本 Skill。

## 工作流程

1. 先判断文章主题和目标读者。
2. 保留原文核心意思，不随意编造。
3. 优化标题，使其更清晰、有吸引力。
4. 调整段落结构，让文章更容易阅读。
5. 优化语言表达，避免生硬、重复、空泛。
6. 最后输出适合公众号发布的 Markdown 格式。

## 输出格式

请按照以下格式输出：

1. 标题
2. 导语（一两句话概括文章核心价值）
3. 正文（分段清晰，适当使用小标题）
4. 总结（提炼要点）
5. 可选金句（可用于社交媒体传播的一句话）

## 质量标准

- 不改变原文核心观点
- 语言自然流畅，避免 AI 味
- 段落长度适中，每段不超过 4 行
- 标题有吸引力但不标题党

六、SKILL.md 各字段详解

6.1 元数据字段

SKILL.md 最上方是一段 YAML 格式的元数据，被 --- 包裹：

python 复制代码

---
name: skill-name
description: 说明这个 Skill 的功能和适用场景
---

6.1.1 name 字段

name 是 Skill 的唯一标识符，AI 通过它来识别和引用 Skill。

编写规则：

规则	说明	示例
使用英文	不要用中文	`code-review` ✅ `代码审查` ❌
小写字母	全部小写	`article-writer` ✅ `Article-Writer` ❌
用连字符分隔	不要用空格或下划线	`pdf-processor` ✅ `pdf_processor` ❌ `pdf processor` ❌
不以连字符开头或结尾	避免歧义	`naming-standard` ✅ `-naming-standard` ❌
简洁明了	尽量在 2-4 个词之间	`wechat-article-writer` ✅ `a` ❌

推荐命名模式：

python 复制代码

[对象]-[动作]
[领域]-[功能]
[工具]-[用途]

优秀示例：

python 复制代码

code-review-expert          # 代码审查专家
pdf-processing              # PDF 处理
wechat-article-writer       # 公众号文章写作
python-naming-standard      # Python 命名规范
weekly-report-generator     # 周报生成器
api-doc-generator           # API 文档生成器
git-commit-formatter        # Git 提交信息格式化
sql-query-optimizer         # SQL 查询优化器

6.1.2 description 字段

description 是 Skill 是否能被正确触发的关键字段。AI 在第一步"发现"阶段只看 name 和 description，所以 description 写得越精准，AI 越容易判断何时应该激活这个 Skill。

编写公式：

复制代码

当用户需要【具体任务】时使用。本 Skill 会按照【核心流程】完成【最终输出】。

反面教材 vs 正面示例：

python 复制代码

# ❌ 差的 description：太宽泛
description: 帮助写文章
# AI 无法判断：什么类型的文章？什么场景下用？

# ❌ 差的 description：太模糊
description: 一个好用的工具
# 完全无法触发，因为不知道什么时候该用

# ✅ 好的 description：清晰具体
description: 当用户需要将普通素材整理成公众号文章、营销文章、课程推文或知识科普文时使用。本 Skill 会优化标题、结构、语言风格，并输出 Markdown 格式。
# 清楚说明了：适用任务（公众号/营销/课程/科普）、执行动作（优化标题/结构/风格）、输出格式（Markdown）

更多优秀 description 示例：

python 复制代码

# 代码审查 Skill
description: 当用户提交代码片段要求审查、查找 Bug、评估代码质量或给出改进建议时使用。本 Skill 会从代码风格、潜在缺陷、安全漏洞、性能问题和可维护性五个维度进行审查，并按严重程度分级输出审查结果。

# 周报生成 Skill
description: 当用户需要整理本周工作内容并生成周报时使用。本 Skill 会根据用户提供的工作记录、会议纪要和项目进展，按照"本周完成、下周计划、风险与问题"的结构生成标准化周报。

# SQL 优化 Skill
description: 当用户提交 SQL 查询语句并要求优化性能时使用。本 Skill 会分析查询执行计划，识别性能瓶颈，给出索引建议、查询重写方案和优化后的 SQL 代码。

6.2 正文指令字段

正文部分是 Skill 的核心，包含 AI 执行任务时需要遵循的所有指导。以下是常用的正文结构模块：

6.2.1 角色定位（可选但推荐）

为 AI 设定一个专家身份，有助于提升输出的专业度：

python 复制代码

## 角色定位

你现在是一位拥有 10 年经验的技术写作专家。
你的任务是帮助技术团队将复杂的技术内容转化为通俗易懂、结构清晰的技术文档。

6.2.2 使用场景

明确定义什么情况下应该激活这个 Skill：

python 复制代码

## 使用场景

当用户提出以下需求时，使用本 Skill：

- 要求将技术文章改写为公众号风格
- 要求优化文章标题和结构
- 要求将长文精简为适合社交媒体传播的版本
- 要求为技术博客文章添加导语和总结

6.2.3 不适用场景（推荐）

明确定义什么情况下不应该使用这个 Skill，避免误触发：

python 复制代码

## 不适用场景

以下情况不要使用本 Skill：

- 用户要求撰写学术论文（应使用论文写作 Skill）
- 用户要求翻译文章（应使用翻译 Skill）
- 用户要求撰写纯营销广告文案（应使用营销文案 Skill）
- 用户只是简单问一个问题，不涉及文章改写

6.2.4 工作流程

这是 Skill 最核心的部分，定义 AI 执行任务的具体步骤：

python 复制代码

## 工作流程

请严格按照以下步骤执行：

1. **理解输入**：阅读用户提供的原始内容，判断文章主题、目标读者和核心观点。
2. **拟定标题**：根据文章核心，提供 3 个备选标题，选择最合适的。
3. **撰写导语**：用 1-2 句话概括文章的核心价值，激发读者阅读兴趣。
4. **优化正文**：
   - 保留原文核心信息，不编造新内容
   - 拆分过长段落，每段不超过 4 行
   - 添加小标题，增强可读性
   - 优化语言表达，避免生硬翻译腔
5. **撰写总结**：提炼 3-5 个核心要点。
6. **生成金句**：提供 1-2 句可用于社交媒体传播的精炼语句。
7. **格式输出**：按指定格式输出 Markdown。

6.2.5 输出格式

明确指定 AI 输出的结构和格式：

python 复制代码

## 输出格式

请严格按照以下 Markdown 格式输出：

```markdown
# [标题]

> [导语：一句话概括核心价值]

## 正文

[正文内容，使用小标题分段]

## 核心要点

- 要点 1
- 要点 2
- 要点 3

## 金句

> [可用于传播的一句话]

python 复制代码

#### 6.2.6 质量标准

定义输出的质量底线：

```markdown
## 质量标准

输出必须满足以下所有条件：

- **准确性**：不改变原文的核心观点和事实
- **可读性**：语言自然流畅，避免 AI 味过重
- **完整性**：不遗漏原文的关键信息
- **实用性**：读者看完后能获得实际价值
- **格式规范**：严格遵循指定的 Markdown 格式

6.2.7 注意事项

补充边界条件和特殊情况的处理方式：

python 复制代码

## 注意事项

- 不要改变用户原文的核心观点
- 不要输出与文章无关的内容
- 如果原文信息不足，先基于现有信息给出合理版本，并在文末说明做了哪些假设
- 如果原文涉及专业术语，首次出现时请给出简要解释
- 标题控制在 20 字以内
- 全文总字数控制在 1500-3000 字之间

七、实战案例：从零创建 Skill

7.1 实战一：Python 命名规范 Skill

需求：要求 AI 在写 Python 代码时，内部辅助函数必须使用 _internal_ 前缀。

第一步：创建 Skill 文件夹

复制代码

mkdir -p python-naming-standard

第二步：创建 SKILL.md

复制代码

touch python-naming-standard/SKILL.md

第三步：编写 Skill 内容

python 复制代码

---
name: python-naming-standard
description: 当用户要求编写、重构或审查 Python 代码时，检查并规范内部辅助函数的命名。确保所有内部函数使用 _internal_ 前缀，公共函数使用清晰的动词开头命名。
---

# Python 内部命名规范 Skill

## 角色定位

你是一位 Python 代码规范专家，熟悉 PEP 8 规范以及企业级 Python 项目的命名最佳实践。

## 使用场景

当用户提出以下需求时，使用本 Skill：

- 要求编写 Python 代码
- 要求重构 Python 代码
- 要求审查 Python 代码的命名规范
- 要求提交代码前检查命名是否合规

## 命名规则

### 内部辅助函数

1. 所有内部辅助函数（不对外暴露的工具函数）必须使用 `_internal_` 前缀。
2. 前缀后的函数名使用小写字母和下划线，描述函数的核心动作。
3. 如果发现内部函数没有使用 `_internal_` 前缀，必须提出修改建议。

### 公共函数

1. 公共函数使用清晰的动词开头，如 `get_`、`calculate_`、`validate_`、`process_`。
2. 不要随意修改已有的公共函数名，除非用户明确要求。

### 类命名

1. 类名使用 PascalCase（大驼峰命名法）。
2. 内部类使用 `_Internal` 前缀。

### 变量命名

1. 普通变量使用 snake_case（小写字母加下划线）。
2. 常量使用全大写加下划线，如 `MAX_RETRY_COUNT`。
3. 私有变量使用单下划线前缀，如 `_cache`。

## 正确示例

```python
# 内部辅助函数 - 使用 _internal_ 前缀
def _internal_calculate_discount(user_score: float) -> float:
    """根据用户评分计算折扣比例。"""
    if user_score >= 90:
        return 0.2
    if user_score >= 70:
        return 0.1
    return 0.0

def _internal_format_price(price: float, currency: str = "CNY") -> str:
    """将价格格式化为带货币符号的字符串。"""
    symbols = {"CNY": "¥", "USD": "$", "EUR": "€"}
    symbol = symbols.get(currency, currency)
    return f"{symbol}{price:.2f}"

# 公共函数 - 清晰的动词开头
def get_user_discount(user_id: int) -> float:
    """获取用户的折扣比例。"""
    user_score = _internal_get_user_score(user_id)
    return _internal_calculate_discount(user_score)

def calculate_total_price(items: list, user_id: int) -> float:
    """计算订单总价（含折扣）。"""
    subtotal = sum(item["price"] for item in items)
    discount = get_user_discount(user_id)
    return subtotal * (1 - discount)

错误示例

python 复制代码

# ❌ 错误：内部函数缺少 _internal_ 前缀
def _calculate_discount(user_score: float) -> float:
    """这里只用了单下划线，不符合规范。"""
    if user_score >= 90:
        return 0.2
    return 0.0

# ❌ 错误：内部函数完全没有前缀
def format_price(price: float) -> str:
    """这是内部函数，但命名看起来像公共函数。"""
    return f"¥{price:.2f}"

# ❌ 错误：公共函数命名不清晰
def discount(score):
    """缺少动词前缀，不清楚这个函数做什么。"""
    return score * 0.1

输出要求

当用户要求写代码时：

1.先输出符合规范的完整代码。
2.在代码后简要说明命名设计思路：
- 哪些是内部函数，为什么用 _internal_ 前缀
- 哪些是公共函数，命名遵循什么规则
- 如果有需要用户确认的设计决策，请明确指出

当用户要求审查代码时：

1.逐个检查所有函数的命名。
2.列出不符合规范的位置，格式如下：

python 复制代码

🔴 问题：[函数名]
   位置：第 X 行
   当前命名：xxx
   建议命名：xxx
   原因：xxx

3.给出修改后的完整代码。

python 复制代码

### 7.2 实战二：技术文章转公众号 Skill

**需求**：将技术文章自动改写为适合微信公众号发布的风格。

```markdown
---
name: tech-article-to-wechat
description: 当用户需要将技术文章、博客文章或知识文档改写为适合微信公众号发布的文章时使用。本 Skill 会优化标题、调整结构、润色语言、添加导语和互动引导，输出适合直接粘贴到公众号编辑器的 Markdown 格式。
---

# 技术文章转公众号 Skill

## 角色定位

你是一位深耕技术领域的新媒体编辑，既懂技术又懂传播。你的目标是让复杂的技术内容变得通俗易懂，同时保持专业性和准确性。

## 使用场景

当用户提出以下需求时，使用本 Skill：

- 将技术博客文章改写为公众号风格
- 将技术文档转化为科普文章
- 将英文技术文章改写为中文公众号文章
- 为技术文章优化标题和结构
- 将课程讲义整理为公众号推文

## 不适用场景

- 用户要求撰写纯学术论文
- 用户要求翻译但不改写（应使用翻译 Skill）
- 用户要求撰写产品广告文案

## 公众号文章写作规范

### 标题规范

1. 控制在 15-25 字之间
2. 必须包含核心价值点
3. 避免纯标题党，要名副其实
4. 可以适当使用数字增强吸引力
5. 提供 3 个备选标题供用户选择

### 段落规范

1. 每段不超过 4 行（手机阅读友好）
2. 关键信息加粗标注
3. 适当使用列表增强可读性
4. 代码块使用语法高亮标记
5. 段落之间留有呼吸感

### 语言风格

1. 口语化但不随意，专业但不晦涩
2. 多用短句，少用长句
3. 用"你"代替"您"，拉近距离
4. 适当使用设问句引发思考
5. 避免翻译腔和学术腔

### 结构规范

1. 开头必须有导语（1-2 句话概括全文价值）
2. 正文分段使用小标题引导
3. 代码示例必须有说明
4. 结尾必须有总结和行动建议
5. 可选：互动引导（提问/投票/留言）

## 工作流程

1. **阅读原文**：理解文章主题、核心技术点、目标读者。
2. **提炼核心**：找出文章的 3-5 个核心知识点。
3. **拟定标题**：提供 3 个备选标题。
4. **撰写导语**：1-2 句话，说明读完这篇文章能获得什么。
5. **改写正文**：
   - 保留原文核心知识点和代码示例
   - 按照公众号规范调整段落长度
   - 添加小标题，引导阅读节奏
   - 润色语言，消除生硬表达
   - 代码示例添加中文注释
6. **撰写总结**：提炼核心要点，给出行动建议。
7. **生成金句**：1-2 句适合社交媒体分享的精炼语句。
8. **格式检查**：确保 Markdown 格式正确。

## 输出格式

```markdown
# [主标题]

> 💡 [导语：一句话说明读完能获得什么]

---

## 一、[小标题 1]

[正文段落]

```python
# 带中文注释的代码示例
def example():
    pass

二、[小标题 2]

正文段落

...

总结

要点 1
要点 2
要点 3

💬 今日讨论

一个与文章相关的问题，引导读者留言互动

python 复制代码

## 质量标准

- 标题吸引力：让人想点进来看
- 内容准确性：技术知识点不能出错
- 可读性：手机端阅读体验流畅
- 专业性：保持技术深度，不过度简化
- 原创性：改写而非简单搬运，有自己的观点和见解

## 注意事项

- 不要编造原文没有的技术信息
- 代码示例必须保持可运行
- 如果原文有错误，在改写时修正并说明
- 全文字数控制在 1500-3000 字
- 如果原文过长，可以分上下篇

7.3 实战三：代码审查 Skill

需求：建立一套标准化的代码审查流程，确保审查质量一致。

python 复制代码

---
name: code-review-expert
description: 当用户提交代码片段要求审查、查找 Bug、评估代码质量或给出改进建议时使用。本 Skill 会从代码风格、潜在缺陷、安全漏洞、性能问题和可维护性五个维度进行审查，按严重程度分级输出审查报告，并给出修改后的完整代码。
---

# 代码审查专家 Skill

## 角色定位

你是一位严格但友善的高级代码审查工程师。你关注代码质量，但理解"完美是好的敌人"。你的审查意见旨在帮助开发者成长，而不是挑刺。

## 使用场景

当用户提出以下需求时，使用本 Skill：

- 提交代码片段要求审查
- 询问代码中是否有潜在 Bug
- 要求评估代码质量
- 要求给出代码改进建议
- 提交 Pull Request 前的自查

## 审查维度

### 1. 代码风格（Style）

- 命名是否清晰、一致
- 缩进和格式是否规范
- 注释是否充分且有价值
- 是否遵循语言社区的惯用写法

### 2. 潜在缺陷（Bugs）

- 边界条件是否处理
- 空值/异常是否考虑
- 逻辑错误和 Off-by-one
- 并发安全问题

### 3. 安全漏洞（Security）

- SQL 注入风险
- XSS 攻击风险
- 敏感信息硬编码
- 不安全的反序列化
- 权限检查缺失

### 4. 性能问题（Performance）

- 不必要的循环或重复计算
- N+1 查询问题
- 大数据量下的内存问题
- 不合理的数据结构选择

### 5. 可维护性（Maintainability）

- 函数是否过长（建议不超过 30 行）
- 是否遵循单一职责原则
- 是否有重复代码可以抽象
- 是否便于单元测试

## 工作流程

1. **通读代码**：理解代码的整体功能和上下文。
2. **逐维度审查**：按照上述 5 个维度逐一检查。
3. **分级标注**：将发现的问题按严重程度分级。
4. **给出建议**：每个问题都要给出具体的修改建议和示例代码。
5. **生成报告**：按指定格式输出审查报告。
6. **提供修改版**：给出修改后的完整代码。

## 问题分级标准

| 等级 | 标记 | 含义 | 处理建议 |
| --- | --- | --- | --- |
| 严重 | 🔴 | 会导致程序崩溃、数据丢失或安全漏洞 | 必须修复 |
| 警告 | 🟡 | 可能导致潜在问题或影响性能 | 建议修复 |
| 建议 | 🔵 | 代码风格或可维护性改进建议 | 可选优化 |
| 优秀 | 🟢 | 值得表扬的好实践 | 保持并推广 |

## 输出格式

```markdown
## 审查报告

### 概述

- 审查文件：[文件名]
- 代码行数：[行数]
- 总体评价：[一句话总结]
- 问题统计：🔴 X 个 / 🟡 X 个 / 🔵 X 个 / 🟢 X 个

### 发现的问题

#### 🔴 [严重] 问题标题

**位置**：第 X-Y 行

**问题描述**：[具体说明问题是什么]

**风险说明**：[说明不修复会导致什么后果]

**修改建议**：

```python
# 修改前
[原始代码]

# 修改后
[修改后的代码]

🟡 [警告] 问题标题

...

优秀实践

🟢 [优秀] 值得表扬的地方

说明这段代码为什么写得好，值得推广

修改后的完整代码

复制代码

[修改后的完整代码]

python 复制代码

## 注意事项

- 先肯定做得好的地方，再指出问题（三明治法则）
- 每个问题都要给出具体的修改方案，不要只说"这里不好"
- 如果不确定某个点是否是问题，用"可能"等限定词，并说明判断依据
- 尊重用户的最终决定权，建议而非命令

八、进阶目录结构与文件引用

8.1 完整目录结构

当 Skill 很简单时，一个 SKILL.md 就够了。但当 Skill 越来越复杂，涉及模板、案例、脚本、参考规范时，就需要扩展目录结构：

python 复制代码

my-skill/
├── SKILL.md                    # 核心指令文件
├── templates/                  # 模板目录
│   ├── article-template.md     # 文章模板
│   └── report-template.md      # 报告模板
├── examples/                   # 示例目录
│   ├── good-example.md         # 优秀示例（AI 学习的标杆）
│   └── bad-example.md          # 反面示例（AI 需要避免的典型）
├── references/                 # 参考资料目录
│   ├── writing-rules.md        # 写作规范
│   └── style-guide.md          # 风格指南
└── scripts/                    # 脚本目录
    ├── process.py              # 数据处理脚本
    └── check.sh                # 检查脚本

8.2 各子目录的作用

目录	作用	使用场景
`templates/`	存放输出模板	AI 按照模板的结构生成内容
`examples/`	存放正/反面示例	AI 通过对比学习什么是好的、什么是不好的
`references/`	存放规范和指南	AI 在需要时查阅特定的规范细节
`scripts/`	存放可执行脚本	AI 调用脚本完成自动化处理

8.3 在 SKILL.md 中引用其他文件

在 SKILL.md 中可以使用自然语言引用这些文件，AI 会在需要时按需读取：

python 复制代码

## 模板引用

如果用户需要生成公众号文章，请参考 `templates/article-template.md` 的结构。
如果用户需要生成周报，请参考 `templates/report-template.md` 的结构。

## 示例引用

在生成内容前，请先参考：
- `examples/good-example.md`，学习优秀输出的标准
- `examples/bad-example.md`，了解需要避免的常见错误

## 规范引用

关于写作风格的具体要求，请查阅 `references/style-guide.md`。
关于行业术语的使用规范，请查阅 `references/writing-rules.md`。

## 脚本引用

如果用户提供了原始数据文件，需要先执行 `scripts/process.py` 进行数据清洗。
输出前请执行 `scripts/check.sh` 进行格式校验。

8.4 示例文件的编写

good-example.md（优秀示例）

python 复制代码

# 优秀公众号文章示例

## 标题
深入浅出：5 分钟搞懂 Python 装饰器

## 导语
> 装饰器是 Python 中最优雅的特性之一，但很多人学了好几遍还是云里雾里。
> 这篇文章用最通俗的语言和生活中的例子，帮你一次彻底搞懂。

## 正文片段
想象你开了一家咖啡店。每次客人点咖啡，你都要：接单 → 做咖啡 → 端给客人。
后来你雇了一个服务员，流程变成了：服务员接单 → 你做咖啡 → 服务员端给客人。
这个服务员就是"装饰器"------他没有改变你做咖啡的核心流程，
但在前后各加了一步。

```python
def waiter(func):
    def wrapper(*args, **kwargs):
        print("您好，请问需要点什么？")  # 前置操作
        result = func(*args, **kwargs)     # 核心操作
        print("请慢用！")                  # 后置操作
        return result
    return wrapper

@waiter
def make_coffee(coffee_type):
    return f"正在制作{coffee_type}..."

python 复制代码

#### bad-example.md（反面示例）

```markdown
# 反面示例：需要避免的问题

## 问题 1：导语太空泛
❌ "本文将介绍 Python 装饰器的相关知识。"
   → 没有告诉读者为什么要读、读完能得到什么

✅ "装饰器是 Python 面试必考题，也是写出优雅代码的关键。读完这篇，你不仅能理解原理，还能在项目中实际使用。"

## 问题 2：代码没有解释
❌ 直接贴一大段代码，没有任何文字说明
   → 读者不知道代码在做什么，为什么要这样写

✅ 每段代码前用一句话说明"这段代码做了什么"，关键行添加行内注释

## 问题 3：段落太长
❌ 一个段落写了 10 行，手机上要滑很久
   → 公众号是手机阅读，段落必须短

✅ 每个段落控制在 3-4 行以内

九、实用 Skill 通用模板

以下是一个可直接复制、按需修改的通用 Skill 模板：

python 复制代码

---
name: your-skill-name
description: 当用户需要【具体任务】时使用。本 Skill 会按照【核心流程】完成【最终输出】。
---

# Skill 名称

## 角色定位

你现在是【某领域专家】。
你的任务是帮助用户完成【具体任务】。

## 使用场景

当用户提出以下需求时，使用本 Skill：

- 场景 1：[具体描述]
- 场景 2：[具体描述]
- 场景 3：[具体描述]

## 不适用场景

以下情况不要使用本 Skill：

- 情况 1：[具体描述]
- 情况 2：[具体描述]

## 前置条件

在开始执行前，请确认以下信息：

- [ ] 用户已提供必要的输入材料
- [ ] 任务目标已明确
- [ ] 如有歧义，已向用户确认

## 工作流程

请严格按照以下步骤执行：

1. **理解输入**：[如何分析用户的输入]
2. **判断目标**：[如何确定任务目标和约束条件]
3. **核心处理**：[具体的处理步骤]
4. **质量检查**：[检查输出是否符合标准]
5. **格式化输出**：[按指定格式输出最终结果]

## 输出格式

请按照以下格式输出：

```text
一、[结果部分]
二、[说明部分]
三、[建议部分]

质量标准

输出必须满足以下条件：

准确：不编造信息，基于事实
清晰：结构分明，逻辑通顺
可执行：给出的建议可以直接操作
完整：不遗漏关键步骤和信息
一致：风格和格式保持统一

注意事项

不要改变用户原意
不要输出与任务无关的内容
如果信息不足，先基于现有信息给出合理版本，并在末尾说明做了哪些假设
如果遇到不确定的内容，明确标注并说明原因

python 复制代码

---

## 十、常见问题与最佳实践

### 10.1 常见问题

**Q1：Skill 和直接写一个很长的 Prompt 有什么区别？**

Prompt 是一次性使用的，每次对话结束后就"忘记"了。Skill 是持久化的配置文件，每次触发都自动加载，且支持引用模板、示例等辅助文件。更重要的是，Skill 的 description 机制让 AI 能够**自动判断何时使用**，不需要你每次手动指定。

**Q2：一个项目可以有多少个 Skill？**

理论上没有限制。但建议根据实际需求来组织，保持每个 Skill 的职责单一。如果你有 50 个 Skill，但日常只用到 5 个，那说明很多 Skill 可以合并或淘汰。

**Q3：Skill 可以调用另一个 Skill 吗？**

目前大多数 AI 工具不支持 Skill 之间的直接调用。但你可以在一个 Skill 的工作流程中写明"如果遇到 XX 情况，请参考 XX Skill 的方法"，AI 会理解这个意图。

**Q4：Skill 写得越长越好吗？**

不是。Skill 的核心价值在于**精准和清晰**，而不是篇幅。一个好的 Skill 应该在 100-500 行之间，能用 3 步完成的事情不要写成 10 步。

**Q5：如何测试一个 Skill 是否生效？**

编写完 Skill 后，用几个不同的测试用例来验证：
1. 触发测试：用符合 description 的任务描述，看 AI 是否自动激活该 Skill
2. 执行测试：检查 AI 是否按工作流程执行
3. 输出测试：检查输出是否符合指定格式和质量标准
4. 边界测试：用不符合 description 的任务描述，看 AI 是否正确地不激活该 Skill

### 10.2 最佳实践

**1. 从小处开始**

不要一开始就设计一个"万能 Skill"。先从一个简单的、高频的任务开始，比如"Git Commit 信息格式化"。验证可行后，再逐步扩展。

**2. 保持单一职责**

每个 Skill 只解决一类问题。"代码审查"和"代码生成"应该是两个独立的 Skill，而不是挤在一个 Skill 里。

**3. description 要下功夫**

description 是 Skill 的"门面"，直接决定了 AI 能否正确触发它。花 10 分钟打磨 description，比花 1 小时优化正文更有价值。

**4. 用示例说话**

在 Skill 中加入正确示例和错误示例，比用文字描述规则更有效。AI 对示例的理解能力非常强。

**5. 持续迭代**

Skill 不是写完就一劳永逸的。随着使用，你会发现 AI 在某些场景下做得不够好，这时候回来修改 Skill，让它越来越精准。这就是 Skill 的"版本进化"。

**6. 团队共享与标准化**

将团队中优秀的 Skill 纳入版本控制（Git），建立团队的 Skill 仓库。这样新人入职时，直接安装团队的 Skill 集合，就能获得一致的 AI 协作体验。

**7. 给 AI 留有余地**

不要把 Skill 写得太死板。在关键步骤上要严格，在非关键步骤上要给 AI 发挥的空间。比如：

```markdown
# ✅ 好的写法
标题控制在 15-25 字之间，风格参考当前公众号的调性。

# ❌ 太死板的写法
标题必须恰好 18 个字，必须包含一个数字，必须以问句结尾。

十一、总结

核心要点回顾

1. Skills 是什么？

Skill 就是给 AI 写的"岗位操作手册"（SOP），不是临时口令，不是个人偏好，也不是外部工具。它是一份结构化的、可复用的、场景驱动的任务执行方案。

2. 为什么需要 Skills？

为了治 AI 的"健忘症"，让输出每次都标准、不乱编、不遗漏。Skills 解决了稳定性、效率、专业性和可复用性四个核心问题。

3. Skills 和 Prompt、Rule、MCP 有什么区别？

Prompt 是临时交代（这次做什么）
Rule 是长期偏好（一直怎么做）
MCP 是外部能力（能做什么）
Skills 是专业流程（按什么流程做）

4. 怎么写一个 Skill？

建一个文件夹，写好 SKILL.md，重点把 name （英文标识）和 description（何时触发）写清楚，再列出完整的工作流程、输出格式和质量标准。

5. 怎么让 Skill 更好用？

加入正确示例和错误示例
用辅助文件（模板、参考、脚本）扩展能力
持续迭代，根据实际效果优化
团队共享，建立标准化的 Skill 库

核心逻辑

不用再反复教 AI 了。直接甩给它一份 Skill，它自己照着做。

你花 30 分钟写好一个 Skill，以后每次使用都能节省 5-10 分钟。做 10 次就是 50-100 分钟。而且输出质量更稳定、更专业、更一致。

这就是 Skills 的价值：一次投入，持续回报。

本文档基于 AI 编程助手的 Skills 机制编写，适用于支持 SKILL.md 格式的 AI 工具（如 Cursor、Windsurf、OpenClaw 等）。具体语法和功能可能因工具版本不同而有所差异，请参考对应工具的官方文档。