project-butler

1. 基本信息

项目	内容
名称	project-butler
作者/维护者	James Shi（GitHub: JamesShi96，个人开发者）
来源链接	https://github.com/JamesShi96/project-butler
许可证	MIT License
GitHub Stars	296（GitHub API）
Forks	11（GitHub API）
最新版本	v1.7.3（2026-07-10，见仓库 UPDATE_LOG.md；GitHub Release 标签最新为 v1.4.0，此后版本仅记录于变更日志未打 Release 标签）
安装方式	一条 `git clone` 命令，见第 10 章

2. 功能介绍与亮点

project-butler 让 Claude Code 等编码 agent 在项目里维护一套纯 Markdown 记忆栈，覆盖决策、进度、文件规则与版本历史七类文件：CLAUDE.md（项目宪法）、PROJECT.md（项目 wiki）、STRUCTURE.md（文件组织规则）、UPDATE_LOG.md（里程碑变更日志）、DOCS.md（文档索引）、session-handoff.md（会话交接）、TODO.md（任务清单）。

日常只需四个自然语言口令：

/project-butler：首次初始化或升级记忆栈
end session：保存进度、刷新下一步计划、沉淀重要决策
continue：新会话直接续接上次进度，无需重新解释项目
status：查看项目当前状态与建议的下一步

进阶命令还包括：continue full context（长时间中断后完整回顾项目轨迹）、review claude（审查候选规则后再写入项目宪法）、sync wiki（强制刷新项目 wiki）、organize files（依据 STRUCTURE.md 整理项目文件）、change language（中英文/双语切换）、normal/full close（按项目画像分级收尾）。

亮点：自带每日一次的版本新鲜度检查，落后上游时通过交互式提示征得用户同意后才执行更新；README 提供中英双语版本；三个月内保持约每周一次的版本迭代节奏（v1.0.0 到 v1.7.3）；完全免费，不依赖任何数据库或云端服务。

3. 适用场景

所属分类：元技能与 Agent 增强

需要让 Claude Code 等编码 agent 跨会话记住项目架构、决策与进度、避免每次新会话重新解释背景的开发者；在 Claude Code、Cursor、Codex 之间切换、希望有一套共享记忆文件的团队；长期维护的项目希望有版本化的变更记录与文档归档习惯的团队。

4. 跨 Agent 兼容性

Agent	结论	依据
Claude Code	✅ 原生支持	官方 skill，`git clone` 到 `~/.claude/skills/` 后通过 SKILL.md 原生触发全部命令
Codex	⚠️ 需适配	官方文档说明可在初始化阶段生成 `AGENTS.md` 指向同一套记忆文件，README 原文称其为 “best-effort” 集成，非原生 skill 机制
OpenClaw	❓ 未验证	抓取到的材料未提及
Hermes Agent	❓ 未验证	抓取到的材料未提及

5. 推荐理由

“每次开新会话都要重新给 AI 解释一遍项目背景”是几乎所有长期用编码 agent 的人都遇到过的问题。project-butler 把这个问题浓缩成四个日常口令，背后是一套结构化的纯 Markdown 文件栈——不依赖数据库或外部服务，产出即是可读文件，天然可以被其他工具复用。安装只需一条命令，近三个月保持活跃迭代，适合希望降低会话间上下文损耗、又不想引入额外服务依赖的开发者。

6. 评分

维度	分数	说明
受欢迎程度	6	GitHub 296 stars / 11 forks，仓库创建于 2026 年 4 月，三个月内持续积累关注；目前主要通过 GitHub 自然发现，未见第三方平台的独立报道
可用性	9	一条 `git clone` 命令即可安装；README 提供中英双语文档与完整命令示例；最近一次提交为 2026-07-10（约两周前），保持高频迭代；完全免费无外部依赖
安全性	8	见下方检查清单

安全检查清单：

① Shell 命令执行：有——仅两类：每日一次的 git fetch 版本检查（用户在交互提示中确认后才会执行 git pull），以及“整理文件”功能对项目内文件的移动/重命名（四阶段流程需用户确认执行计划后才落地）——权限范围与用途均有文档说明，不扣分
② 联网外发：仅限——每日一次 git fetch 访问技能自身 GitHub 仓库以检查更新，不涉及向第三方发送数据——不扣分
③ API Key/凭据：不涉及——纯本地 Markdown 文件维护，不接触任何密钥或账号信息——不扣分
④ 可疑指令：未见——审阅 SKILL.md 全文与 scripts/check-update.sh 脚本，逻辑清晰透明，无混淆代码或隐藏指令——不扣分
⑤ 作者信誉：个人开发者，README 朴实不含营销话术，提交记录与版本号连续可信，无造假迹象——不扣分
⑥ License：MIT，条款清晰——不扣分
⑦ 维护时间：最近提交 2026-07-10，约两周前，持续活跃——不扣分

7. 跟同类 Skills 相比的优势

维度	project-butler	handoff（mattpocock/skills）	supermemory
定位	完整项目记忆栈：宪法规则 + 项目 wiki + 文件组织 + 变更日志 + 任务清单 + 会话交接	单一用途：把当前会话压缩成交接文档，供新会话或新 agent 续接	API/SDK 化的跨会话记忆与个性化基础设施，面向语义检索与多模态内容
存储形式	纯本地 Markdown 文件，无需数据库	纯本地交接文档	依赖 Supermemory 云端/自托管服务 + SDK
安装门槛	一条 `git clone` 命令	插件市场一条命令或 `npx skills` 安装	需接入 TypeScript/Python SDK 并配置服务
版本管理	自带里程碑级 `UPDATE_LOG.md` 与语义化版本号	无独立版本管理层	依赖服务端 Release/npm 版本

handoff 专注在“单次会话到下一次会话”这一个动作；project-butler 把这个动作作为四个日常命令之一，额外维护项目 wiki、文件组织规则与变更历史，覆盖面更广，代价是初始化时需要回答几个项目基本信息问题。supermemory 走的是另一条路——把记忆做成可编程的 API 与语义检索层，适合需要把记忆能力嵌入自有产品的开发者；project-butler 面向的是直接在编码会话里用命令行触发的日常项目管理，不需要额外的 SDK 或云端账号。

8. 用户评价

该技能目前在第三方平台尚无具名用户评价。在其自身代码仓库中，曾有真实用户提出 SKILL.md 文件体积过大、建议拆分为独立模块的具体意见，作者随后完成拆分并关闭了该讨论。

9. 其他补充

README 提供中英双语版本，并支持在初始化阶段选择项目记忆文件采用中文、英文或双语模式。作者在近三个月内保持约每周一次的版本发布节奏，功能已从最初的会话交接逐步扩展到文件归档、文档索引与项目画像（Profile）系统等模块。

10. 安装使用方式

Claude Code（原生）：

git clone https://github.com/JamesShi96/project-butler.git ~/.claude/skills/project-butler

安装后在项目内执行 /project-butler 完成初始化，此后用自然语言触发 end session、continue、status 等日常命令。

Cursor：初始化时选择生成 .cursor/rules/project-system.mdc，令 Cursor 读取同一套记忆文件（官方文档称为 “best-effort” 文件级集成，非原生 skill 机制）。

Codex：初始化时选择生成 AGENTS.md，指向同一套记忆文件（同为 “best-effort” 集成）。

其他能够读取项目内 Markdown 文件的 AI 编码助手，理论上也可直接读取生成的记忆文件。

安装后无需重启会话，直接执行 /project-butler 即可完成首次初始化；此后每次调用该 skill 会自动做一次（每天最多一次）版本新鲜度检查，若落后上游会通过交互提示询问是否更新。

11. 注意事项

每日自动执行的 git fetch 版本检查会导致技能目录下 git status 显示“behind origin/main”，这是设计内的正常现象，不会修改用户项目文件
“整理文件”功能会移动/重命名项目内文件，虽设有用户确认环节，首次在正式项目中使用前建议先在已提交或备份状态下验证效果
Cursor 与 Codex 的集成均为 “best-effort” 文件级方案，不具备 Claude Code 原生 skill 的完整交互能力（如自动触发、交互式确认）
OpenClaw 与 Hermes Agent 的兼容性暂无官方说明，未经验证
2026 年 6 月中旬（v1.7.0）之前安装的用户需手动执行一次 git pull，才能启用自动更新检查功能