本文针对已掌握基础任务型Skill创建方法，却不清楚参考型Skill定义、用途及创建流程的学习者，精准解决核心困惑：明确参考型Skill的本质与应用场景，详解其SKILL.md文件的创建位置、编写规范（含中英文版本），拆解特征及description设计技巧，帮助学习者快速掌握参考型Skill的创建方法，轻松制定符合项目需求的规范类Skill。
通过上节课的学习，我们已经知道了什么是Skills,并且学会了自己创建一个最简单的任务型Skill。这节我们就主要学习如何创建参考型Skill。
一.什么是参考型Skill
参考型 Skill 往往定义的是一些规范。它定义“在这个世界里，什么是正确的做法”——例如 API 设计标准、代码风格、错误处理约定。这类 Skill 通常由模型根据语义自动判断是否加载，它不主导行动，而是塑造行动的方式。它属于“世界规则”。
我们最常用参考型Skill来完成下面三个方面的规范。
1. API设计标准
2. 代码风格规范
3. 错误处理约定
二. 创建参考型SKILL.md文件 api-conventions
这节课的重点就是创建这个SKILL.md文件，所以直接上手了。创建一个项目API的代码规范。先来看参考型skill的存放位置。
1.创建文件位置
我们依然创建一个项目集的skill（工作中90%的skill创建都是项目集的）。所以根据上节课学习的创建规则，我们依然把文件位置依然放到项目根目录下的.claude/skills/<skill-name>/SKILL.md。
安装要创建的技能名字是api-conventions 所以具体的目录就是.claude/skills/api-conventions/SKILL.md
2.编写SKILL.md文件
创建好SKILL.md文件后，就可以写这个规范了。
.claude/skills/api-conventions/ # skill 目录，名称即 skill 名
└── SKILL.md # 主文件（必需）
---
name: api-conventions
description: 本项目的 API 设计模式与规范。涵盖 RESTful URL 命名规则、响应格式标准、错误处理方式以及认证要求。在编写/评审 API 接口、设计新 API、或确定请求/响应格式时使用本规范。
allowed-tools:
- Read
- Grep
- Glob
---
# API 设计规范
以下是本项目的 API 设计标准。在处理所有 API 接口时，均需遵循这些规范。
## URL 命名规则
- 资源使用复数名词：`/users`、`/orders`、`/products`
- 多词资源使用烤串命名法（kebab-case）：`/order-items`、`/user-profiles`
- 从属关系的资源使用嵌套结构：`/users/{id}/orders`
- 嵌套层级最多两级；超过两级时使用查询参数
- 筛选条件使用查询参数：`/orders?status=active&limit=20`
## 响应格式
所有 API 响应必须遵循以下结构：
{
"data": {}, // 成功时返回的数据
"error": null, // 错误时返回错误对象 { code, message, details }
"meta": { // 分页和元信息
"page": 1,
"limit": 20,
"total": 100
}
}
## HTTP 状态码
- 200: 成功返回数据
- 201: 成功创建资源
- 400: 请求参数错误
- 401: 未认证
- 403: 无权限
- 404: 资源不存在
- 422: 业务逻辑错误
- 500: 服务器内部错误
## 认证规则
- 除非明确标记为公共接口，否则所有接口均要求携带 Bearer token
- 公共接口必须使用 @public 注解进行标注
- Token 格式：Authorization: Bearer <jwt-token>
## 版本控制
- URL 路径中包含 API 版本号：`/api/v1/users`
- 不兼容的变更必须创建新版本
这是我自己项目里用Skill制作的一个api规范，有了这个规范，接口就会完全按照规范来进行编写（当然你可以完全拷贝自用，如果你英文很好，可以使用英文版本）。
3.英文版本的SKILL.md文件
为了你方便直接使用，这里也 提供了英文版本。
.claude/skills/api-conventions/ # skill 目录，名称即 skill 名
└── SKILL.md # 主文件（必需）
---
name: api-conventions
description: API design patterns and conventions for this project. Covers RESTful URL naming, response format standards, error handling, and authentication requirements. Use when writing or reviewing API endpoints, designing new APIs, or making decisions about request/response formats.
allowed-tools:
- Read
- Grep
- Glob
---
# API Design Conventions
These are the API design standards for our project. Apply these conventions whenever working with API endpoints.
## URL Naming
- Use plural nouns for resources: `/users`, `/orders`, `/products`
- Use kebab-case for multi-word resources: `/order-items`, `/user-profiles`
- Nested resources for belongsTo relationships: `/users/{id}/orders`
- Maximum two levels of nesting; beyond that, use query parameters
- Use query parameters for filtering: `/orders?status=active&limit=20`
## Response Format
All API responses must follow this structure:
{
"data": {}, // 成功时返回的数据
"error": null, // 错误时返回错误对象 { code, message, details }
"meta": { // 分页和元信息
"page": 1,
"limit": 20,
"total": 100
}
}
## HTTP Status Codes
- 200: 成功返回数据
- 201: 成功创建资源
- 400: 请求参数错误
- 401: 未认证
- 403: 无权限
- 404: 资源不存在
- 422: 业务逻辑错误
- 500: 服务器内部错误
## Authentication
- All endpoints require Bearer token unless explicitly marked as public
- Public endpoints must be documented with `@public` annotation
- Token format: `Authorization: Bearer <jwt-token>`
## Versioning
- API version in URL path: `/api/v1/users`
- Breaking changes require new version
三.参考型Skill的特点（特征）
下面再说说参考型Skill的特征和设计难点，当你掌握好了下面的知识，会对它有更深刻的了解，你也完全能写出属于自己的参考型Skill了。
1. 四个基本特征
- 没有执行步骤：不是先做A，再做B，而是“遵循这些规范”。
- 没有输出模版：不要求Claude输出固定格式的报告。
- 没有设
disable-model-invocation:Claude 可以自动判断何时需要。 - 只读工具：
allowed-tools限制为 Read/Grep/Glob，因为规范查阅不需要修改代码。
2. description设计技巧
在参考型Skill里的description非常重要（这里需要强调三遍），因为它不是给人看的文档，而是给 Claude 看的触发器。
用户输入: "帮我看看这段代码有没有问题"
Claude 思考过程：
1. 扫描所有 Skills 的 description
2. 看到 "code-reviewing" 的 description:
"Review code for quality... Use when the user asks for code review..."
3. 语义推理："看看代码有没有问题" ≈ "code review"
4. 决定：激活这个 Skill
知道了为什么description重要，我们如何写好它呢，有一个description的协作公式：
description = [做什么] + [怎么做] + [什么时候用]
这里再给你几个常用的description写法：
# 代码审查 Skill
description: Review code for quality, security, and best practices. Checks for bugs, performance issues, and style violations. Use when the user asks for code review, wants feedback on their code, mentions reviewing changes, or asks about code quality.
# API 文档 Skill
description: Generate API documentation from code. Extracts endpoints, parameters, and response schemas. Use when the user wants to document APIs, create API reference, generate endpoint documentation, or needs help with OpenAPI/Swagger specs.
# 数据库查询 Skill
description: Query databases and analyze results. Supports SQL generation, query optimization, and result interpretation. Use when the user asks about data, wants to run queries, needs database information, or mentions tables/schemas.
总结
本文核心讲解了参考型Skill的定义、应用场景、创建流程及核心特征，明确其作为“世界规则”的定位，提供了可直接复用的中英文API规范SKILL.md模板，拆解了description的设计公式与技巧。通过学习，你已掌握参考型Skill的核心要点，无需畏惧规范编写的难点，大胆运用所学知识，结合项目需求实践，就能轻松打造符合自身需求的参考型Skill，提升工作规范性与效率。
留言
发表留言
邮箱必填，留言后等待管理员审核通过后显示。