摘要

随着 AI 编程工具在日常开发中的使用越来越频繁，很多开发者已经不满足于让 AI 简单回答问题，而是希望 AI 能够按照固定规范完成代码开发、接口设计、文档编写、代码审查、PPT 生成等任务。

Claude Code 的 Skills 提供了一种项目级能力沉淀方式。它可以将某类任务的执行流程、边界规则、验证方式写入项目目录，使 Claude Code 在合适场景下自动采用对应工作流。

本文将从实际开发角度出发，介绍 Claude Code Skills 的基本概念、目录结构、Skill 文件格式、设计原则、拆分方法、项目安装方式、GitHub 发布规范以及常见避坑点，帮助开发者构建一套可复用、可维护、适合团队协作的 AI 开发工作流。

常用skills地址：
github：https://github.com/yiweiwan/skills
gitee:https://gitee.com/in-case-of-reed/skills

一、前言

在刚开始使用 Claude Code 时，很多人会把它当成一个普通的 AI 编程助手。

例如：

  • 让它解释一段代码
  • 让它修复一个 bug
  • 让它生成一个接口
  • 让它编写 README
  • 让它优化一段 SQL
  • 让它帮忙生成项目文档

这种使用方式当然有效，但随着项目逐渐复杂，会出现一个明显问题：

每次都需要重复告诉 AI：应该遵守什么规范、按照什么流程做、输出什么格式、如何检查结果。

例如你让 Claude Code 设计 REST API 时，可能需要反复强调：

  • 接口路径要符合 REST 风格
  • 请求参数要有校验
  • 返回结构要统一
  • 错误码要规范
  • 分页、筛选、排序要完整
  • 权限、幂等性、异常处理都要考虑

如果每次都在对话里重新写一遍这些要求，不仅效率低，而且容易遗漏。

这时候，Claude Code 的 Skills 就非常有用了。

二、什么是 Claude Code Skills？

Claude Code Skills 可以理解为一组放在项目中的“专业任务说明书”。

它不是简单的提示词合集，而是结构化的工作流文件，用来告诉 Claude Code：

当遇到某类任务时，应该按照什么流程执行、遵守哪些边界、最终如何验证结果。

通常情况下，Skills 会放在项目根目录的 .claude/skills 目录中。

目录结构示例：

your-project/
├─ .claude/
│  └─ skills/
│     ├─ rest-api/
│     │  └─ SKILL.md
│     ├─ react-frontend/
│     │  └─ SKILL.md
│     └─ presentation-builder/
│        └─ SKILL.md

其中：

Skill 名称 作用
rest-api 用于 REST API 设计、实现和修改
react-frontend 用于 React 前端页面或组件开发
presentation-builder 用于 PPT、幻灯片结构设计
runbook-writing 用于运维手册、故障处理文档
api-documentation 用于接口文档编写

每个 Skill 通常对应一个独立目录，核心文件是：

SKILL.md

三、为什么需要 Skills？

1. 减少重复提示词

没有 Skills 时，你可能每次都要这样写：

请你帮我设计一个 REST API，要求路径规范、状态码合理、返回结构统一、参数校验完整、支持分页筛选排序，并且考虑权限和错误处理。

有了 Skills 后，这些规则可以提前写入 rest-api/SKILL.md 中。

之后你只需要告诉 Claude Code：

帮我设计一个订单列表接口，支持分页和状态筛选。

Claude Code 就可以根据 Skill 中的规则执行。

2. 让 AI 输出更加稳定

普通提示词容易受到上下文影响。

同样一个任务，不同时间、不同对话中，AI 的输出可能不一致。

而 Skills 的作用是把稳定规则固化下来，使 Claude Code 在对应场景下尽可能按照同一套流程执行。

例如代码审查类 Skill 可以固定要求检查：

  • 业务逻辑错误
  • 边界条件
  • 安全风险
  • 性能问题
  • 异常处理
  • 缺失测试
  • 回归风险

这样每次代码审查的关注点都会更加稳定。

3. 适合团队沉淀规范

对于团队来说，Skills 不仅是个人效率工具，也可以作为团队规范的一部分。

比如团队可以把以下内容沉淀成 Skills：

  • REST API 设计规范
  • 前端组件开发规范
  • 数据库迁移规范
  • 代码审查规范
  • README 编写规范
  • Release Notes 编写规范
  • 运维 Runbook 编写规范
  • 安全检查规范

这样不同成员使用 Claude Code 时，也能尽量保持一致的开发风格和交付标准。

四、推荐的 Skills 仓库结构

如果只是单个项目内部使用，最简单的结构如下：

your-project/
└─ .claude/
   └─ skills/
      ├─ rest-api/
      │  └─ SKILL.md
      └─ react-frontend/
         └─ SKILL.md

如果你希望将 Skills 发布到 GitHub，建议使用更完整的结构：

.
├─ .claude/
│  └─ skills/
│     ├─ rest-api/
│     │  └─ SKILL.md
│     ├─ react-frontend/
│     │  └─ SKILL.md
│     └─ presentation-builder/
│        └─ SKILL.md
│
├─ docs/
│  └─ zh-CN/
│     ├─ 使用指南.md
│     └─ skills/
│        ├─ README.md
│        ├─ rest-api.md
│        ├─ react-frontend.md
│        └─ presentation-builder.md
│
├─ README.md
├─ CONTRIBUTING.md
├─ LICENSE
├─ .gitignore
└─ skills-directory.md

各文件作用如下：

文件或目录 说明
.claude/skills Claude Code 实际读取的技能目录
docs/zh-CN 给开发者阅读的中文文档
README.md GitHub 仓库首页说明
skills-directory.md Skills 总目录
CONTRIBUTING.md 贡献规范
LICENSE 开源协议
.gitignore 避免提交无关文件和敏感文件

这种结构的好处是：

  • Claude Code 能够直接读取 .claude/skills
  • 开发者可以阅读 docs/zh-CN
  • GitHub 首页有清晰说明
  • 后续扩展和维护更加方便

五、Skill 文件的基本格式

一个最小可用的 SKILL.md 通常包含两部分：

  1. frontmatter 元信息
  2. 正文工作流说明

示例：

---
name: rest-api
description: Use only when designing, implementing, or modifying REST APIs, including resources, HTTP methods, status codes, request validation, response shapes, pagination, filtering, sorting, idempotency, and REST error handling.
---

# REST API

## Workflow

1. Identify resource, action, caller, auth, and API contract.
2. Choose HTTP method and status codes according to existing repo practice.
3. Validate request body, params, query, headers, and auth context.
4. Keep response and error shapes consistent.
5. Document pagination, filtering, sorting, and idempotency when relevant.

## Verification

- Test success, validation failure, auth failure, not found, and conflict paths.

其中最重要的是：

description

因为 Claude Code 会根据 description 判断当前任务是否适合使用这个 Skill。

六、description 应该怎么写？

description 决定 Skill 的触发边界。

写得太宽，容易误触发。

写得太窄，又可能无法触发。

不推荐这样写：

description: Use this skill for backend development.

这个描述太宽泛，后端开发可能包括：

  • REST API
  • GraphQL
  • 数据库设计
  • 缓存
  • 队列
  • 权限认证
  • 性能优化
  • 日志监控

更推荐这样写：

description: Use only when designing, implementing, or modifying REST APIs, including resources, HTTP methods, status codes, request validation, response shapes, pagination, filtering, sorting, idempotency, and REST error handling.

这个描述明确指出：

  • 只用于 REST API
  • 包含资源设计、HTTP 方法、状态码、请求校验、响应结构等内容
  • 不泛化到所有后端开发任务

七、Skills 设计原则：窄 Skill 优先

设计 Skills 时，最重要的原则是：

一个 Skill 只解决一类任务。

很多人刚开始会写出这种大而全的 Skill：

frontend-implementation
backend-api
technical-writing
office-documents
research-synthesis

这些名称看起来很方便，但实际使用中容易出现问题：

  • 边界太宽
  • 触发不稳定
  • 规则过多
  • 执行目标不清晰
  • 容易和其他 Skill 重叠

更好的方式是拆成多个窄 Skill。

八、技术写作类 Skill 拆分示例

不要只写一个 technical-writing，而是拆成：

technical-writing      # 总控/路由
readme-writing         # README 编写
api-documentation      # API 文档
runbook-writing        # 运维手册
architecture-docs      # 架构文档
release-notes          # 发布说明
migration-guide        # 迁移指南

不同技术文档的写法是不一样的。

例如 README 更关注：

  • 项目简介
  • 安装方式
  • 快速开始
  • 配置说明
  • 常见问题

而 Runbook 更关注：

  • 故障现象
  • 影响范围
  • 排查步骤
  • 临时缓解
  • 回滚方案
  • 升级路径

如果全部放进一个 Skill，Claude Code 仍然需要自己判断当前到底应该写哪一种文档，稳定性就会下降。

九、PPT 类 Skill 拆分示例

很多人会把 PPT、演讲稿、汇报材料、BP 全部放进一个 Skill。

但它们实际关注点不同。

推荐拆分为：

presentation-builder   # PPT / 幻灯片制作
speaker-notes          # 演讲稿 / 讲稿
pitch-deck-builder     # 融资 BP / 销售 BP / 合作方案
report-outline         # 汇报大纲

其中 presentation-builder 应该只负责 PPT 页面本身，例如：

  • 页面标题
  • 页面顺序
  • 每页一个核心观点
  • 页面层级
  • 图文关系
  • 整体叙事主线

示例：

name: presentation-builder
description: "Use only when creating or editing PowerPoint-style slide decks: slide structure, slide titles, slide content, slide order, deck outline, visual slide hierarchy, and slide-by-slide storylines. Do not use for speaker notes, pitch strategy, general documents, emails, or research synthesis."

这样当用户说：

帮我做一份 10 页项目汇报 PPT

应该触发 presentation-builder。

当用户说：

帮我写一份演讲稿

则应该触发 speaker-notes。

十、REST API Skill 设计示例

后端 API 也不建议全部放进一个 backend-api。

推荐拆分为：

backend-api            # 后端 API 总控
rest-api               # REST API
graphql-api            # GraphQL API
auth-access-control    # 认证与权限
backend-performance    # 后端性能优化
database-migration     # 数据库迁移

rest-api 只关注 REST 接口相关内容。

例如：

  • Resource 资源设计
  • HTTP Method
  • Status Code
  • Request Validation
  • Response Shape
  • Error Shape
  • Pagination
  • Filtering
  • Sorting
  • Idempotency
  • Auth Context

一个较完整的 rest-api/SKILL.md 可以这样写：

---
name: rest-api
description: Use only when designing, implementing, or modifying REST APIs, including resources, HTTP methods, status codes, request validation, response shapes, pagination, filtering, sorting, idempotency, and REST error handling.
---

# REST API

## Workflow

1. Identify the API resource.
2. Identify caller, permission, and authentication context.
3. Choose HTTP method based on the operation.
4. Define request path, query parameters, headers, and body.
5. Validate all external inputs.
6. Keep response structure consistent with the existing project.
7. Define error response shape.
8. Add pagination, filtering, sorting, and idempotency when relevant.
9. Update API documentation.
10. Add tests for common and failure paths.

## Rules

- Use nouns for resources whenever possible.
- Do not expose internal database table names directly.
- Do not return raw exceptions to clients.
- Use consistent error codes and messages.
- Keep response fields stable once published.
- Use pagination for list APIs.

## Verification

Check the following cases:

- Success response
- Validation failure
- Authentication failure
- Authorization failure
- Resource not found
- Conflict
- Duplicate request
- Pagination boundary

十一、如何在项目中安装 Skills？

项目级安装最简单。

假设你已经准备好了 .claude 目录，可以直接复制到目标项目根目录。

Windows PowerShell 示例

Copy-Item -Recurse .\.claude D:\your-project\

安装后结构如下：

D:\your-project\
├─ .claude\
│  └─ skills\
│     ├─ rest-api\
│     │  └─ SKILL.md
│     └─ react-frontend\
│        └─ SKILL.md
├─ src\
├─ package.json
└─ README.md

然后使用 Claude Code 打开这个项目即可。

十二、项目级 Skills 和全局 Skills 如何选择？

推荐优先使用项目级 Skills。

原因如下：

类型 优点 缺点
项目级 Skills 和项目强绑定，规则更准确，方便团队共享 每个项目都需要维护
全局 Skills 一次配置，多项目可用 容易过宽，可能误触发
通用仓库 Skills 方便开源和复用 需要根据项目二次裁剪

比较推荐的做法是：

通用 Skills 仓库
        ↓
复制到具体项目
        ↓
根据项目规则进行调整
        ↓
项目内长期维护

也就是说，通用 Skills 可以作为模板，但真正使用时最好放到具体项目中。

十三、发布到 GitHub 前的检查清单

如果你准备把 Skills 仓库发布到 GitHub，建议至少做好以下检查。

1. 检查 SKILL.md 是否存在

每个 Skill 目录下都应该包含：

SKILL.md

可以使用 PowerShell 检查：

Get-ChildItem .\.claude\skills -Directory | ForEach-Object {
    $skillFile = Join-Path $_.FullName "SKILL.md"
    if (-Not (Test-Path $skillFile)) {
        Write-Host "Missing SKILL.md:" $_.FullName
    }
}

2. 检查文档是否对应

建议每个 Skill 都有一份面向开发者的中文说明文档。

对应关系如下：

.claude/skills/rest-api/SKILL.md
docs/zh-CN/skills/rest-api.md

可以使用下面的命令做简单检查：

Get-ChildItem .\.claude\skills -Directory | ForEach-Object {
    $name = $_.Name
    $docFile = ".\docs\zh-CN\skills\$name.md"

    if (-Not (Test-Path $docFile)) {
        Write-Host "Missing docs file:" $docFile
    }
}

3. 检查敏感信息

发布到 GitHub 前，必须检查是否包含敏感信息。

不要提交以下内容：

  • .env
  • token
  • API key
  • 密码
  • 私钥
  • 证书
  • 本机绝对路径
  • 个人邮箱
  • 手机号
  • 身份证号
  • 客户资料
  • 合同文件
  • 财务数据
  • 本地 Office 草稿
  • 临时压缩包

可以使用 rg 做基础扫描：

rg -n --hidden -S "C:\\Users|api[_-]?key|secret|token|password|private[_-]?key|BEGIN .*PRIVATE KEY|[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}" .

如果扫描结果中出现敏感内容，应先清理再提交。

十四、推荐的 .gitignore 配置

Skills 仓库建议添加 .gitignore 文件，避免误提交本地文件。

示例：

# Environment
.env
.env.*
*.local

# Node
node_modules/
dist/
build/

# Python
__pycache__/
*.pyc
.venv/
venv/

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Logs
*.log

# Archives
*.zip
*.rar
*.7z

# Office temp files
~$*.docx
~$*.pptx
~$*.xlsx

# Secrets
*.pem
*.key
*.crt

如果项目中确实需要提交 .vscode 或部分配置文件，可以根据实际情况调整。

十五、一个适合初学者的 Skills 建设路线

刚开始不建议一次性写几十个 Skills。

更推荐从最常用的场景开始。

第一阶段：先做 3 个 Skill

rest-api
readme-writing
code-review

这三个最常用，也最容易看到效果。

第二阶段：扩展到项目开发流程

react-frontend
database-migration
api-documentation
unit-test-writing

这时可以覆盖接口、前端、数据库和测试。

第三阶段：沉淀团队规范

architecture-docs
runbook-writing
release-notes
security-review
performance-review

这一阶段更适合团队协作和工程化管理。

十六、常见问题

1. Skills 是不是提示词？

不完全是。

普通提示词通常是一次性的，而 Skills 更像是长期存放在项目中的工作流规则。

可以简单理解为：

提示词：临时告诉 AI 怎么做
Skills：长期告诉 AI 遇到某类任务时怎么做

2. Skills 写得越多越好吗？

不是。

Skills 的价值不在于数量，而在于边界清楚。

一个好的 Skill 应该满足：

  • 只解决一类任务
  • 触发条件明确
  • 工作流清晰
  • 规则不过度泛化
  • 有明确验证方式
  • 不和其他 Skill 大量重叠

3. 宽泛 Skill 是否完全不能用？

不是。

宽泛 Skill 可以存在，但更适合作为总控或路由。

例如：

technical-writing
backend-api
research-synthesis

它们可以作为分类入口，但真正执行任务的，应该是更具体的 Skill。

例如：

technical-writing
├─ readme-writing
├─ api-documentation
├─ runbook-writing
└─ release-notes

4. Skills 是否适合团队使用？

适合。

尤其适合以下场景：

  • 团队接口风格不统一
  • 文档质量参差不齐
  • Code Review 关注点不一致
  • 新人不熟悉项目规范
  • AI 输出结果不稳定
  • 希望把经验沉淀为可复用流程

团队可以把 Skills 作为项目规范的一部分进行维护。

十七、实践建议

结合实际使用经验，设计 Claude Code Skills 时建议遵守以下原则：

  1. 一个 Skill 只解决一类任务。
  2. description 要写清楚触发边界。
  3. 不要把多个完全不同的任务塞进一个 Skill。
  4. 宽泛 Skill 只适合作为总控或路由。
  5. 正文重点写流程、规则和验证方式。
  6. .claude/skills 给 Claude Code 使用。
  7. docs/zh-CN 给开发者阅读。
  8. 发布到 GitHub 前必须做隐私检查。
  9. 项目级 Skills 优先于全局 Skills。
  10. 先从高频任务开始沉淀，不要一开始追求大而全。

十八、总结

Claude Code Skills 的核心价值，不是让 AI “知道更多”，而是让 AI “做得更稳定”。

没有 Skills 时，我们每次都需要重新告诉 AI：

这次要怎么做？
注意哪些规范？
输出什么格式？
如何检查结果？

有了 Skills 后，这些规则可以沉淀到项目中。

Claude Code 在处理 REST API、前端组件、README、PPT、Runbook、代码审查等任务时，就可以按照对应 Skill 中定义的流程执行。

对于个人开发者来说，Skills 可以减少重复提示词，提高开发效率。

对于团队来说，Skills 可以统一开发规范、文档规范和交付标准。

因此，如果你已经在使用 Claude Code 进行项目开发，非常建议从当前项目中最常用、最重复的任务开始，逐步建立自己的 Skills 库。

最后可以用一句话总结：

提示词解决的是一次对话的问题，Skills 解决的是长期工作流复用的问题。

# 人工智能
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

第T7周：咖啡豆识别

1. 数据加载与预处理 (tf.data)在深度学习中，高效的数据管道是加速训练的关键。快捷加载：使用 tf.keras.utils.image_dataset_from_directory 可以直接从本地文件夹结构中加载图片，它会自动将子目录的名称作为数据的分类标签（按字母顺序排列）。数据集性能优化（三大核心方法）：shuffle()：打乱数据顺序，防止模型记忆数据的输入顺序，提升泛化能力。pr

avatar AtomGit开源社区
cover

企业级mvc高校办公室行政事务管理系统管理系统源码｜SpringBoot+Vue+MyBatis架构+MySQL数据库【完整版】

avatar AtomGit开源社区
cover

前后端分离Spring Boot可盈保险合同管理系统系统｜SpringBoot+Vue+MyBatis+MySQL完整源码+部署教程

avatar AtomGit开源社区