project-butler skill
A skill that keeps project memory in plain Markdown files: session logs, a wiki, rules, a to-do list and a note on where to resume
- 374 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Creates and updates files in the project root, including CLAUDE.md, and the organize files command moves new files according to the structure rules
- Puts session summaries into the log folder, so details of your code and decisions may end up in them
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/project-butlerDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Creates and updates files in the project root, including CLAUDE.md, and the organize files command moves new files according to the structure rules
- Puts session summaries into the log folder, so details of your code and decisions may end up in them
This is third-party code. Review the repository files before installing.
What it does
project-butler teaches Claude Code, Cursor and Codex to remember a project between sessions. The `/project-butler` command creates a set of plain Markdown files in the project root once: CLAUDE.md with rules, PROJECT.md with the current wiki, STRUCTURE.md with file placement rules, UPDATE_LOG.md with milestones, DOCS.md with a document index, session-handoff.md and TODO.md. Beside them sit a log folder for session logs and helper files in .claude. From there work runs on ordinary phrases. `end session` saves progress, refreshes next steps and records important changes. In a new session `continue` returns the context without repeated explanations, and `status` shows the state of the project and the next step. After a long break or an assistant switch, `continue full context` rebuilds the whole trajectory. Candidate rules the agent notices along the way go into a separate file and become long-term only after you review them with `review claude`. For projects with strict product, architecture or roadmap requirements, setup can create a project profile that decides which documents matter and which sections are protected, and normal or full session close update them under a bounded plan. The `organize files` and `change language` commands tidy files according to STRUCTURE.md and switch file language between English, Chinese and bilingual mode.
Who it is for. For developers who often start fresh sessions with Claude Code, Cursor or Codex and tire of re-explaining the architecture, decisions and rules every time.
Good fit when
- Every new session means re-describing the project architecture, and you want the agent to read it from files
- Decisions such as naming conventions vanish into chat history and should live next to the code
- The README and to-do list drift from reality, and you want them refreshed when a session closes
- You switch between Claude Code, Cursor and Codex and need a shared source of truth in plain files
- After a long break you need a full review of the project's trajectory with `continue full context`
Not a fit when
- The project is throwaway and fits in one session: the set of management files only adds noise
- You do not want the agent to create helper files such as PROJECT.md and session-handoff.md in the project root
- You need automatic memory with database search: everything here is Markdown with no index search
- You work in Cursor or Codex and expect the same native behavior as in Claude Code: there the skill connects through generated rules and is best-effort
Example request
/project-butler set up project memory, and at the end of the work I will say end sessionLimitations
- In Claude Code the skill works natively. For Cursor it generates `.cursor/rules/project-system.mdc`, for Codex an AGENTS.md file, and that is best-effort support mirroring the main triggers.
- Once a day the skill runs `git fetch` in its own folder and offers to update. The check follows the skill's instructions and does not always fire. The `PROJECT_BUTLER_NO_UPDATE_CHECK=1` variable turns it off.
- Rules in CLAUDE.md appear only after your review, and the agent does not make them permanent on its own.
- Documentation and triggers are partly written in Chinese, while the language of project files switches between English, Chinese and bilingual mode.
- The skill maintains many helper files, so on a small project the set can feel heavy.
How to disable. Delete the ~/.claude/skills/project-butler folder and the skill stops firing. The files it created in your project (CLAUDE.md, PROJECT.md, TODO.md, log and others) stay as ordinary files that you can keep or delete by hand.
FAQ
How do I install project-butler in Claude Code?
Run git clone https://github.com/JamesShi96/project-butler.git ~/.claude/skills/project-butler, open a project and type /project-butler. The skill asks about the project and creates the memory files. After that the phrases end session, continue and status are enough.
Which files does project-butler create?
CLAUDE.md, PROJECT.md, STRUCTURE.md, UPDATE_LOG.md, DOCS.md, session-handoff.md and TODO.md appear in the project root, plus the docs and log folders. The .claude folder holds candidates.md with candidate rules, project-profile.json, profile-pending.json and a file snapshot.
Does project-butler work in Cursor and Codex?
Yes, as best-effort support. The skill can generate `.cursor/rules/project-system.mdc` for Cursor or AGENTS.md for Codex, and they point the assistant at the same memory files. Any assistant that reads project files can use them as shared context.
How is project-butler different from a CLAUDE.md file?
CLAUDE.md here is only the top layer with stable rules that you review by hand. Under it sit a wiki of the current state, session logs, a to-do list and a resume point, and the skill refreshes them itself when a session closes.
How do I turn off the update check?
Set PROJECT_BUTLER_NO_UPDATE_CHECK=1: only the value 1 works, while 0, false or empty do not disable the check. The skill runs git fetch in its own folder once a day and asks whether to update, and it updates only with your consent.
Discussion
No questions or reviews yet.
Related
SkillsAn Obsidian vault template for Claude Code: /daily, /weekly, /monthly and /project commands link three-year goals to today's tasks
Table Skills: project-handoff
Table Skills (project-handoff)
The project-handoff skill saves goals, decisions and the next step to PROJECT_STATE.md for a fresh Codex or Claude Code session
Claude Code Toolkit (robertguss)
Claude Code Toolkit
A set of Claude Code skills and hooks: brainstorming, worker-led project leadership, a wiki, and a book pipeline.
A Claude Code plugin that catches your corrections in chat and, after review, writes them into CLAUDE.md and AGENTS.md
A Claude Code skill collects product context in Markdown and links decisions to interviews, documents and hypotheses
Ready-made Obsidian vault with Claude Code skills for projects, tasks, clients and daily reviews, started with /setup-memory.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| project-butler (this card) | no | 374 | |
| Operator Memory | no | 504 | agent memory in plain Markdown: specs, decisions and lessons |
| Citadel | no | 927 | an operating layer for Claude Code and Codex with one /do entry point and project memory |
| LLM Wiki | no | 1,510 | AI-compiled knowledge bases: topics, import and lint checks |
README in short
The README offers four basic actions and a quick install, then covers the update auto-check and why such memory is needed. It goes on with tables of basic and advanced commands, the layout of created files, tool support, the memory layers and the project profile system.
README badge
Original SKILL.md
---
name: project-butler
description: "Project memory workflow for init/upgrade, profile-aware setup, end session, normal/full close, file organization, document archiving, language switching, versioned update logs, rule review, status, wiki sync, and context recovery. Use for /project-butler, setup/初始化, foundation setup, profile setup, end session/收工, normal close, full close, foundation repair, organize files/整理文件, change language/切换语言, continue/接着上次, continue full context/全面回顾, review claude, sync wiki, status. Maintains project memory files. Runs version freshness check before trigger routing."
---
# Project Butler — Project Memory Stack
Initialize standardized project memory:
```
上层（稳定原则）
┌─────────────────────────────────────┐
│ CLAUDE.md（项目宪法）← 人工确认 │
│ ↑ candidates（AI 自动收集候选） │
└─────────────────────────────────────┘
↑ 抽象沉淀
中层（当前快照）
┌─────────────────────────────────────┐
│ PROJECT.md（项目 Wiki）← AI 自动同步 │
│ 概览 / 结构 / 模块状态 / 文件索引 │
│ STRUCTURE.md（文件管理规则）← AI 自动│
│ 目录规则 / 匹配条件 / 整理历史 │
│ UPDATE_LOG.md（里程碑变化）← AI 自动 │
│ DOCS.md（文档索引 + 元数据）← AI 自动 │
│ .claude/project-profile.json（画像配置）│
│ .claude/profile-pending.json（画像待处理）│
└─────────────────────────────────────┘
↑ 状态汇总
下层（事实流水）
┌────────────────────┐ ┌────────────────────┐
│ log/（会话日志） │ │ TODO.md（执行清单）│
│ raw + summaries │ │ owner/deadline/ │
│ + archive（分级） │ │ deps │
└────────────────────┘ └────────────────────┘
↓
session-handoff.md（下次接手点）
```
Core idea: bottom feeds top, top constrains bottom. Logs and TODOs are raw facts. Handoff marks the next resume point. Wiki is the current snapshot. Structure manages file organization. Docs index manages document output. Update Log records versioned milestone changes. Constitution is stable principles.
Supports 3 language modes: English (`en`), Chinese (`zh`), or bilingual. All content adapts to the selected language.
---
## Step -1: Version Freshness Check (always run first)