Claude Code Skills & Plugins：AI 编程智能体技能库完全指南

§1 学习目标

学完本文档后，你将能够：

• 理解 Claude Code Skills 的核心概念与设计理念
• 掌握在 Claude Code、OpenAI Codex、Gemini CLI、OpenClaw 等 11 个 AI 编程工具中安装和使用技能的方法
• 了解 205 个技能的分类体系与核心功能
• 学会使用 convert.sh 脚本将技能转换为不同工具的原生格式
• 掌握开发新技能的规范与工作流程
• 理解 Skills、Agents、Personas 三层架构的适用场景
• 能够在团队中推广和应用这套技能系统

§2 项目概述

2.1 什么是 Claude Code Skills

Claude Code Skills（官方仓库：alirezarezvani/claude-skills，简称 Skills）是目前最全面的开源 AI 编程智能体技能库，收录了 205 个生产级技能（Skills）和插件（Plugins），支持 11 个主流 AI 编程工具。项目获得了 8,200+ GitHub Stars，973 Forks，由开发者 alirezarezvani 维护，采用 MIT 许可证开源。

这个项目的核心价值在于：将人类专家的领域知识封装为可复用的模块，让 AI 智能体获得开箱即用的专业能力。每个技能本质上是一个指令包，包含结构化的指导文件、标准库 Python 工具脚本和参考文档，AI 智能体加载后即可在对应领域展现专家级表现。

2.2 支持的平台

项目天然支持 11 个主流 AI 编程工具，覆盖市面上几乎所有重要的 AI 辅助编程产品：

注意：部分工具（如 Cursor、Aider）不支持 Python 工具脚本，仅支持指令规则转换，因此技能总数为 156 个而非完整的 205 个。

2.3 核心数据

Stars:     8,200+
Forks:     973
Commits:   587
最新提交:   2026-03-26
许可证:    MIT
开发者:    alirezarezvani

2.4 为什么需要 AI 编程技能

AI 编程工具（如 Claude Code）虽然具备强大的通用能力，但在垂直领域往往缺乏深度专业知识和标准化工作流程。举例来说：

• AI 可能知道"要写测试"，但不知道"如何针对遗留代码编写可维护的 Playwright 集成测试"
• AI 可能理解"SEO 优化"，但不了解"Google Core Web Vitals 的具体评分标准和修复方法"
• AI 可能能"写代码"，但缺乏"数据库表结构设计"和"API 版本管理"的专业判断

Claude Code Skills 通过为 AI 注入结构化的专家知识来解决这个问题。每个技能包含：

§3 原理分析

3.1 技能的本质：模块化专家知识封装

Claude Code Skills 的设计理念源于一个关键洞察：AI 编程工具的能力边界取决于其指令的精细程度。通过将领域专家的知识封装为标准化的技能模块，可以系统性地提升 AI 的专业表现。

一个典型的技能结构如下：

engineering/
├── SKILL.md              # 技能核心定义
├── README.md             # 使用说明
├── CLAUDE.md             # AI 智能体配置
├── tools/                # Python 工具脚本
│   ├── analyze.sh
│   └── generate.sh
├── references/           # 参考文档
│   ├── template.md
│   └── checklist.md
└── package.json          # 元数据配置

SKILL.md 是技能的核心，它定义了 AI 在该领域应该如何思考、提问、执行和验证。一个高质量的 SKILL.md 包含：

• 目标声明：明确技能要解决什么问题
• 前置条件：使用技能前需要满足什么
• 执行流程：分步骤的工作流程，每步都有明确的输入输出
• 决策框架：遇到分歧时如何判断
• 验证标准：如何确认任务完成质量

3.2 Skills vs Agents vs Personas：三层架构

项目区分了三种不同层次的智能增强方式，适用于不同场景：

Skills 是最基础的层次，解决"怎么做"的问题。例如 /seo-auditor 技能会告诉 AI 按照指定流程执行 SEO 审计，每一步都有清晰的检查标准。

Agents 在 Skills 基础上增加了"做什么"的判断能力。例如 /security-agent 会主动识别需要审计的场景，并协调多个 Skills 完成完整的安全评估。

Personas 提供跨领域的思维方式指导。例如 "Think like a startup CTO" 会让 AI 从技术决策者的视角权衡利弊，涉及产品、工程、商业多个维度。

3.3 技能分类体系

205 个技能划分为 9 大领域：

3.4 Python 工具的设计哲学

268 个 Python 工具脚本是技能自动化能力的重要载体。它们的设计遵循几个关键原则：

纯标准库：所有脚本仅使用 Python 标准库（stdlib），不依赖任何第三方包。这确保了脚本在任何 Python 环境中都能运行，不会因为 pip 安装问题而失败。

零外部依赖命令：工具脚本调用的外部命令（如 curl、jq、git）在脚本内部有fallback处理或明确的依赖声明。

原子化设计：每个脚本只做一件事，通过管道组合实现复杂功能。这种 Unix 哲学让工具可预测、可测试、可组合。

跨平台兼容：脚本经过测试可在 Linux、macOS、Windows（WSL）环境下正常运行。

§4 架构分析

4.1 仓库整体结构

claude-skills/
├── .autoresearch/           # AutoResearch SEO 相关技能
│   └── seo/
├── .claude-plugin/          # Claude Code 插件配置
├── .claude/                 # Claude Code 配置
│   └── commands/            # Slash commands
├── .codex/                  # OpenAI Codex 格式
├── .gemini/                 # Gemini CLI 格式
├── agents/                  # Agent 智能体模板
│   ├── cs-product-manager/
│   └── ...
├── business-growth/          # 商业增长技能
├── c-level-advisor/          # C-level 高管顾问技能
├── commands/                # 命令行工具
├── custom-gpt/               # 自定义 GPT 资源
├── docs/                     # MkDocs 文档站点
├── documentation/            # 参考文档库
├── engineering/              # 工程技能（POWERFUL 级）
├── engineering-team/          # 工程团队技能（核心）
├── eval-workspace/            # 评估工作区
├── finance/                  # 金融技能
├── marketing-skill/           # 营销技能
├── orchestration/            # 多智能体编排协议
├── product-team/             # 产品团队技能
├── project-management/        # 项目管理技能
├── ra-qm-team/              # 监管与质量管理技能
├── scripts/                  # 安装与转换脚本
├── standards/                # 开发规范
├── templates/                # 项目模板
├── CHANGELOG.md              # 版本变更日志
├── CLAUDE.md                 # Claude 配置入口
├── GEMINI.md                 # Gemini 配置入口
├── INSTALLATION.md           # 安装指南
├── README.md                 # 项目说明
├── SKILL-AUTHORING-STANDARD.md # 技能开发规范
├── SKILL_PIPELINE.md         # 技能开发流程
├── STORE.md                  # 技能商店目录
└── mkdocs.yml               # 文档站点配置

4.2 多格式转换架构

项目实现了一套巧妙的多工具格式转换系统。核心是 scripts/convert.sh 脚本，它能自动将基础技能转换为目标工具的原生格式：

源格式（SKILL.md）
       ↓
scripts/convert.sh
       ↓
┌──────────────────────────────────────┐
│  Cursor (.mdc)                       │
│  Aider (CONVENTIONS.md)              │
│  Windsurf (.windsurf/skills/)        │
│  Kilo Code (.kilocode/rules/)        │
│  OpenCode (.opencode/skills/)        │
│  Augment (.augment/rules/)           │
│  Antigravity (~/.gemini/antigravity/) │
└──────────────────────────────────────┘

转换过程是无损的：SKILL.md 中的结构化指令被转换为目标工具的等价格式，Python 工具脚本被包装为符合目标工具规范的执行方式。

4.3 安装脚本体系

安装流程设计为幂等操作：重复执行不会产生副作用，可安全重试。

4.4 版本管理策略

项目采用语义化版本号（SemVer），通过 CHANGELOG.md 记录每个版本的变更。最新稳定版本信息可在 GitHub Releases 页面查看。每个技能的版本通过 package.json 中的 version 字段管理，支持依赖锁定。

§5 功能详解

5.1 核心工程技能（Engineering — Core）

26 个核心工程技能覆盖软件开发的各个阶段：

架构与设计

• architecture-design — 系统架构设计决策
• database-designer — 数据模型与 Schema 设计
• api-designer — RESTful API 设计与版本管理

前端开发

• frontend-dev — React/Vue/Angular 最佳实践
• css-architect — CSS 架构与样式指南
• accessibility-audit — WCAG 合规性审计

后端开发

• backend-dev — 服务端架构与实现
• microservices — 微服务设计模式
• api-security — API 安全实践

质量保障

• qa-strategy — 测试策略制定
• e2e-testing — 端到端测试框架
• performance-testing — 性能基准与优化

DevOps

• ci-cd-builder — 持续集成/持续部署流水线
• docker-best-practices — Docker 容器化指南
• kubernetes-deployment — K8s 部署配置

5.2 Playwright Pro 测试技能

作为 Playwright 官方推荐的高级测试技能集，提供：

• 智能测试生成 — 根据页面行为自动生成测试用例
• Flaky 测试修复 — 自动识别并修复不稳定的测试
• 框架迁移 — Cypress/Selenium 到 Playwright 的自动迁移
• 测试管理集成 — TestRail、BrowserStack 等平台对接
• 55+ 测试模板 — 覆盖常见测试场景

# 安装 Playwright Pro 技能
/plugin install playwright-pro@claude-code-skills

5.3 自我提升智能体（Self-Improving Agent）

这是一套让 AI 在学习中持续进化的系统：

5.4 产品经理技能（Product Skills）

14 个产品相关技能帮助 AI 理解产品思维：

• product-manager — PRD 撰写与需求管理
• ux-researcher — 用户研究方法与洞察提取
• analytics-setup — 数据分析与指标体系
• experiment-designer — A/B 测试设计与分析
• roadmap-communicator — 技术方案与产品路线图的沟通

5.5 营销技能（Marketing Skills）

43 个营销技能覆盖数字营销全渠道：

SEO 与搜索优化

• seo-auditor — 全方位 SEO 审计，输出可执行的优化建议
• keyword-researcher — 关键词研究与竞争分析
• technical-seo — 技术性 SEO 问题诊断与修复

内容营销

• content-strategist — 内容策略规划
• blog-writer — 技术博客撰写模板
• copywriter — 转化率优化文案

社交媒体

• social-media-strategy — 多平台社交媒体运营
• twitter-growth — Twitter/X 增长策略

5.6 C-level 高管顾问技能

28 个高管顾问技能模拟不同职能高管的专业视角：

这些技能能够帮助 AI 在技术方案评审、商业计划审查等场景中提供多维度的高管级建议。

§6 使用说明

6.1 环境要求

• Python 3.8+（用于运行工具脚本）
• Git（用于克隆仓库）
• 对应平台的 AI 编程工具（Claude Code / Codex / Gemini CLI 等）

6.2 Claude Code 快速安装（推荐）

Claude Code 是项目官方推荐的平台，安装最简单：

# 1. 添加技能市场
/plugin marketplace add alirezarezvani/claude-skills

# 2. 安装全套技能（按领域分组安装）
/plugin install engineering-skills@claude-code-skills    # 26 个核心工程技能
/plugin install engineering-advanced-skills@claude-code-skills  # 30 个 POWERFUL 级技能
/plugin install product-skills@claude-code-skills      # 14 个产品技能
/plugin install marketing-skills@claude-code-skills     # 43 个营销技能
/plugin install ra-qm-skills@claude-code-skills         # 12 个监管/质量技能
/plugin install pm-skills@claude-code-skills           # 6 个项目管理技能
/plugin install c-level-skills@claude-code-skills     # 28 个 C-level 顾问技能
/plugin install business-growth-skills@claude-code-skills  # 4 个商业增长技能
/plugin install finance-skills@claude-code-skills      # 2 个金融技能

# 或安装单个技能
/plugin install skill-security-auditor@claude-code-skills
/plugin install playwright-pro@claude-code-skills
/plugin install self-improving-agent@claude-code-skills

6.3 OpenClaw 安装

# 一键安装脚本
bash <(curl -s https://raw.githubusercontent.com/alirezarezvani/claude-skills/main/scripts/openclaw-install.sh)

6.4 Gemini CLI 安装

# 克隆仓库
git clone https://github.com/alirezarezvani/claude-skills.git
cd claude-skills

# 运行安装脚本
./scripts/gemini-install.sh

# 在 Gemini CLI 中激活技能
> activate_skill(name="senior-architect")

6.5 OpenAI Codex 安装

# 使用 npx 安装
npx agent-skills-cli add alirezarezvani/claude-skills --agent codex

# 或手动克隆
git clone https://github.com/alirezarezvani/claude-skills.git
cd claude-skills
./scripts/codex-install.sh

6.6 Cursor / Aider 等工具的转换安装

# 1. 克隆仓库
git clone https://github.com/alirezarezvani/claude-skills.git
cd claude-skills

# 2. 转换为目标工具格式（以 Cursor 为例）
./scripts/convert.sh --tool cursor

# 3. 安装到项目
./scripts/install.sh --tool cursor --target /path/to/project

# 4. 验证安装
find .cursor/rules -name "*.mdc" | wc -l
# 应该输出 156（转换的技能总数）

支持的工具转换：

6.7 手动安装单个技能

如果只想安装特定技能而不是整个技能包：

# 1. 克隆仓库
git clone https://github.com/alirezarezvani/claude-skills.git
cd claude-skills

# 2. 复制技能文件夹到对应目录
# Claude Code
cp -r engineering ~/.claude/skills/

# OpenAI Codex
cp -r engineering ~/.codex/skills/

# 3. 验证
ls ~/.claude/skills/engineering/

§7 开发扩展

7.1 技能开发规范

创建一个新技能需要遵循 SKILL-AUTHORING-STANDARD.md 中定义的规范。一个标准技能的结构：

<skill-name>/
├── SKILL.md           # 必须：技能核心定义
├── README.md          # 必须：人类可读的使用说明
├── CLAUDE.md         # 必须：AI 智能体的配置与指令
├── tools/            # 可选：Python 工具脚本
│   ├── script1.py
│   └── script2.sh
├── references/       # 可选：参考文档
│   ├── template.md
│   └── checklist.md
└── package.json      # 必须：技能元数据

7.2 SKILL.md 编写指南

SKILL.md 是技能的核心，需要包含：

# 技能名称

## 概述
简要说明技能的用途和核心价值（2-3 句话）

## 前置条件
- 使用本技能前需要满足什么？
- 需要什么样的上下文？

## 适用场景
- 什么时候应该使用本技能？
- 什么情况下不应该使用？

## 执行流程

### 步骤 1：阶段名称
**做什么**：详细说明这一步的具体动作

**输入**：
- 什么信息/文件是必需的？

**输出**：
- 这一步应该产出什么？

**检查点**：
- 如何验证这一步完成了？

### 步骤 2：...

## 决策框架
遇到以下情况时如何判断：
- 情况 A vs 情况 B？
- 优先级的判断标准？

## 验证标准
任务完成前必须满足的条件列表

## 相关技能
- 本技能依赖的其他技能
- 可以与哪些技能配合使用

7.3 Python 工具编写规范

#!/usr/bin/env python3
"""
技能名称 - 工具描述

功能：简明描述工具做什么
输入：命令行参数或标准输入
输出：结构化结果（JSON/TOML）
依赖：仅使用 Python 标准库
"""

import sys
import json
from pathlib import Path


def main():
    # 实现工具逻辑
    pass


if __name__ == "__main__":
    main()

关键原则：

• 必须使用 #!/usr/bin/env python3 shebang
• 仅导入标准库模块
• 输入/输出使用 JSON 或纯文本
• 添加 --help 参数显示使用说明
• 脚本必须是可执行的（chmod +x）

7.4 package.json 元数据格式

{
  "name": "skill-<skill-name>",
  "version": "1.0.0",
  "description": "技能的简短描述",
  "author": "你的 GitHub 用户名",
  "license": "MIT",
  "homepage": "https://github.com/alirezarezvani/claude-skills",
  "repository": {
    "type": "git",
    "url": "https://github.com/alirezarezvani/claude-skills"
  },
  "keywords": ["skill", "domain", "ai", "claude-code"],
  "engines": {
    "claude-code": ">=1.0.0"
  },
  "dependencies": {},
  "tools": [
    {
      "name": "script-name",
      "file": "tools/script.py",
      "description": "工具功能描述"
    }
  ]
}

7.5 提交技能到社区

如果希望将开发的技能贡献回主仓库：

1. Fork 仓库
2. 在对应目录下创建技能文件夹
3. 确保符合 SKILL-AUTHORING-STANDARD.md 规范
4. 添加测试（如果有）
5. 创建 Pull Request
6. 等待 Code Review

贡献者需要签署 CLA（Contributor License Agreement）。

7.6 技能评估与验证

项目提供了 SkillCheck 验证框架，用于确保技能质量：

# 在本地验证技能
./scripts/validate-skill.sh --skill <skill-name>

# 运行完整的技能测试套件
./scripts/run-tests.sh

§8 最佳实践

8.1 技能选用策略

按需加载：不要一次性加载所有技能，这会增加 AI 的上下文负担。只安装当前任务需要的技能。

领域组合：某些领域技能天然搭配使用。例如：

• database-designer + api-designer + backend-dev 组合用于后端开发
• seo-auditor + content-strategist + copywriter 组合用于内容营销

渐进式深化：先安装核心技能，熟悉后再扩展到 POWERFUL 级和顾问级技能。

8.2 团队协作建议

技能版本锁定：在团队中共享技能时，使用 Git submodule 或特定的提交锁定版本：

# 添加为 submodule
git submodule add https://github.com/alirezarezvani/claude-skills.git vendor/claude-skills

# 切换到稳定版本
cd vendor/claude-skills
git checkout v2.1.1

团队自定义技能库：在主仓库基础上创建团队分支，添加公司特定技能：

team-claude-skills/
├── README.md
├── CLAUDE.md
├── skills/              # 团队共享技能
│   ├── internal-api-docs/
│   └── compliance-checker/
└── scripts/
    └── install.sh

8.3 性能优化

按需转换：不需要在所有工具中安装全套技能。使用 convert.sh 只转换你实际会用的工具格式。

工具脚本缓存：将常用工具脚本符号链接到 PATH 中，减少路径查找开销：

# 在 ~/.local/bin/ 创建符号链接
mkdir -p ~/.local/bin
ln -s ~/.claude/skills/engineering/tools/* ~/.local/bin/

8.4 故障排查

技能不生效：

1. 检查是否正确安装：/plugin list
2. 检查技能目录结构是否完整
3. 查看 Claude Code 日志：Settings → Debug → View Logs
4. 尝试重新安装：/plugin uninstall <skill> && /plugin install <skill>

工具脚本报错：

1. 检查 Python 版本：python3 --version（需要 3.8+）
2. 检查脚本权限：ls -la tools/
3. 手动运行脚本查看错误输出
4. 确认所有工具依赖已安装

§9 常见问题

Q1：技能和插件有什么区别？

在 Claude Code 语境下，“技能（Skills）“和"插件（Plugins）“基本等价，都指这种模块化的专家知识包。主要差异在于实现方式：

• Skills 通过 /skill activate 命令激活
• Plugins 通过 /plugin 命令管理

项目仓库同时包含两种实现，以兼容不同版本的 Claude Code。

Q2：为什么部分工具的技能数量是 156 而不是 205？

Cursor、Aider、Windsurf 等工具不支持 Python 工具脚本，仅支持指令规则转换。因此：

• 可转换的技能总数：156 个（不含纯 Python 工具类技能）
• Claude Code / Codex / Gemini CLI：205 个完整技能
• 其他工具：156 个规则类技能

Q3：技能会更新吗？如何同步更新？

项目通过 Git 追踪更新。你可以：

# 克隆仓库后
git pull origin main

# 或更新到特定版本
git fetch --all
git checkout v2.1.1

# 更新已安装的技能
./scripts/update-installed.sh

Q4：可以离线使用这些技能吗？

可以。克隆仓库后，所有技能都存储在本地。离线环境下：

• 技能指令和参考文档完全可用
• Python 工具脚本完全可用（纯标准库，无网络依赖）
• 部分需要外部 API 的工具（如 seo-auditor 调用 Google PageSpeed API）需要网络

Q5：如何报告技能的问题或提出改进建议？

• GitHub Issues：https://github.com/alirezarezvani/claude-skills/issues
• 功能请求：提交 Feature Request 类型 Issue
• Bug 报告：提交 Bug 类型 Issue，包含复现步骤

Q6：技能支持中文吗？

技能指令本身是英文编写，因为 AI 理解英文指令的效果最佳。但技能生成的内容可以是任何语言，包括中文。你可以在 CLAUDE.md 中指定输出语言偏好。

§10 总结

Claude Code Skills 是目前最全面的 AI 编程智能体技能库，通过模块化的专家知识封装，让 AI 编程工具在软件工程、产品管理、营销、运营等多个领域展现专业级表现。

核心优势：

• 205 个生产级技能，覆盖 11 个 AI 编程平台
• MIT 许可证，可自由使用和修改
• 纯标准库 Python 工具，零依赖，可靠性高
• 多工具格式自动转换，一套技能库多平台通用
• 活跃的社区维护，持续更新和优化

推荐学习路径：

1. 先安装 Engineering Core 技能（26 个），覆盖日常开发需求
2. 根据需要扩展到 Playwright Pro（测试）或 Self-Improving Agent（效率提升）
3. 探索 Product 和 Marketing 技能，拓展 AI 的应用边界
4. 最后尝试 C-level 顾问技能，获取高管视角的决策支持

链接资源：

• GitHub 仓库：https://github.com/alirezarezvani/claude-skills
• 官方文档：https://alirezarezvani.github.io/claude-skills/
• SkillCheck 验证：https://getskillcheck.com

🦞 文档版本 1.0 | 撰写日期：2026-03-31 | 基于仓库 commit 110348f (2026-03-26)