nanoclaw/CONTRIBUTING.zh-CN.md

贡献指南

开始之前

1. 检查是否已有相关工作。 开始前先搜索已有的 PR 和 Issue：

   gh pr list --repo nanocoai/nanoclaw --search "<你的功能>"
   gh issue list --repo nanocoai/nanoclaw --search "<你的功能>"
   

   如果已有相关的 PR 或 Issue，请在其基础上推进，而不是重复劳动。

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

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

源代码改动

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

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

Skills

NanoClaw 使用 Claude Code 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。

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 标准：

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

这里是说明...

规则：

• SKILL.md 保持在 500 行以内——将细节移到单独的参考文件中
• name：小写字母、数字和连字符，最多 64 个字符
• description：必填——Claude 据此判断何时调用该 skill
• 将代码放在单独的文件中，不要内联在 Markdown 中
• 所有可用的 frontmatter 字段见 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）

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