[cc] Skills
一些相对高阶的实操。
Skills - 标准流程的菜谱（Recipe）
是什么？
固定某些流程的操作过程。
必要性：模型的输出是随机的，但有些过程完全没必要随机，而且随机有可能还会出问题，例如 几种不同的方案实现一个过程，但有些方案可能有bug 等等。
从哪来？
定位自己目前项目属于哪一类，然后再寻找合适的Skiils
一个官方例子：https://github.com/anthropics/skills/tree/main/skills
| 类别 | Skill 示例 | 说明 |
|---|---|---|
| 文档处理 | docx、pdf、pptx、xlsx | 生成和处理 Office 文档、PDF，生产级质量 |
| 创意设计 | algorithmic-art、canvas-design、slack-gif-creator | 生成算法艺术、设计画布、动图（模型需要支持多模态） |
| 开发技术 | frontend-design、mcp-builder、webapp-testing、artifacts-builder | 前端设计、MCP Server 生成、Web 应用测试 |
| 企业沟通 | brand-guidelines、internal-comms |
品牌规范、内部沟通模板 把 Anthropic 官方的品牌色和字体应用到任何可能受益于这套视觉风格的产出物上——遇到需要品牌色、样式规范、视觉排版或公司设计标准的场合就会触发。 |
| 工具 | skill-creator | 用 AI 创建新 Skill 的 Skill（"元技能"） |
另一个偏向于前端开发的例子：https://github.com/vercel-labs/skills/tree/main/skills/find-skills（找skill的skill）
另一个星数夸张的例子：https://github.com/mattpocock/skills/tree/main/skills
| 仓库 | 数量 | 实际情况 |
|---|---|---|
| ComposioHQ/awesome-claude-skills | 127+ | 实际 1000+，差了一个数量级 |
| alirezarezvani/claude-skills | 235+ | 仓库自己说是 362，但同一仓库不同页面还写着 192、345、43、37+ 这些互相矛盾的数字——说明这个项目的自我统计本身就很混乱，而且在快速变化 |
| travisvn/awesome-claude-skills | 持续更新 | 描述准确，是个持续增长的精选清单，且有质量门槛 |
| glebis/claude-skills | 专项 | 没搜到确切信息核实 |
怎么用？
今天 Anthropic 官方强调：name and description。尤其是 description。
官方现在甚至明确把 description 当作触发 Skill 的主要机制之一。且 skill-creator 现在甚至专门对 description 做 triggering accuracy 优化。
这其实不是简单地：
“新版本把 trigger 删除了。”
而是一次设计思想升级：
早期：
keyword trigger↓
现在：
semantic trigger
怎么写？
description: Use this skill whenever the user wants to do anything with ...
内部路由（Overview）：
如果想要表达的有太多，也就是想要告诉大模型的话有好多。
This guide covers essential PDF processing operations using Python libraries and command-line tools.
For advanced features, JavaScript libraries, and detailed examples, see REFERENCE.md.
If you need to fill out a PDF form, read FORMS.md and follow its instructions.
PDF任务 │ ├── scripts --> 常用脚本文件 | ├── 普通PDF任务 → 继续读 SKILL.md │ ├── 高级任务 → reference.md │ └── 填PDF表格 → forms.md
Quick Start
from pypdf import PdfReader, PdfWriter # Read a PDF reader = PdfReader("document.pdf") print(f"Pages: {len(reader.pages)}") # Extract text text = "" for page in reader.pages: text += page.extract_text()
可能要做什么？给你一个使用 “推荐工具” 处理该类事情的示范。
pypdf
→ PDF结构操作
→ merge / split / rotate / metadata
pdfplumber
→ 内容提取
→ text / table
reportlab
→ 创建PDF
→ layout / pages / text
常用任务的实现示范
任务代码示范例子
-
For advanced pypdfium2 usage, see REFERENCE.md
-
For JavaScript libraries (pdf-lib), see REFERENCE.md
-
If you need to fill out a PDF form, follow the instructions in FORMS.md
-
自定义 Skill
为何使用skill-creator？因为既能创建测试用例，又能验证技能效果 via 前后比对。
安装后，在 Claude Code 中输入：
用
skill-creator帮我创建一个名为weekly-report-generator的技能。
功能：每周自动扫描本周的 Git 提交记录和 TODO 变更。
生成一份结构化的周报 Markdown 文件。
需要的工具：Read、Glob、Bash（用于 git log）。
构建自己的 Skill
Skill 很大程度上就是在给 Agent 提供 SOP（Standard Operating Procedure）：别每次从零思考，按成熟流程做。
.claude/skills/react-component/ # Skill 根目录 ├── SKILL.md # 核心指令文件 ├── scripts/ # 辅助脚本 │ └── validate.js # 组件结构验证脚本 └── resources/ # 配套资源 ├── template/ # 代码模板 │ ├── component.tsx.tpl # 组件主文件模板 │ └── test.tsx.tpl # 测试文件模板 └── examples/ # 示例 └── BookmarkCard-example/ # 一个完整的示例组件供参考
近期最新的推荐写法：
.claude/
└── skills/
└── react-component-generator/
├── SKILL.md
│
├── assets/
│ └── templates/
│ ├── component.tsx.tpl
│ └── test.tsx.tpl
│
├── references/
│ └── examples/
│ └── BookmarkCard-example/
│ ├── index.tsx
│ ├── types.ts
│ └── BookmarkCard.test.tsx
│
└── scripts/
└── validate.js # test在于组件本身，而这里更像是交付任务的检查器
SKILL.md → 这个 Skill 的入口、规则、SOP、路由
Description / Discovery 立项 ↓ Understand Requirement 产品 ↓ File / Template Policy 开发环境及条件 ↓ Coding & Testing Policy 开发与测试 ↓ Mandatory Validation 验证 ↓ Definition of Done 交付 ↓ Example
assets/ → 生成结果时直接使用的资源，例如模板
references/ → Agent 需要时读取的知识、示例、规范
scripts/ → Agent 可以执行的确定性工具
1. Frontmatter：Skill 的身份与触发
原始版本
---
name: react-component-generator
# 用于人工版本管理，思想没问题，但不是 Skill 的核心。
version: 1.0
# 说明“这个 Skill 做什么”。
description: 根据组件名称和功能描述，生成符合项目规范的 React 组件文件集
# 早期常见做法：通过显式关键词定义触发条件。
trigger: ["创建组件", "新建React组件", "生成组件"]
# 这里实际表达的是技术栈，不是真正意义上的 Agent tools。
tools: ["typescript", "react", "tailwindcss"]
# 维护信息，对 Agent 执行任务本身没有帮助。
author: your-name
---建议版本
---
name: react-component-generator
# 现代写法：description 同时说明 What + When，
# 让 Agent 通过语义理解判断是否应该使用此 Skill。
description: >
根据用户需求生成符合当前项目规范的 React 组件文件集。
当用户要求创建、添加或生成新的 React 组件时使用此 Skill。
---这里最重要的变化其实只有一个：
旧：description + trigger keywords
新：description → semantic triggering2. Skill Scope：什么时候使用
原始版本
# React 组件生成器
## 触发条件
当用户要求创建新的 React 组件时使用此 Skill。 # Jeff: 已经在如上的description中覆盖了
<!--
这和 Frontmatter 中的 trigger 基本重复。
它表达的思想没错，但放在这里价值已经不大。
-->建议版本
# React 组件生成器
## Scope
用于按照当前项目规范创建新的 React 组件。
<!--
如果需要这一节，与其再次写“什么时候触发”，
不如说明这个 Skill 的能力边界。
-->也就是说：
Frontmatter
→ 负责“什么时候找到这个 Skill”
正文 Scope
→ 负责“这个 Skill 管到哪里”3. 输入参数：从传统 Function 转向 Agent 理解需求
原始版本
## 输入参数
- componentName（必填）：组件名称，使用 PascalCase 格式
- description（必填）：组件功能描述
- hasProps（可选，默认true）：是否需要 Props 类型定义
- hasState（可选，默认false）：是否需要状态管理
<!--
这是很典型的参数化 SOP：
Input
↓
Process
↓
Output
优点是非常明确。
但它把 Skill 写得有点像函数：
createComponent(name, description, hasProps, hasState)
现代 Agent 已经可以从自然语言中自己推断这些信息。
-->建议版本
## 需求理解
从用户需求和现有代码中确定：
- 组件名称，使用 PascalCase
- 组件的主要功能
- 需要的 Props
- 是否需要 local state
<!--
不再要求用户显式填写 hasProps=true / hasState=false。
Agent 应优先自行推断。
只有缺失信息真正阻碍实现时，再向用户询问。
-->这个变化很重要：
旧：
User → Structured Parameters → Agent
新：
User → Natural Language → Agent Understanding但原来的“参数”并没有消失，它们只是变成了 Agent 内部需要理解的信息。
4. 文件结构与 Template
原始版本
## 执行步骤
1. 在 `src/components/` 目录下创建组件文件夹：
`src/components/{componentName}/`
2. 参考 `resources/template/` 中的模板文件创建以下文件：
- `index.tsx` - 组件主文件（参考 component.tsx.tpl）
- `types.ts` - TypeScript 类型定义（如果 hasProps=true）
- `{componentName}.test.tsx` - 测试文件（参考 test.tsx.tpl）
<!--
这部分设计得很好。
src/components/
→ 固定项目目录规范
resources/template/
→ 保存成熟的标准代码骨架
SKILL.md 不需要把模板代码本身全部写进来，
只需要告诉 Agent 什么时候、怎样使用模板。
-->建议版本
## 文件创建
1. 在 `src/components/` 下创建：
`src/components/{componentName}/`
2. 使用 `resources/template/` 中的模板作为默认实现骨架：
- `index.tsx`
- 使用 `component.tsx.tpl`
- `types.ts`
- 当组件需要 Props 类型时创建
- `{componentName}.test.tsx`
- 使用 `test.tsx.tpl`
<!--
主要变化：
“参考模板”
↓
“使用模板作为默认骨架”
这样约束更强，减少 Agent 每次重新设计组件结构。
-->这其实就是：
SKILL.md
→ Workflow / Policy
template
→ Canonical Skeleton这部分原版已经相当不错。
5. Coding Policy + Testing Policy
原始版本
3. 组件代码规范：
- 使用函数式组件 + TypeScript
- Props 使用 interface 定义，命名为 {componentName}Props
- 使用 Tailwind CSS 处理样式
- 导出使用 named export
- 添加 JSDoc 注释说明组件功能
4. 测试代码规范：
- 使用 @testing-library/react
- 至少包含：渲染测试、Props 传递测试
<!--
这是整个 Skill 最有价值的部分之一。
Claude 本来就知道 React，也知道很多种正确写法。
这里不是在“教 React”，而是在告诉 Agent：
在这个项目里，
不要自己选择，
按照我们的约定来。
同时测试要求开始定义最低质量标准。
-->建议版本
## 组件规范
- 使用函数式 React 组件和 TypeScript
- Props 使用 `interface`
- Props 命名为 `{componentName}Props`
- 使用 Tailwind CSS
- 使用 named export，不使用 default export
- 添加简洁的 JSDoc 说明组件职责
## 测试规范
使用 `@testing-library/react`。
至少包含：
- 渲染测试
- Props 传递测试
如果组件包含其他重要行为，为这些行为增加相应测试。这部分我基本赞成原作者。
因为它体现的是 Skill 一个非常核心的价值：
Model:
“我知道很多种做法。”
Skill:
“很好，但在这个项目里请这样做。”也就是减少选择空间，而不是增加知识量。
6. Validation：从 Helper 升级成 Quality Gate
原始版本
5. 创建完成后，可运行 `scripts/validate.js` 验证组件结构完整性。
<!--
设计思想很好：
LLM
→ 负责生成
validate.js
→ 负责确定性检查
问题主要在“可运行”。
既然已经有可靠的 validator，
就没必要让 Agent 自己决定是否检查。
-->建议版本
## 验证
创建完成后，运行：
`scripts/validate.js`
如果验证失败：
1. 分析失败原因
2. 修复相关文件
3. 再次运行验证
重复以上过程，直到验证通过。 # Jeff: 体现了 Loop Engineering 的思想。
<!--
这样 validator 从 optional helper
升级成真正的 quality gate。
-->这一步实际上把原来的：
Generate
→ Maybe Validate
→ Finish升级成：
Generate
↓
Validate
↓
Fail → Fix
↑ │
└──────┘
↓
Pass这是我认为原版最值得改的一处。
7. 输出规范：定义什么叫 Done
原始版本
## 输出规范
- 所有文件创建完成后，报告创建的文件列表
- 给出组件的使用示例代码
<!--
这部分很好。
它告诉 Agent：
写完代码还不等于整个任务完成。
已经开始定义 Completion Criteria。
-->建议版本
## 完成标准
只有满足以下条件后，任务才算完成：
- 所需组件文件已经创建
- 必要测试已经创建
- `scripts/validate.js` 验证通过
- 报告创建或修改的文件列表
- 给出组件的基本使用示例
<!--
把 Output Specification 进一步升级成 Definition of Done。
-->8. Example + External Example
原始版本
## 参考示例
参见 `resources/examples/BookmarkCard-example/` 中的完整示例。
## 示例
输入：
- componentName: "BookmarkCard"
- description: "展示单个书签的卡片组件，显示标题、URL和标签"
- hasProps: true
- hasState: false
预期输出文件：
- src/components/BookmarkCard/index.tsx
- src/components/BookmarkCard/types.ts
- src/components/BookmarkCard/BookmarkCard.test.tsx
<!--
这里实际上有两层 Example：
SKILL.md 中的小例子
→ 快速说明 Input → Output
resources/examples/
→ 完整成品
这个分层是好的。
-->建议版本
## 参考示例
需要查看完整实现时，参考：
`resources/examples/BookmarkCard-example/`
## 示例
用户请求：
> 创建一个 BookmarkCard 组件，
> 用于展示书签标题、URL 和标签，
> 不需要内部状态。
预期生成：
- `src/components/BookmarkCard/index.tsx`
- `src/components/BookmarkCard/types.ts`
- `src/components/BookmarkCard/BookmarkCard.test.tsx`
<!--
主要变化是：
传统参数输入
→ 自然语言输入
更符合 Agent 实际工作的方式。
-->实战：创建一个 API 端点生成 Skill
.claude/skills/api-endpoint/ ├── SKILL.md # 核心指令 └── resources/ └── config/ └── response-format.json # API 统一返回格式定义
【SKILL.md写法示范】
name: api-endpoint description: > 为当前项目创建符合既有规范的 RESTful API endpoints。 当用户要求为数据模型创建、添加或生成 CRUD API、REST API 或 API route 时使用此 Skill。
RESTful API 端点生成器
Scope
用于为当前项目的数据模型创建标准 RESTful CRUD API。
默认支持：
-
-
create
-
read
-
update
-
delete
-
list
-
需求理解
从用户需求和现有项目代码中确定：
-
-
数据模型名称
-
模型字段
-
需要支持的操作
-
输入验证要求
-
分页和搜索需求
-
尽可能从用户描述、Prisma schema 和现有 API 代码中推断。
只有缺失信息会阻碍实现时，才向用户询问。
实现前检查
在创建代码之前：
-
查看现有
src/app/api/下的 API 实现 -
查看 Prisma schema 和对应 model
-
遵循项目已有的命名、验证和错误处理方式
-
读取
references/config/response-format.json并使用其中定义的统一 API 返回格式
-
执行步骤
根据需要创建：
src/app/api/{modelName}s/
├── route.ts
└── [id]/
└── route.ts
Collection Endpoint
在：
src/app/api/{modelName}s/route.ts
实现：
-
-
GET /api/{modelName}s-
获取列表
-
支持分页
-
支持搜索
-
-
POST /api/{modelName}s-
创建记录
-
-
Item Endpoint
在：
src/app/api/{modelName}s/[id]/route.ts
实现：
-
-
GET /api/{modelName}s/[id]-
获取单条记录
-
-
PUT /api/{modelName}s/[id]-
更新记录
-
-
DELETE /api/{modelName}s/[id]-
删除记录
-
-
代码规范
-
-
使用 Prisma Client 操作数据库
-
API 返回格式遵循
references/config/response-format.json -
对用户输入进行验证
-
对预期错误进行明确处理
-
返回合适的 HTTP status code
-
遵循项目已有 TypeScript 和 API coding conventions
-
不重复实现项目中已经存在的公共 helper
-
完成检查
完成后确认：
-
-
所需 API route 文件已经创建
-
请求参数和 body 已进行必要验证
-
Prisma 操作与实际 model 字段一致
-
success / error / list response 符合统一格式
-
所要求的 CRUD operations 均已实现
-
没有破坏现有项目的 API convention
-
输出
完成后向用户报告：
-
-
创建或修改的文件
-
创建的 API endpoints
-
每个 endpoint 支持的 HTTP method
-
-
把 Skills 组合成了一套完整的软件开发方法：brainstorming、planning、TDD、systematic debugging、subagent-driven development、code review、verification 等。官方插件页面也把它定义成一个 structured software development methodology。
所以这两句话合起来，其实表达的是 Superpowers 一个很强的设计哲学：
Skill 不是“有空参考一下的文档”，而是优先级很高的标准工作流程。只要可能适用，就先调用；一旦调用，就按它的流程做。
这也是为什么 Superpowers 会显得比普通 Skills 更“强势”——它是在主动压缩 Agent 的自由发挥空间，尽量让开发行为走 Jesse Vincent 已经设计好的工程流程。
安装：npx superpowers-zh
已经装好了，.claude/skills/ 下现在有 20 个 skill。按功能分类列一下：
开发流程类（配合任务生命周期使用）
- brainstorming — 做任何创造性工作（新功能、新组件）之前先用，探索需求和设计意图，而不是直接开写
- writing-plans — 需求明确后、动手写代码前，先写实现计划
- executing-plans — 有一份书面计划、要在独立会话中按检查点执行时用
- subagent-driven-development — 用子任务/子代理拆解并执行实现计划
- dispatching-parallel-agents — 遇到 2 个以上互不依赖、可并行的任务时用
- test-driven-development — 写实现代码前先写测试
- systematic-debugging — 遇到 bug/测试失败/异常行为时，先系统排查再动手修
- verification-before-completion — 声称"完成/修复/测试通过"之前，必须先跑验证命令拿到证据
- using-git-worktrees — 需要跟当前工作区隔离开发时，用 git worktree 建独立环境
- finishing-a-development-branch — 实现完、测试都过了，决定怎么收尾集成这个分支
代码审查类
- requesting-code-review — 完成任务/合并前，请求代码审查
- receiving-code-review — 收到审查意见后，先技术核实、别盲目照做或和稀泥
中文本地化参考类（都是显式 /xxx 调用才触发，不会自动介入）
- chinese-code-review — 中文 code review 话术模板、分级标注习惯
- chinese-commit-conventions — 中文 Conventional Commits / commitlint 配置
- chinese-documentation — 中文文案排版规范（全半角、术语、链接格式）
- chinese-git-workflow — Gitee/Coding.net/极狐GitLab 等国内平台的接入配置
其他工具类
- mcp-builder — 系统化搭建生产级 MCP server
- workflow-runner — 直接在 Claude Code 里跑 YAML 格式的多角色协作工作流，不需要 API key
- writing-skills — 创建/编辑/校验一个新 skill 该怎么写
框架自身
- using-superpowers — 每次对话开始都会触发，规定"怎么找 skill、怎么用 skill"这一整套元规则（就是它让 CLAUDE.md 被追加了那段"响应前必须先检查 skill"的指令）
那到底什么是插件呢？
- 2025 年 10 月 9 日：Anthropic 官方发布 Claude Code Plugins 插件系统 公测，允许开发者通过
/plugin命令自由打包和分享斜杠命令、Subagents、MCP 服务和自动化 Hooks Medium: Lalatendu Swain。 - 2026 年 1 月 - 2 月：Anthropic 密集推出了数十款官方和合作伙伴预构建插件，全面覆盖工程研发、架构设计、金融服务、数据分析等细分领域 Claude Cowork Directory。
浙公网安备 33010602011771号