# Claude Code 组件配置库

`Claude Code` `Agent` `自动化` `开发工具` `配置管理`

# steve

集中管理 Claude Code 智能体配置、钩子、命令、技能和模板的统一仓库。

## 项目状态

| 指标 | 数值 |
| --- | --- |
| **组件数量** | 共 377 个（137 个智能体、97 个命令、57 个技能、59 个钩子、27 个模板） |
| **测试套件** | 415 个测试全部通过 |
| **覆盖率** | 82.5% |
| **Python** | 3.10+ |

## 概述

本仓库提供了一套组织良好的 Claude Code 可复用组件集合，包括：

- **智能体（Agents）** - 按领域和专业方向组织的子智能体配置
- **钩子（Hooks）** - 用于分析、守卫、工作流和生命周期事件的 Claude 钩子
- **命令（Commands）** - 适用于各种开发工作流的斜杠命令
- **技能（Skills）** - 附带资源包的可复用技能
- **规则（Rules）** - 语言和格式专用的编码规范
- **模板（Templates）** - 用于创建新组件的脚手架模板

## 内容导览

### 核心模块

| 模块 | 描述 | 位置 |
| --- | --- | --- |
| [智能体](steve/agents/) | 按领域划分的子智能体配置 | `steve/agents/` |
| [命令](steve/commands/) | 工作流斜杠命令 | `steve/commands/` |
| [技能](steve/skills/) | 可复用领域知识包 | `steve/skills/` |
| [钩子](steve/hooks/) | 事件驱动自动化 | `steve/hooks/` |
| [模板](steve/templates/) | 组件脚手架 | `steve/templates/` |
| [规则](steve/rules/) | 语言专用编码规范 | `steve/rules/` |
| [辅助工具](steve/helpers/) | Python 工具模块 | `steve/helpers/` |

### 文档

| 文档 | 描述 |
| --- | --- |
| [快速入门](docs/GETTING_STARTED.md) | 快速上手指南 |
| [安装说明](docs/INSTALLATION.md) | 详细安装步骤 |
| [架构设计](docs/ARCHITECTURE.md) | 系统设计说明 |
| [开发指南](docs/DEVELOPMENT.md) | 开发工作流 |
| [使用智能体](docs/USING_AGENTS.md) | 智能体使用指南 |
| [使用命令](docs/USING_COMMANDS.md) | 命令使用指南 |
| [使用技能](docs/USING_SKILLS.md) | 技能使用指南 |
| [使用钩子](docs/USING_HOOKS.md) | 钩子使用指南 |
| [贡献指南](docs/CONTRIBUTING.md) | 贡献规范 |
| [脚本参考](docs/SCRIPTS_REFERENCE.md) | 脚本文档 |
| [常见问题](docs/FAQ.md) | 常见问题解答 |

## 仓库结构

```
steve/
├── agents/              # 子智能体配置
│   ├── core/           # 核心系统智能体
│   ├── development/    # 开发工作流智能体
│   ├── code-quality/   # 代码质量与审查智能体
│   ├── expert-advisors/# 领域专家顾问
│   └── ...             # 更多专业领域
│
├── hooks/               # Claude 钩子
│   ├── analyzers/      # 代码分析钩子
│   ├── guards/         # 守卫钩子（提交前检查）
│   ├── workflows/      # 工作流自动化钩子
│   ├── lifecycle/      # 生命周期事件钩子
│   └── context/        # 上下文管理钩子
│
├── commands/            # 斜杠命令
│   ├── _team/          # 团队协作命令
│   ├── agents/         # 智能体管理命令
│   ├── git/            # Git 工作流命令
│   ├── dev/            # 开发命令
│   └── ...             # 更多命令分类
│
├── skills/              # 可复用技能
│   ├── skill-name/     # 每个技能独立目录
│   │   ├── SKILL.md    # 技能主定义文件
│   │   ├── references/ # 文档参考资料
│   │   ├── scripts/    # 可执行代码
│   │   └── assets/     # 输出文件
│   └── ...
│
├── rules/               # 语言专用规则
│   ├── python.md
│   ├── typescript.md
│   ├── shell.md
│   └── ...
│
├── templates/           # 组件模板
│   ├── AGENT_PLAYBOOK.template.md
│   ├── AGENT_SKILL.template.md
│   ├── SLASH_COMMAND.template.md
│   └── ...
│
├── helpers/             # Python 辅助模块
│   ├── context_monitor.py
│   ├── debug_rotation.py
│   ├── history_archival.py
│   └── ...
│
└── scripts/             # Python 管理脚本
    ├── build_index.py
    ├── install_component.py
    ├── list_components.py
    └── ...
```

## 组件组织方式

### 领域/专业方向层级结构

组件按领域和专业方向组织，以实现：

- **易于发现** - 按领域查找组件
- **逻辑分组** - 相关组件集中存放
- **可扩展性** - 添加新领域无需重构

### 命名规范

- **智能体**：`kebab-case`（如 `code-reviewer`、`dependency-manager`）
- **技能**：`kebab-case`（如 `code-context-finder`、`tdd-pytest`）
- **命令**：`kebab-case.md`（如 `create-subagent.md`）
- **钩子**：`kebab-case.py` 与 `kebab-case.md` 成对出现

## 快速开始

### 安装

```bash
# 克隆仓库
git clone https://github.com/joe/steve.git
cd steve

# 安装依赖
uv sync

# 构建组件索引
uv run scripts/build_index.py

# 运行测试
uv run pytest
```

```bash
# 索引
make run-index                              # 构建索引
make run-index ARGS="--verbose"             # 带选项构建

# 列表
make run-list                               # 列出全部
make run-list ARGS="--type agent"           # 按类型筛选

# 安装
make run-install ARGS="python-pro"          # 安装组件

# 发布
make run-publish                            # 发布全部
make run-publish ARGS="steve/agents/core/*.md"  # 通配符匹配
make run-publish ARGS="steve/agents/core/example-agent.md"  # 单个文件

# 密钥检测
make run-secrets ARGS="--scan"              # 扫描
make run-secrets ARGS="--baseline"          # 建立基线

# 元数据
make run-metadata ARGS="steve/agents/core/example-agent.md"
make run-metadata ARGS="steve/agents/core/*.md"  # 通配符匹配
make run-metadata ARGS="steve/agents/core/*.md --gist-url https://..."  # 带选项

# 批量元数据
make run-batch-metadata ARGS='steve/agents --dry-run'
make run-batch-metadata ARGS='steve/agents --key version 1.0.1'
make run-batch-metadata ARGS='steve/agents --key author "Joseph OBrien" --key status unpublished --key updated 2025-12-23 --key version 1.0.1 --dry-run'
make run-batch-metadata ARGS='steve/agents/core --pattern "*.md" --key category core'
make run-batch-metadata ARGS='steve/skills --pattern "**/SKILL.md" --key type skill'
```

### 使用组件

```bash
# 列出可用组件
uv run scripts/list_components.py

# 搜索特定组件
uv run scripts/list_components.py --search "code review"

# 安装某个组件
uv run scripts/install_component.py code-reviewer
```

### 创建新组件

1. 使用 `steve/templates/` 中的模板
2. 遵循命名规范（kebab-case）
3. 在适用处添加 YAML 前置元数据
4. 为复杂组件添加 README.md

## 文件格式

### 智能体文件

```yaml
---
name: agent-name
description: 面向动作的描述
tools: Read, Write, Grep
model: sonnet
color: cyan
skills: skill1, skill2
---
# 用途
---
## 使用说明
```

### 技能文件

```yaml
---
name: skill-name
description: 第三人称描述
---
# 技能标题
```

## 贡献指南

1. 遵循领域/专业方向的目录结构
2. 使用 kebab-case 命名规范
3. 在适用处添加 YAML 前置元数据
4. 为复杂组件添加 README.md 文件
5. 提交前运行密钥检测（参见安全章节）

## 安全

- **密钥检测**：通过 `.pre-commit-config.yaml` 配置
- **敏感文件**：通过 `.gitignore` 排除
- **公开仓库**：确保不提交任何密钥信息

## 脚本参考

| 脚本 | 描述 |
| --- | --- |
| `build_index.py` | 从仓库构建组件索引 |
| `list_components.py` | 列出并搜索组件 |
| `install_component.py` | 将组件安装到 Claude Code |
| `install_from_gist.py` | 从 GitHub Gist 安装 |
| `publish_to_gist.py` | 将组件发布到 Gist |
| `publish_registry.py` | 将注册表发布到 Gist |
| `add_metadata.py` | 更新组件前置元数据 |
| `detect_secrets.py` | 扫描代码库中的密钥 |
| `python_to_markdown.py` | 将 Python 转换为 Markdown |

## 文档

- [快速入门](docs/GETTING_STARTED.md)
- [架构设计](docs/ARCHITECTURE.md)
- [开发指南](docs/DEVELOPMENT.md)
- [贡献指南](docs/CONTRIBUTING.md)
- [脚本参考](docs/SCRIPTS_REFERENCE.md)
- [常见问题](docs/FAQ.md)

Claude Code 专属配置请参阅 `CLAUDE.md`，完整文档请查看 `docs/` 目录。