### 2.4 为什么需要 AI 编程技能

用 AI 编程工具写过实际项目的人都会碰到一个瓶颈：通用模型知道概念，但不知道怎么落地。举个例子：

- AI 知道"要写测试"，但面对遗留代码时，它不知道该怎么写一份能跑、可维护的 Playwright 集成测试
- AI 理解"SEO 优化"这个词，但不清楚 Google Core Web Vitals 的评分细则和具体修复步骤
- AI 会写代码，但设计数据库表结构或 API 版本管理时缺乏工程判断

Skills 解决的就是这个"知道概念 vs 知道怎么干"的落差——直接给出工作流，而非补充背景知识。每个技能包含：

| 组件 | 说明 |
|------|------|
| **SKILL.md**（技能定义文件） | 技能的核心指令文件，包含工作流程、决策框架和执行步骤 |
| **Python 工具**（纯标准库 stdlib-only） | 268 个纯 Python 标准库 CLI 脚本（无任何第三方依赖），提供自动化能力 |
| **参考文档**（references） | 模板、检查清单、推荐做法文档等支撑材料 |

---

## §3 原理分析

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

Claude Code Skills 的设计思路很朴素：你给 AI 的指令越具体，它的输出越靠谱。与其希望 AI "恰好知道"某个领域的推荐做法，不如把专家的决策流程写成一份标准化文件，AI 照着执行。

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

```text

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

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

### 3.2 Skills vs Agents vs Personas：三层架构

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

| 维度 | **Skills** | **Agents** | **Personas** |
|------|------------|------------|--------------|
| **核心问题** | 如何执行任务 | 应该执行什么任务 | 谁在思考 |
| **范围** | 单领域 | 单领域 | 跨领域 |
| **语气** | 中性专业 | 专业严肃 | 个性化驱动 |
| **适用场景** | 标准化执行 | 自动化流程 | 创意咨询 |
| **示例指令** | "Follow these steps for SEO" | "Run a security audit" | "Think like a startup CTO" |

**Skills** 解决"怎么做"。加载 `/seo-auditor` 后，AI 会按文件里写好的流程——检查 meta 标签、跑 Lighthouse、输出按优先级排列的修复列表——而不是随口说一句"优化一下 SEO"。它的价值是把一次性的提示词变成了可重复执行的检查清单。

**Agents** 在 Skills 之上加了"该做什么"的判断。`/security-agent` 不等人命令，它会自己扫描项目里值得审计的地方，然后按需拉起对应的 Skills。你可以把它理解为给 AI 装了一组触发规则。

**Personas** 改的是思考框架，不绑定特定任务。给 AI 设定 `"Think like a startup CTO"` 后，它在讨论技术选型时会自动带上成本、团队能力、迁移风险的权衡——这不是任何一个 Skill 能单独做到的，因为它跨了工程、产品和商业三个维度。

### 3.3 技能分类体系

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

| 领域 | 技能数 | 代表技能 | 覆盖方向 |
|------|--------|---------|---------|
| **Engineering — Core** | 26 | 架构设计、前后端开发、QA、DevOps | 软件工程全生命周期 |
| **Playwright Pro** | 9+3 | 测试生成、flaky 修复、Cypress 迁移 | 企业级 UI 自动化测试 |
| **Self-Improving Agent** | 5+2 | 自动记忆管理、模式提炼、技能提取 | 让 AI 在对话中积累经验 |
| **Engineering — POWERFUL** | 30 | Agent 设计器、RAG 架构师、CI/CD 构建器 | 复杂系统设计与实现 |
| **Product** | 14 | 产品经理、UX 研究员、SaaS 脚手架 | 产品思维与用户洞察 |
| **Marketing** | 43 | SEO 审计、内容营销、社交媒体 | 增长与获客 |
| **RA/QM** | 12 | 监管合规、质量管理 | 企业合规与质量保障 |
| **Project Management** | 6 | 敏捷教练、Sprint 规划 | 项目交付管理 |
| **C-level Advisory** | 28 | CTO/CFO/COO 顾问 | 高管决策支持 |
| **Finance** | 2 | 金融分析师、SaaS 指标 | 财务分析与商业智能 |
| **Business & Growth** | 4 | 增长策略、商业模式 | 商业战略 |

### 3.4 Python 工具的设计约束

268 个 Python 工具脚本承载了技能的大部分自动化能力。它们有几条硬约束：

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

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

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

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

### 3.5 一次真实任务如何流过三个技能

只看静态结构容易觉得技能就是"进阶版提示词"。放到一次具体任务里看，区别会更清楚。

假设你要给一个新项目设计用户认证系统。你加载了 `database-designer`、`api-designer` 和 `backend-dev` 三个技能，然后对 AI 说："设计一套用户注册登录的数据库和 API。"

AI 不会像没加载技能时那样直接给出一个大概方案。`database-designer` 的 SKILL.md 里写好了：先确认业务实体、再画关系图、再输出 DDL、最后给索引建议。AI 会按这个顺序提问——"用户有几种角色？需要支持第三方登录吗？会话管理用什么策略？"——等你回答完，它产出的是一份带主键、外键、索引策略的完整 schema，而不是一句 "users 表应该有 id、email、password"。

接着 `api-designer` 接管。它的 SKILL.md 规定了 RESTful 端点命名规范、版本号策略和错误响应格式。AI 读入上一步的 schema，输出 `/api/v1/auth/register`、`/api/v1/auth/login` 等端点的完整定义——请求体、响应体、状态码、rate limit 建议——格式与团队已有的 OpenAPI 规范一致。

最后 `backend-dev` 上场。它的指令文件告诉 AI：先检查数据库 schema 和 API 定义是否存在、再决定用什么 ORM、再生成带参数校验和错误处理的代码骨架。AI 发现前两步的产物都在上下文里，直接生成了 Express + Prisma 的实现，每个端点都带了输入校验中间件。

这三个技能单独用也能工作，但串联起来效果不一样：每个技能的输出格式被下一个技能识别为"已知输入"，AI 不需要在每一步重新猜测上下文。这就是技能和零散提示词的根本差别——技能把工作流写进了文件，AI 只需要按检查清单推进。实际使用中，你可以按任务组合不同的技能链：SEO 审计链（auditor → copywriter）、安全评估链（auditor → fixer）、产品设计链（pm → ux → api-designer），每个链的交接点都是预定义的输出格式。

---

## §4 架构分析

### 4.1 仓库整体结构

```text

### 4.2 多格式转换架构

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

```text

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

### 4.3 安装脚本体系

| 脚本 | 用途 | 支持平台 |
|------|------|---------|
| `scripts/gemini-install.sh` | Gemini CLI 快速安装 | Gemini CLI |
| `scripts/openclaw-install.sh` | OpenClaw 快速安装 | OpenClaw |
| `scripts/codex-install.sh` | OpenAI Codex 安装 | Codex |
| `scripts/convert.sh` | 转换为所有工具格式 | 多平台 |
| `scripts/install.sh` | 安装到目标项目 | 多平台 |

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

### 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 Pro 是面向 UI 自动化测试的一组高级技能，提供：

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

```bash
# 安装 Playwright Pro 技能
/plugin install playwright-pro@claude-code-skills
```textbash
# 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
```textbash
# 一键安装脚本
bash <(curl -s https://raw.githubusercontent.com/alirezarezvani/claude-skills/main/scripts/openclaw-install.sh)
```textbash
# 克隆仓库
git clone https://github.com/alirezarezvani/claude-skills.git
cd claude-skills

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

# 在 Gemini CLI 中激活技能
> activate_skill(name="senior-architect")
```textbash
# 使用 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
```textbash
# 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（转换的技能总数）
```textbash
# 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/
```text
<skill-name>/
├── SKILL.md           # 必须：技能核心定义
├── README.md          # 必须：人类可读的使用说明
├── CLAUDE.md         # 必须：AI 智能体的配置与指令
├── tools/            # 可选：Python 工具脚本
│   ├── script1.py
│   └── script2.sh
├── references/       # 可选：参考文档
│   ├── template.md
│   └── checklist.md
└── package.json      # 必须：技能元数据
```textmarkdown
# 技能名称

## 概述
简要说明技能的用途和关键能力（2-3 句话）

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

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

## 执行流程

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

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

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

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

### 步骤 2：...

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

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

## 相关技能
- 本技能依赖的其他技能
- 可以与哪些技能配合使用
```textpython
#!/usr/bin/env python3
"""
技能名称 - 工具描述

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

import sys
import json
from pathlib import Path


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


if __name__ == "__main__":
    main()
```textjson
{
  "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": "工具功能描述"
    }
  ]
}
```textbash
# 在本地验证技能
./scripts/validate-skill.sh --skill <skill-name>

# 运行完整的技能测试套件
./scripts/run-tests.sh
```textbash
# 添加为 submodule
git submodule add https://github.com/alirezarezvani/claude-skills.git vendor/claude-skills

# 切换到稳定版本
cd vendor/claude-skills
git checkout v2.1.1
```text
team-claude-skills/
├── README.md
├── CLAUDE.md
├── skills/              # 团队共享技能
│   ├── internal-api-docs/
│   └── compliance-checker/
└── scripts/
    └── install.sh
```textbash
# 在 ~/.local/bin/ 创建符号链接
mkdir -p ~/.local/bin
ln -s ~/.claude/skills/engineering/tools/* ~/.local/bin/
```textbash
# 克隆仓库后
git pull origin main

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

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