Claude Skills 实战万字指南：原理拆解 + 手写一个生产级 Skill + 私藏技能清单

原创于 2026-08-20 11:28:37 发布 · 233 阅读

本内容遵循CC 4.0 BY-SA版权协议

2026 年，AI 编程的分水岭已经不是"会不会写 Prompt"，而是"会不会沉淀 Skill"。这篇文章把我这半年翻了几百个 Skill、亲手写了几十个之后总结的方法论一次性讲透：Skills 的底层原理、SKILL.md 的标准写法、一个可以直接抄走的生产级实战案例，以及我常逛的技能清单。

一、为什么 Prompt 救不了你的 AI 编程

先讲一个你肯定遇到过的场景：

你让 Claude Code（或者 Cursor、Codex）帮你提交代码，它写的 commit message 天马行空；你在团队里定了规范——type 前缀、中文描述、不超过 50 字。于是你每次都在对话里贴一遍规范。

第二天，你让它写 SQL，又得贴一遍"我们公司的数仓规范"。第三天，写周报，再贴一遍模板……

问题不在于模型不够聪明，而在于你的经验没有被"资产化"。

每次对话都是一次性消耗品。而 Agent Skills（以下简称 Skill）解决的就是这件事：把你的经验、流程、规范打包成一个可被 AI 自动发现和加载的"技能包"，一次编写，永久生效。

我用了半年 Skills 之后，最直观的体感是：AI 从一个"每次都要重新培训的新人"，变成了一个"入职半年的老员工"。

二、Skills 到底是什么：三个关键词讲透本质

2.1 一个文件夹，不是一个 API

很多人以为 Skill 是什么高深的服务。其实一个 Skill 就是一个文件夹：

my-skill/
├── SKILL.md          # 必需：技能的说明书（触发条件 + 执行指令）
├── scripts/          # 可选：可执行脚本（Python/Bash/JS）
├── references/       # 可选：参考文档（按需加载的详细资料）
└── assets/           # 可选：模板、示例等静态资源

核心只有 SKILL.md 一个文件。它没有服务端、没有网络调用、没有运行时——它就是一份写给 AI 看的、结构化的操作手册。

2.2 渐进式披露：Skills 最精妙的设计

Skills 能在工程上成立，靠的是 Progressive Disclosure（渐进式披露） 的三级加载机制：

层级	加载内容	加载时机	Token 成本
L1 元数据	name + description（约 100 tokens）	启动时全部加载	极低
L2 指令	SKILL.md 正文（建议 500 行内）	技能被触发时	中
L3 资源	references/scripts 里的文件	执行中按需读取	按需

这意味着你可以给 AI 装 100 个技能，但日常上下文里只多了 100 段一两句话的"目录"。只有当用户的请求命中某个技能的 description 时，AI 才会把完整的 SKILL.md 读进来；遇到复杂情况，再按需翻 references 里的详细文档。

这是它和"把所有规范塞进系统提示词"的本质区别：前者是图书馆的索引，后者是把整个图书馆背下来。

2.3 Skill 和 MCP 到底什么关系

这是被问得最多的问题，一句话区分：

MCP 解决的是"连接"：让 AI 能访问外部数据和工具（数据库、API、文件系统）。
Skill 解决的是"经验"：告诉 AI 拿到这些能力之后，按什么流程、什么规范、什么最佳实践去做事。

MCP 给 AI 一双手，Skill 给 AI 一本岗位 SOP。两者是互补关系，一个成熟的 Skill 里经常会写"先调用某某 MCP 查数据，再按以下模板输出"。

三、解剖一个真实的 SKILL.md

SKILL.md 由两部分组成：YAML frontmatter + Markdown 正文。先看一个精简但完整的真实例子（一个代码提交规范技能）：

---
name: git-commit
description: 按照团队 Conventional Commits 规范生成中文 commit message 并提交。当用户要求"提交代码"、"写 commit"、"帮我 commit"时使用。
---

# Git Commit 规范技能

## 提交流程

1. 运行 `git status` 和 `git diff --staged` 确认改动范围
2. 按以下格式生成 commit message：

   <type>(<scope>): <中文描述，不超过50字>

   - type 可选：feat / fix / docs / refactor / perf / test / chore
   - scope 为模块名，可省略
   - 描述用动词开头，如"新增""修复""移除"

3. 涉及多个不相关改动时，提示用户拆分提交
4. 不要提交 .env、密钥文件和 node_modules

## 禁止事项

- 禁止使用 git push --force
- 禁止跳过 hooks（--no-verify）

几个关键点：

1. description 是触发器，不是简介。 它是 AI 判断"要不要用这个技能"的唯一依据。对比一下：

❌ 差的写法：description: 一个 git 提交工具——AI 根本不知道什么时候该用它，触发率趋近于零。
✅ 好的写法：说清楚做什么 + 什么时候触发，最好带上用户可能的原话（“提交代码”“帮我 commit”）。

2. 正文是写给 AI 的指令，不是写给人看的文档。 用祈使句、编号步骤、明确的判断条件，少写背景和客套话。AI 不需要被说服，只需要被指令。

3. 500 行红线。 SKILL.md 正文建议控制在 500 行以内。写不下说明该拆了：详细参考资料放 references/，SKILL.md 里写一句"需要 XX 详细信息时阅读 references/xx.md"，AI 会自己去翻。

4. 确定性操作交给脚本。 如果某个步骤是机械操作（格式校验、模板渲染），写成 scripts/ 里的脚本，让 AI 执行脚本而不是"现场发挥"。脚本是确定性的，模型是概率性的——能用前者就别用后者。

四、实战：从零写一个生产级 Skill

光说不练假把式。我们来写一个真实可用的技能：“SQL 取数助手”——团队里最高频的场景之一。

4.1 定义需求

痛点：数据表几百张，字段命名不规范，新人写 SQL 要么查错表，要么写出全表扫描。我们希望 AI 写 SQL 前强制遵守团队规范。

4.2 目录结构

sql-helper/
├── SKILL.md
├── references/
│   └── table-dictionary.md    # 核心表结构字典
└── scripts/
    └── validate_sql.py        # SQL 静态检查脚本

4.3 SKILL.md 全文

---
name: sql-helper
description: 编写和优化团队数仓 SQL。当用户要求写 SQL、查数据、优化慢查询、统计指标时使用。
---

# SQL 取数助手

## 执行流程

1. 明确用户的统计口径：时间范围、维度、指标定义，口径不明确必须先反问
2. 阅读 references/table-dictionary.md 确认表名和字段，禁止臆造表名
3. 按以下硬约束编写 SQL：
   - 必须带分区过滤条件（dt 字段），禁止全表扫描
   - SELECT 明确列出字段，禁止 SELECT *
   - JOIN 超过 3 张表时，先用 CTE 拆解
4. 写完后运行 `python3 scripts/validate_sql.py <sql文件>` 做静态检查
5. 检查不通过必须修复，不要绕过

## 输出格式

最终交付包含：SQL 正文、口径说明（一句话）、预估扫描量级。

4.4 静态检查脚本（节选）

# scripts/validate_sql.py
import re, sys

sql = open(sys.argv[1]).read().lower()
errors = []

if "select *" in sql:
    errors.append("禁止使用 SELECT *")
if not re.search(r"\bdt\s*[=><]", sql):
    errors.append("缺少 dt 分区过滤条件")
if "join" in sql and "on" not in sql:
    errors.append("JOIN 缺少 ON 条件")

if errors:
    print("检查未通过：")
    for e in errors:
        print(" -", e)
    sys.exit(1)
print("检查通过")

4.5 效果

装好之后，一句"帮我统计一下上周各渠道的注册转化率"，AI 会自动：反问口径 → 翻表字典 → 写出带分区过滤的 SQL → 自己跑一遍静态检查 → 附上口径说明。整个流程不需要你提醒任何一个字。

这就是 Skill 的杠杆：你写一遍，团队每个人、每一次对话都在复用。

五、八条军规：我踩过的坑都在这了

description 写"什么时候用"，不写"是什么"。它决定触发率，是最重要的一行。
一个 Skill 只干一件事。"代码审查+提交+部署"三合一的技能，触发和输出都会失控，拆成三个。
正文 500 行红线，写不下就拆 references，别让索引变成正文。
确定性逻辑脚本化。能让 AI 跑脚本就别让它背规则，概率模型干不过确定性代码。
给验证方式，不给期望结果。写"运行 X 命令确认成功"比"确保结果正确"有效十倍。
别在 Skill 里放秘密。密钥、内网地址、个人 token 一律走环境变量。
命名动词化、语义化。sql-helper 比 tool1 好，generate-report 比 report 好——名字本身也参与触发。
上线后持续调触发率。找 10 个真实用户问法测一遍，触发不了的改 description，误触发的收窄描述。Skill 是运营出来的，不是写完就完的。

六、去哪找高质量的现成 Skill

自己写是进阶，先用好别人写的才是性价比。分享几个我常逛的渠道：

1. 官方仓库 anthropics/skills
Anthropic 官方维护的技能集，文档处理（docx/pdf/pptx/xlsx）那几个质量极高，也是学习 SKILL.md 写法的最佳范本。

2. xia345（虾345）—— 中文圈最全的 Agent 技能导航
这是我自己日常在用的一个中文聚合站：xia345.com。它把散落在 GitHub 各个角落的 Skills、MCP Server、Agent 客户端按场景做了分类导航，有两个榜单我特别推荐：

Skills 热门榜 / 上新榜——每天能刷到社区新出的技能，适合淘货；
Agent 客户端和 LLM 选型页——对比各家客户端和模型的能力边界。

比较戳我的一个细节是，这个站给搜索引擎和 AI Agent 准备了机器可读入口（xia345.com/llms.txt），你甚至可以把这些地址直接丢给你的 AI，让它自己去导航里找技能——用 Agent 的方式发现 Agent 技能，很闭环。

3. 从别人的 dotfiles 里淘
GitHub 搜 SKILL.md path:.claude/skills，能看到大量开发者公开的个人技能库，很多小众但极实用的工作流（自动发日报、会议纪要生成、PR 描述生成）都是从这里淘的。

七、写在最后

Prompt 是对话，Skill 是资产。

2023 年我们学写提示词，2024 年我们学搭 Agent，2025 年 MCP 统一了"连接"，而 2026 年最重要的动作，是把你脑子里那些"我知道该怎么做但 AI 不知道"的经验，一个个沉淀成 Skill。

每个资深工程师和行业专家的脑子里，都住着几十个还没被写出来的 Skill。这件事的复利，远超你的想象。

你写过最实用的 Skill 是什么？评论区聊聊，我去偷师。觉得有用的话点个赞和收藏，后面我会再写一篇《Skill 触发率调优实战》——也就是怎么让 AI 在该用技能的时候 100% 想起来用。
把散落的经验沉淀为可复用的技能资产

标签

#人工智能 #AI编程 #AIGC