Skills 深度解析：给 AI 编程助手装上「专业大脑」

什么是 Skills？

假设你招了一个 IQ 极高的新人，他学什么都快，但他不了解你的项目——不知道你的代码规范、不熟悉你的技术栈、更不清楚你团队的 Code Review 标准。每次分配任务，你都得从头说一遍。

Skills 就是你给这个"AI 新人"准备的工作手册。

graph LR
    subgraph 没有Skills
        U1["开发者"] -- "每次重复说明规范" --> A1["AI 助手"]
        A1 -- "输出不稳定" --> R1["代码质量参差不齐"]
    end

graph LR
    subgraph 有了Skills
        U2["开发者"] -- "正常对话" --> A2["AI 助手"]
        S["Skills 工作手册"] -- "自动注入专业知识" --> A2
        A2 -- "标准化输出" --> R2["提供一致的检查流程"]
    end

Skills 是 AI 编程助手的模块化能力扩展包——通过结构化的 Markdown 文件，将团队的编码规范、最佳实践、工作流程「随项目维护、按需使用」地注入 AI 的工作上下文。它不改变 AI 的"智商"，但极大提升了它的"专业度"。

为什么需要 Skills？

Skills 核心机制：三层渐进式加载

以 Claude Code 的 SKILL.md 为代表，Anthropic 设计了一个优雅的"按需加载"架构。核心设计哲学是 "Token 就是金钱"——在保持功能丰富的同时，最大限度地节省上下文窗口资源。

graph TB
    subgraph 三层加载
        L1["Level 1：YAML Frontmatter"]
        L2["Level 2：SKILL.md 正文"]
        L3["Level 3：关联文件"]
        L1 -- "匹配用户请求？" --> L2
        L2 -- "需要执行脚本？" --> L3
    end
    style L1 fill:#4ade80,color:#000
    style L2 fill:#60a5fa,color:#000
    style L3 fill:#f472b6,color:#000

Level 1：YAML Frontmatter（始终驻留）

AI 启动时读取所有 Skills 的 name 和 description，仅消耗极少 Token。这层的作用是快速判断"这个 Skill 跟当前任务有关吗"。

---
name: code-review-assistant
description: 代码审查助手，从安全性、性能、类型安全、测试覆盖等维度审查代码
---

Level 2：SKILL.md 正文（按需加载）

当用户的请求与某个 Skill 的 description 匹配时，AI 才加载该 Skill 的完整指令。例如用户说"帮我审查这段代码"，就会触发 code-review-assistant 的完整规则加载。

Level 3：关联文件（深度按需）

Skills 可以包含脚本、参考文档、模板等附属文件，只有在 SKILL.md 中被引用且确实需要时才会被读取。

skills/
└── code-review/
    ├── SKILL.md           # 必需：核心指令
    ├── scripts/           # 可选：可执行脚本
    │   └── lint-check.sh
    ├── references/        # 可选：参考文档
    │   └── security-checklist.md
    └── assets/            # 可选：模板和资源
        └── report-template.md

Skills 的按需加载有助于控制上下文开销；规则也可能按路径或条件加载，不能一概视为全量注入。技能提供指导，确定性的质量要求仍应通过测试和检查器验证。

SKILL.md 编写实战

标准结构

---
name: skill-name
description: 一句话描述这个 Skill 的用途和触发场景
---

# Skill 标题

何时使用此 Skill 的说明。

## 核心规则

### 1. 规则一
- 具体的检查项或操作步骤

### 2. 规则二
- ...

## 输出格式

定义 AI 的标准化输出模板。

## 示例

提供至少一个高质量的输入→输出示例。

实战案例一：代码审查助手

这是一个"检查清单型"Skill，将团队的 Code Review 标准系统化：

---
name: code-review-assistant
description: 代码审查助手，从安全性、性能、类型安全、测试覆盖等维度审查代码
---

# Code Review 助手

当用户要求审查代码或 review PR 时使用此技能。

## 审查维度

按以下顺序检查，输出结构化的审查意见：

### 1. 🔴 安全性（Critical）
- SQL 注入：是否使用参数化查询
- XSS：用户输入是否经过转义
- 认证/授权：API 端点是否有适当的权限检查
- 敏感信息：密钥、密码是否硬编码在代码中

### 2. 🟠 性能（High）
- N+1 查询：是否使用 joinedload/selectinload 避免
- 缓存：频繁查询是否利用 Redis 缓存
- 异步：IO 密集操作是否使用 async/await

### 3. 🟡 类型安全（Medium）
- 是否有 `any` 类型可以被更具体的类型替代
- 函数是否有类型注解

### 4. 🟢 代码质量（Low）
- 命名：变量和函数名是否清晰表达意图
- 函数长度：单个函数是否超过 50 行
- DRY：是否有可以复用的重复代码

## 输出格式

## Code Review Summary

### 🔴 Critical
- [文件:行号] 描述问题和修复建议

### 🟠 Suggestions
- [文件:行号] 描述优化建议

### 🟢 Good Practices
- 值得肯定的做法

### 📊 Overall
- 评分: X/10
- 建议: 通过 / 需修改后通过 / 需重新设计

这个 Skill 的设计精妙之处在于：优先级排序（安全 > 性能 > 类型 > 质量 > 测试）确保 AI 先关注最致命的问题；强制输出格式让每次 Code Review 的结果都可比较和追踪。

实战案例二：Git Commit 格式化器

这是一个"格式规范型"Skill，强制执行 Conventional Commits 规范：

---
name: git-commit-formatter
description: 按照 Conventional Commits 规范格式化 Git 提交信息，支持中英文
---

# Git Commit Formatter

当用户要求提交代码或生成 commit message 时，使用此技能。

## 提交格式

<type>(<scope>): <subject>

<body>

<footer>

## Type 类型

| Type | 说明 | 示例 |
|------|------|------|
| feat | 新功能 | feat(auth): 添加 JWT 刷新令牌 |
| fix | 修复 Bug | fix(api): 修复分页参数解析错误 |
| docs | 文档更新 | docs(readme): 更新部署指南 |
| refactor | 重构 | refactor(ai-service): 拆分模型选择逻辑 |
| perf | 性能优化 | perf(cache): 优化 Redis 缓存命中率 |
| test | 测试相关 | test(api): 添加用户注册集成测试 |
| chore | 构建/工具变更 | chore(deps): 升级 FastAPI 到 0.115 |

## 规则

1. subject 不超过 50 字符，使用祈使句
2. body 说明**为什么**做这个变更，而不是**做了什么**
3. 一次提交只做一件事

实战案例三：Docker 部署助手

这是一个"知识沉淀型"Skill，将项目容器化架构知识固化：

---
name: docker-deploy-assistant
description: Docker 部署助手，指导 Dockerfile 编写、docker-compose 编排和部署流程
---

# Docker 部署助手

当涉及 Docker 容器化、部署、环境编排相关任务时使用此技能。

## 项目容器架构

docker-compose.yml
├── backend    (FastAPI, Python 3.12, port 8001)
├── frontend   (Nginx + React build, port 5174)
├── db         (PostgreSQL, port 5432)
├── redis      (Redis, port 6379)
└── monitoring (Prometheus + Grafana, optional)

## 关键规则

1. **多阶段构建** — 减小镜像体积，分离构建和运行环境
2. **非 root 用户** — 生产镜像应使用非 root 用户运行
3. **健康检查** — 添加 HEALTHCHECK 指令监控容器状态
4. **环境变量** — 敏感信息通过 .env 或 Docker secrets 注入
5. **网络隔离** — 数据库和 Redis 只暴露给内部网络

这个 Skill 的价值在于：新人加入团队时，AI 自动获得项目的完整部署知识，不需要任何人手动传授。

六大平台：Skills、规则与仓库指令要分开比较

核对日期为 2026-10-20。SKILL.md 是可按任务加载的能力包；Rules 和仓库指令负责持久背景或路径规则。不能把某个平台的规则格式当成它唯一的扩展能力，再据此断言“不支持脚本”或“只能全量加载”。

Cursor、Copilot 与 Gemini CLI 的技能都可以携带脚本和参考资源；实际执行仍取决于可用工具、依赖和权限。通用格式不意味着所有 frontmatter 扩展字段、触发方式或审批流程都能原样迁移。

参见 Claude Code Skills、Cursor Skills、Copilot Skills、Codex Skills、Gemini CLI Skills。Windsurf 的当前技能文档本次未能可靠读取，因此不将其脚本与加载能力标为不支持。

AGENTS.md 不等于自定义 Agent 角色

AGENTS.md 通常承载项目结构、构建步骤与目录约定。GitHub Copilot 的自定义 Agent profile 使用 .github/agents/*.agent.md，不能把角色定义归到 AGENTS.md。Claude Code 的主要项目指令入口是 CLAUDE.md，可显式导入其他文件；不要假设所有客户端都会自动读取同一套文件。

跨平台迁移怎么验证？

先共享标准 SKILL.md 正文、脚本和参考文件，再逐个平台确认发现目录、支持字段、资源路径、命令环境及权限行为。把始终需要的项目约定保留在各客户端认可的仓库指令入口，不要期望一次技能触发就永久约束所有未来会话。

Skills 在 AI 定制体系中的位置

理解 Skills 的定位，需要看到 AI 编程助手的完整定制层级。在进阶的 AI 编程驾驭实践 中，各层级职责清晰是避免上下文污染和提示词膨胀的关键基石：

graph TB
    subgraph 定制层级
        L1["System Prompt — 平台内置，开发者不可修改"]
        L2["Custom Instructions — 用户全局偏好（如：总是用中文回复）"]
        L3["Project Rules — 项目级约定（如：用 4 空格缩进）"]
        L4["Skills — 任务领域级专业能力（如：Code Review 规范）"]
        L5["MCP Tools — 与外部系统交互（如：调用数据库、GitHub API）"]
        L6["对话上下文 — 当前会话内容"]
    end
    L1 --> L2 --> L3 --> L4 --> L5 --> L6

Skills vs MCP：互补而非竞争

很多人会混淆 Skills 和 MCP（Model Context Protocol），两者是完全不同层次的概念：

一句话总结：Skills 是 AI 的"大脑里的知识"，MCP 是 AI 的"手里的工具"。一个完整的 AI 编程工作流需要两者的配合——Skills 告诉 AI "做代码审查时要检查 N+1 查询"，MCP 让 AI 能够"真正连接数据库去验证查询性能"。

Skills vs 提示工程

Skills 也与提示工程（Prompt Engineering）有本质不同：

编写 Skills 的最佳实践

六大核心原则

1. 单一职责

一个 Skill 只解决一个领域的问题。不要把 Code Review、Git Commit、部署流程塞进同一个文件。

2. 清晰的触发条件

在 SKILL.md 开头明确说明"什么时候用这个 Skill"：

当用户要求审查代码、review PR、或检查代码质量时使用此技能。

3. 具体而非抽象

❌ "写出高质量的代码"

✅ "函数不超过 50 行，使用 4 空格缩进，所有公共方法必须有 docstring"

4. 提供输出模板

定义 AI 的结构化输出格式，确保每次输出可预测、可比较。

5. 至少一个完整示例

人类看文档需要示例，AI 也一样。一个高质量的输入→输出示例胜过十段规则描述。

6. 版本控制与迭代

Skills 应纳入 Git 仓库管理。根据实际使用反馈持续优化——如果 AI 经常忽略某条规则，说明规则写得不够清晰。

四种 Skill 设计模式

graph LR
    A["检查清单型"] --> A1["Code Review\n安全审计\nPR 审查"]
    B["知识沉淀型"] --> B1["项目架构\n部署流程\n技术栈文档"]
    C["格式规范型"] --> C1["Commit Message\n文档模板\nAPI 规范"]
    D["工作流型"] --> D1["CI/CD 流程\n发布流程\n迁移流程"]

反模式（应避免）

• ❌ 巨无霸 Skill：一个文件覆盖所有场景，导致 Token 浪费且指令冲突
• ❌ 模糊描述：description 写成"帮助编程"，AI 无法判断何时触发
• ❌ 缺少示例：纯规则无示例，AI 容易理解偏差
• ❌ 没有输出格式：AI 每次输出格式不同，无法标准化流程
• ❌ 职责重叠：多个 Skills 覆盖相同领域，导致指令冲突

企业级 Skills 架构

当团队规模扩大，Skills 的管理需要上升到架构层面：

1. 分层组织策略

项目根目录/
├── AGENTS.md              # 跨平台通用的项目上下文
├── CLAUDE.md              # Claude Code 全局配置
├── .github/
│   └── copilot-instructions.md  # GitHub Copilot 配置
├── .cursor/
│   └── rules/             # Cursor 规则目录
│       ├── python.mdc
│       └── typescript.mdc
└── .claude/
    └── skills/            # Claude Skills 目录
        ├── code-review/
        │   └── SKILL.md
        ├── git-commit/
        │   └── SKILL.md
        └── deploy/
            ├── SKILL.md
            └── scripts/
                └── deploy.sh

2. 多平台兼容策略

如果团队成员使用不同的 AI 工具，可以采用 AGENTS.md 为公共层 + 各平台专有配置 的策略：

• AGENTS.md 定义所有工具通用的项目上下文和编码规范（OpenAI Codex、GitHub Copilot、Gemini 等均支持）
• 各平台特有的配置文件定义工具专属的高级功能
• 通过 Git 版本控制确保全团队同步

3. 团队 Skills 治理

• 定期审计：每季度审查 Skills 的有效性，删除过时规则
• 使用 metrics：跟踪 Skills 的触发频次和输出质量
• 分级管理：核心规则（安全相关）由 Tech Lead 审批，一般规则由团队成员自主维护

发展趋势与展望

2025-2026 关键演进

timeline
    title Skills 系统演进时间线
    2023.08 / 11 : ChatGPT Custom Instructions 与 GPTs 推出 : OpenAI 奠定早期提示词定制体系
    2024 : .cursorrules 单文件 : 早期编辑器级自定义指令实践
    2024.10 : copilot-instructions.md : GitHub Copilot 支持仓库级自定义指令
    2025.02 : CLAUDE.md 规范 : Claude Code 推出项目级内存与架构规范
    2025-05-16 : AGENTS.md 规范发布 : 推动跨平台开放代理标准
    2025-10-16 : SKILL.md 发布 : Anthropic 推出模块化 Agent Skills 系统
    2026 Q1 : Agent Skills 2.0 : 多代理协同、动态注入与跨平台生态兼容

未来形态

1. 标准化融合：AGENTS.md 正在成为跨平台事实标准，未来可能出现类似 MCP 的统一 Skills 协议
2. 从指令到执行：Skills 从纯文本指令进化为可包含脚本、MCP 工具引用和自动化流程的完整执行包
3. AI 自生成 Skills：AI 可以从开发者的工作模式中自动提炼和生成 Skills，形成"越用越聪明"的正向循环
4. Skills 市场：类似 VS Code 扩展市场和 OpenAI GPT Store，社区驱动的 Skills 共享平台正在兴起
5. 与 MCP 深度整合：Skills 作为 MCP 工具的"使用说明书"，两者协同构建完整的 AI 开发生态

graph LR
    subgraph 未来的AI开发者工作台
        Brain["AI 模型（大脑）"]
        MCP["MCP 工具（双手）"]
        Skills["Skills（专业知识）"]
        Context["对话上下文（当前任务）"]
        Brain --- Skills
        Brain --- MCP
        Brain --- Context
        Skills --- S1["团队共享"]
        Skills --- S2["个人偏好"]
        Skills --- S3["社区最佳实践"]
    end

常见问题 (FAQ)

Q1: Skills 与传统 System Prompt 的本质区别是什么？

System Prompt 是由平台和模型厂商固化的底层基底指令，通常包含全局安全伦理红线且不可被开发者直接抹除或替换。Skills 则是开发者根据特定业务工程领域自定义的高阶外挂知识规范包，遵循按需激活与模块化装配原则，可以根据开发场景（如专项测试、架构评审、SQL 审查）动态注入大模型上下文，避免提示词膨胀。

Q2: 配置很多 Skills 会不会占用上下文？

会。渐进式加载通常先提供技能名称与描述，相关任务再读取正文与资源，但目录元数据本身也有开销。节省比例取决于技能数量、长度与触发范围；减少重复和无关技能，比承诺固定 90% 节省更可靠。

Q3: 工程架构中如何决策该采用 Skills 还是 MCP？

两者的角色完全互补：Skills 负责教大模型如何正确思考与执行流程（即最佳实践、规范清单、架构约束和代码模板）；而 MCP（Model Context Protocol） 负责为大模型提供与外部世界交互的实际工具（如操作数据库客户端、调用外部 API、读取沙箱环境）。Skills 指导大模型何时以及如何以合规参数调用对应的 MCP 工具。

Q4: 现代 Skills 体系支持跨平台和跨编辑器迁移吗？

支持。以 AGENTS.md、CLAUDE.md 及通用 SKILL.md 为代表的文件规范采用纯文本开放标准编写，已被 GitHub Copilot、Cursor、Claude Code 以及各大开源 Agent 运行时广泛支持。开发者只需将 Skills 文件纳入项目的 Git 版本控制，团队成员即可在各自偏好的 IDE 工具中获得完全一致的 AI 辅助效果。