Skills 是什么
简单理解：把经验打包，下次让 AI 接着用。
你让 Claude Code 写个页面，发现效果不太满意，就一点点补要求：“参考项目里现有的样式，别什么内容都往卡片里塞”，“按钮用品牌色” 来回改了几次，终于顺眼了。
在这个对话内它终于懂你的要求了。可过几天换个对话，Claude完全不记得上次的约定，你需要重新解释，甚至去翻阅历史对话。
Skills 就是解决这个问题的。它本质上是一份结构化的经验文档，告诉 Claude “遇到这类任务时，按这个方法来做”。
拿开发里熟悉的东西对照一下：
| 开发时你会 | 用 Skills 也是类似的思路 |
|---|---|
| 装个现成的 npm 包 | 找个别人写好的 Skill，复用里面的经验 |
| 把常用组件封装成组件库 | 把自己常用的做法整理成 Skill |
| 用 ESLint 约束代码写法 | 在 Skill 里约定 AI 做事的要求 |
| 看 README 了解项目 | AI 看 SKILL.md 了解技能干什么、怎么用 |
挑 Skills 也跟安装依赖一样，够用就好。
看见一个就装一个，最后攒了一堆用不上的，管理起来麻烦。而且每个安装的 Skill 都会占用 Claude 的注意力资源，反而会干扰它的判断。
Skills VS 提示词
既然提示词能搞定，为什么还要用 Skills？
问题不在于提示词不好用，而是每次都得靠你记着、找着、补全要求：
| 遇到的问题 | 用起来是什么感觉 |
|---|---|
| 总在重复 | 同样的要求，做一次就得说一次 |
| 接不上之前的约定 | 换个会话，又得从头交代 |
| 经验散落 | 调了半天的提示词，最后埋在聊天记录里 |
| 不方便复用 | 同事想照着用，还得找出完整要求发给他 |
| 效果不稳定 | 少交代一句，结果就可能差不少 |
Skills 就是把这套要求保存下来，变成以后能反复使用的经验。
它把你的经验写成一份持久化的文档，Claude 自动加载、反复遵守、跨会话生效。
打个比方：每次写提示词，就像每次点咖啡都要说“少冰、不加糖、换燕麦奶”；Skills 则是把这个搭配存成“我的常喝”，下次直接选就行。
跟 CLAUDE.md 的区别也好理解：CLAUDE.md 写的是“在这个项目里干活，都得遵守什么”，Skills 写的是“碰到某类任务，具体该怎么做”。
比如“统一用 pnpm 安装依赖”放在 CLAUDE.md，“做页面时怎么选配色、安排布局”放在前端设计的 Skill 里。
Skills 和 Commands
你可能见过两种写法：有的资料让你在 .claude/commands/ 里放一个 Markdown 文件，有的让你创建 .claude/skills/技能名/SKILL.md。
早期 Claude Code 里确实是两种机制，现在官方已经把自定义命令(commands) 合并进了 Skills，
并且 Skills 在此基础上多了三项能力：用目录存放配套文件、通过 frontmatter 设置由谁触发（手动输入 /技能名，还是让 Claude 自行判断）、任务相关时会主动加载。
| 格式 | 怎么理解 | 怎么用 | 举例 |
|---|---|---|---|
| Commands（旧格式） | 像 Shell alias，固定的提示词/流程 | 输入 /命令名 | /commit、/review |
| Skills（新格式） | 专业经验包，技术方案文档 + 可执行脚本 | 输入 /技能名，或自然语言按需调用 | frontend-design、mcp-builder |
旧 Commands 像一张写着操作步骤的便签，Skills 则像一个工具包，里面既有说明书，也能装上干活要用的工具。
SKills 安装说明及常用命令
npx skills 安装 (推荐)
社区标准的安装 CLI 是 vercel-labs 的 npx skills（支持 Claude Code、Codex、Cursor、OpenCode 等 75+ 个 agent），Anthropic 官方仓库和大部分社区 Skills 都能用它装：
# 安装 Anthropic 官方仓库里的 Skills，执行后选择需要的技能
npx skills add anthropics/skills
# 安装社区 Skills
npx skills add obra/superpowers # 示例： 一个开发工作流 Skills 集合
# 仅查看仓库里有哪些技能
npx skills add anthropics/skills --list
# 只安装 pdf、docx，-g 表示所有项目都能用
npx skills add anthropics/skills --skill pdf --skill docx -g
# 只给 Claude Code 安装
npx skills add anthropics/skills --skill pdf -a claude-code
# 搜索、查看和更新 Skills
npx skills find typescript
npx skills list
npx skills update安装时跟着终端提示走：选技能 → 选工具 → 选项目级或全局 → 选 symlink 或 copy。多选时用空格勾选，只选自己需要的就行。默认装到当前项目，加 -g 则装到用户目录。
symlink是多个工具共用一份技能文件，方便统一更新；copy是每个工具各存一份，之后分别维护。一般选推荐的symlink。
Claude Code 官方市场
安装了 anthropics/skills 后本身就会注册 Claude Code 插件市场，
可以直接在 Claude Code 中 /plugin 这样使用：
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skillsdocument-skills 包含 PDF、Word、Excel、PowerPoint 相关技能，example-skills 是其他示例技能。
装完可以直接说：“用 PDF 技能提取这个文件里的表单字段。”
手动安装
手动安装就是把完整的技能文件夹放到对应目录，这个主要是适用于：
有些社区的 Skills 没有发布到 CLI，需要手动克隆：
git clone https://github.com/xxx/awesome-skill.git ~/.claude/skills/awesome-skill注意看仓库结构：有的仓库本身就是一个 Skill，有的包含几十个 Skill。要放进去的是技能目录，别把整个合集当成一个技能。
Skills 文件结构及编写要点
存放位置
Skills 跟 CLAUDE.md 一样有层级 ：
CLAUDE.md 相关可阅读 CLAUDE.md 使用与编写，从项目规范到规则排查
| 层级 | 路径 | 作用范围 |
|---|---|---|
| 企业级 | 管理设置目录下的 .claude/skills/ | 组织部署了这些配置的机器 |
| 个人级 | ~/.claude/skills/ | 本机所有项目 |
| 项目级 | ./.claude/skills/ | 当前仓库，可提交到 Git 分享给团队 |
| 插件 | <plugin>/skills/ | 插件启用后使用，调用名为 /插件名:技能名 |
一个 Skill 的结构大致如下，一个 Skill 就是一个目录， SKILL.md 是核心，其他目录按需要添加：
frontend-design/
SKILL.md # 技能说明和操作步骤
scripts/ # 可执行脚本
references/ # 参考资料
assets/ # 模板、图片等资源文件结构
SKILL.md 的结构很简单，分两部分：头部元信息 + 正文指令：
---
name: my-skill # 技能名称，用 kebab-case（不写则用目录名）
description: 一句话描述 # 说明这个技能干什么、什么情况下触发
---
# 技能标题
## 触发场景
什么时候应该使用。
## 工作流程
具体的步骤说明。
## 输出规范
产出的格式和质量要求。就这么简单。不需要搞复杂的模板，重点是把经验和要求写清楚。
编写要点
一个好的 Skill，核心就是三件事：
- 触发场景写清楚 — 让 Claude 知道什么时候该用这个技能
- 关键规范写具体 — 不要写”保持代码简洁”，写”文件不超过800行”
- 示例比描述有效 — 给个好的示例比写十条规则都有用
要点一：触发场景要具体
# 差：检查代码
检查什么、什么时候检查？范围太大，Claude 不好判断。
# 好：提交代码前，检查本次 Git 改动中的异常处理和权限校验
场景和检查范围都有了，Claude 才知道什么时候该用。要点二：规范要具体可验证
# 差：写一份完善的 README
什么叫完善？Claude 只能自己猜。
# 好：README 必须包含安装步骤、启动命令、环境变量和使用示例
有没有写全，对照一下就知道。要点三：：给示例比给规则有效
# 差：提交信息要规范，准确描述改动
光说规范，Claude 不一定知道你想要哪种格式。
# 好：按下面的示例生成提交信息
改动：修复登录后跳转到空白页的问题
输出：fix(auth): 修复登录后跳转空白页的问题
有输入、有输出，比只讲规则更容易照着做。要点四：写清楚什么时候不用
# 差：用户需要处理 Excel 时使用这个 Skill
统计、清洗、画图都算处理 Excel，容易接到不擅长的任务。
# 好：用于汇总销售 Excel 中的月度营收，不用于预测销量或生成图表
能做什么、不能做什么都说清楚，避免误用。要点五：正文别写太满
# 差：把操作步骤、完整 API 文档、几十个示例全塞进 SKILL.md
内容堆在一起，真正要遵守的要求反而不好找。
# 好：SKILL.md 只保留核心步骤，详细资料单独存放
接口参数：需要调用接口时，读取 references/api.md
输出示例：生成结果前，读取 references/examples.md
写清楚去哪看、什么时候看，用到再读。创建自己的 Skill
我们每次都要给项目生成 README，你都要交代一遍：“先看 package.json”“写清安装和启动方式”“别编不存在的功能”。
这些要求基本不变, 这里正好整理成一个 README 生成 Skill。
手动创建 Skill
创建目录
mkdir -p ~/.claude/skills/readme-generator手动编写 SKILL.md
创建 SKILL.md，写入下面的内容：
---
name: readme-generator
description: 为包含 package.json 的项目生成中文 README。当用户要求“生成 README”“补充项目说明”时使用。
---
# 项目 README 生成器
## 工作流程
1. 读取 package.json，了解项目名称、依赖和 scripts
2. 查看源码目录、配置文件
3. 编写 README.md，包含以下章节：
- 项目简介（2-3句话）
- 功能特性列表
- 快速开始（安装+使用示例）
- 技术栈说明
- 开发指南
4. 格式为标准 Markdown，适配中文阅读习惯
## 输出规范
- 使用中文和标准 Markdown
- 项目介绍不超过 100 字
- 功能特性用列表展示，每条描述一个功能
- 安装命令与项目实际使用的包管理器一致
- 示例来自实际代码，不编造接口、配置和功能测试使用
在目标项目里打开 Claude Code：
/readme-generator也可以直接说“帮这个项目生成 README”，让 Claude 根据 description 判断是否使用。
调试要点:
- 该触发时没触发：检查 description 是否写清使用场景，是否允许 Claude 自动调用。
- 输出跟预期不一样：检查步骤有没有歧义、要求够不够具体，补一个正确示例。
- 内容太长、重点被淹没：删掉重复说明，把详细资料移到参考文件，正文写清路径和读取时机。
自动创建 skill-creator
官方的 skill-creator 就是 “帮你创建 Skill 的 Skill”。直接执行 /skill-creator，它会交互式地问你几个问题。
描述需求时，把这两件事说清楚：
- 要做什么、做到什么程度。 不只说“写 README”，而是“读取当前项目的配置和源码，生成包含项目介绍、安装启动、目录说明的中文 README”。
- 什么时候用、有什么要求。 比如“我说‘生成 README’时使用，也能通过
/readme-generator调用；介绍控制在 100 字以内，命令必须来自项目配置”。
它会根据需求整理 SKILL.md，生成的结果比手写模板更完整，它会自动补上目录结构说明、安装使用方式、生成规则等章节，这些你都没必要逐字教它。
已经聊了很多轮，才想把经验存下来？
也可以直接说：“用 skill-creator，把这次对话里确认过的步骤、要求和正确示例整理成一个 Skill。”它可以从当前对话中提取这些内容，不必让你从头复述。
社区的 claude-reflect 也提供了类似功能，通过 /reflect-skills 从会话中寻找可复用的工作模式。已经调顺的流程，可以继续整理成技能。
你不需要是提示词高手，把好的对话结果交给它提炼就行。
关键机制：渐进式加载（progressive disclosure）
渐进式加载
一个 Skill 里又是说明、又是参考资料，会不会还没开始干活，就把上下文塞满了？
渐进式加载（progressive disclosure）这是 Skills 和 CLAUDE.md 最大的区别，也是”长内容几乎零成本”的原因。加载分三段：
| 阶段 | 加载什么 | 成本 |
|---|---|---|
| 常驻 | frontmatter 的 name + description（约 30-50 token） | 每个会话都占，但极小 |
| 按需 | SKILL.md 正文 | Claude 判断与当前任务相关、或你 /技能名 调用时才加载 |
| 深入 | 附属文件（scripts/、references/） | 正文里指路，需要时 Claude 自己去读 |
对比一下写在 CLAUDE.md 里的内容每次对话都全量注入上下文；写进 Skill 的内容，平时只有一行 description 常驻，正文用到才加载。
官方文档:“a skill’s body loads only when it’s used, so long reference material costs almost nothing until you need it”。所以大块的参考资料（API 速查、设计规范、长示例）应该放 Skill 而不是 CLAUDE.md。
打个比方：先看书的目录，找到要读的章节，再翻具体内容，不用每次都从第一页读到最后一页。
动态上下文注入
还有个实用功能叫动态上下文注入：在技能正文里写入 !`命令`，Claude Code 会先执行命令，再把输出填进正文交给模型。
比如在一个”变更摘要”技能里写:
!`git diff HEAD`Claude 收到的就是带着当前代码差异的指令，你不用手动复制 diff，它也能根据实际改动写摘要。
最后
可以先从一个经常重复的小任务开始，比如上面的 README 生成。把每次都要交代的要求整理进去，实际用几次，哪里没按预期来，再补上对应的说明或示例。
下次你又对 AI 说“这个要求上次不是说过了吗”，就可以想想：是不是该把它整理成一个 Skill 了。