# 贡献指南

## 开始之前

1. **检查是否已有相关工作。** 开始前先搜索已有的 PR 和 Issue：
   ```bash
   gh pr list --repo nanocoai/nanoclaw --search "<你的功能>"
   gh issue list --repo nanocoai/nanoclaw --search "<你的功能>"
   ```
   如果已有相关的 PR 或 Issue，请在其基础上推进，而不是重复劳动。

2. **检查理念一致性。** 阅读 [README.md 中的理念章节](README.md#philosophy)。源代码改动应仅限于 90% 以上用户都需要的功能。Skills 可以小众一些，但仍应具备超出单用户场景的通用性。

3. **一个 PR 只做一件事。** 每个 PR 只做一件事——修复一个 bug、添加一个 skill、做一项简化。不要在同一个 PR 中混杂无关的改动。

## 源代码改动

**接受：** Bug 修复、安全修复、简化、减少代码。

**不接受：** 新功能、新能力、兼容性适配、功能增强。这些应通过 skill 实现。

## Skills

NanoClaw 使用 [Claude Code skills](https://code.claude.com/docs/en/skills)——带可选附属文件的 Markdown 文件，用于教会 Claude 如何完成某项任务。NanoClaw 中有四种类型的 skill，各有不同用途。

### 为什么用 skill？

每个用户都应该拥有简洁、最小化的代码，只包含他们真正需要的功能。Skill 让用户可以有选择地为自己的 fork 添加功能，而不必继承他们不需要的功能代码。

### Skill 类型

#### 1. 功能 Skill（基于分支）

通过合并 Git 分支来为 NanoClaw 添加能力。SKILL.md 包含设置说明；实际代码位于 `skill/*` 分支上。

**位置：** `.claude/skills/`（仅在 `main` 分支上有说明文档），代码在 `skill/*` 分支

**示例：** `/add-telegram`、`/add-slack`、`/add-discord`、`/add-gmail`

**工作方式：**
1. 用户执行 `/add-telegram`
2. Claude 按照 SKILL.md 操作：fetch 并合并 `skill/telegram` 分支
3. Claude 引导完成交互式设置（环境变量、Bot 创建等）

**贡献功能 skill：**
1. Fork `nanocoai/nanoclaw`，基于 `main` 创建分支
2. 进行代码改动（新增文件、修改源码、更新 `package.json` 等）
3. 在 `.claude/skills/<name>/` 中添加 SKILL.md，包含设置说明——第一步应该是合并该分支
4. 提交 PR。我们会基于你的工作创建 `skill/<name>` 分支

参考 `/add-telegram` 作为范例。完整系统设计见 [docs/skills-as-branches.md](docs/skills-as-branches.md)。

#### 2. 工具 Skill（含代码文件）

独立的工具，在 SKILL.md 之外还附带代码文件。SKILL.md 告诉 Claude 如何安装该工具；代码位于 skill 目录本身（如 `scripts/` 子目录中）。

**位置：** `.claude/skills/<name>/`，包含附属文件

**示例：** `/claw`（Python CLI，位于 `scripts/claw`）

**与功能 skill 的关键区别：** 无需合并分支。代码是自包含在 skill 目录中的，安装时复制到目标位置。

**规范：**
- 将代码放在单独的文件中，不要内联在 SKILL.md 里
- 使用 `${CLAUDE_SKILL_DIR}` 引用 skill 目录中的文件
- SKILL.md 包含安装说明、使用文档和故障排除

#### 3. 操作 Skill（纯指令）

不涉及代码改动的流程和指南。SKILL.md 就是整个 skill——Claude 按照指令完成某项任务。

**位置：** `.claude/skills/`（在 `main` 分支上）

**示例：** `/setup`、`/debug`、`/customize`、`/update-nanoclaw`、`/update-skills`

**规范：**
- 纯指令——没有代码文件，没有分支合并
- 使用 `AskUserQuestion` 进行交互式提示
- 这些 skill 保留在 `main` 分支上，所有用户始终可用

#### 4. 容器 Skill（Agent 运行时）

在 agent 容器内部运行的 skill，而非在宿主机上运行。这些 skill 教会容器内的 agent 如何使用工具、格式化输出或执行任务。容器启动时，它们会被同步到每个 agent group 的 `.claude/skills/` 目录中。

**位置：** `container/skills/<name>/`

**示例：** `agent-browser`（网页浏览）、`capabilities`（/capabilities 命令）、`status`（/status 命令）、`slack-formatting`（Slack mrkdwn 语法）

**关键区别：** 这些 skill 不由用户在宿主机上调用。它们由容器内的 Claude Code 加载，影响 agent 的行为方式。

**规范：**
- 遵循相同的 SKILL.md + frontmatter 格式
- 使用 `allowed-tools` frontmatter 来限定工具权限范围
- 保持专注——agent 的上下文窗口由所有容器 skill 共享

### SKILL.md 格式

所有 skill 都遵循 [Claude Code skills 标准](https://code.claude.com/docs/en/skills)：

```markdown
---
name: my-skill
description: 这个 skill 做什么以及何时使用。
---

这里是说明...
```

**规则：**
- SKILL.md 保持在 **500 行以内**——将细节移到单独的参考文件中
- `name`：小写字母、数字和连字符，最多 64 个字符
- `description`：必填——Claude 据此判断何时调用该 skill
- 将代码放在单独的文件中，不要内联在 Markdown 中
- 所有可用的 frontmatter 字段见 [skills 标准](https://code.claude.com/docs/en/skills)

## 测试

在提交前，在一个全新 clone 的环境中测试你的贡献。对于 skill，要完整地跑一遍端到端流程并验证其正常工作。

## Pull Request

### 提交前

1. **关联相关 Issue。** 如果你的 PR 解决了某个未关闭的 Issue，在描述中加入 `Closes #123`，这样合并后 Issue 会自动关闭。
2. **充分测试。** 亲自运行该功能。对于 skill，在全新 clone 中测试。
3. **检查安装专属文件。** 创建 PR 前，确认 diff 中没有安装专属文件（参见 CLAUDE.md 中的 PR Hygiene 章节）。
4. **勾选正确的选项框。** 在 PR 模板中进行选择，标签会根据你的选择自动应用：

| 选项框 | 标签 |
|--------|------|
| 功能 Skill | `PR: Skill` + `PR: Feature` |
| 工具 Skill | `PR: Skill` |
| 操作/容器 Skill | `PR: Skill` |
| 修复 | `PR: Fix` |
| 简化 | `PR: Refactor` |
| 文档 | `PR: Docs` |

### PR 描述

保持简洁。删除不适用的模板章节。描述应包含：

- **是什么**——PR 添加或改动了什么
- **为什么**——动机是什么
- **如何实现**——简要说明实现方式
- **如何测试**——你做了什么来验证它能正常工作
- **如何使用**——用户如何调用（针对 skill）

不要堆砌文字。几句清晰的话比冗长的段落更好。