What it does
Your team does the same kinds of work over and over, and each person explains it to the agent from scratch, in their own way. TeamHandbook is an open source plugin for Claude Code, an add-on that gives the agent new commands, and it turns that repeated work into a skill. A skill is a short written instruction that tells the agent how to do one job. The plugin reads your repository's git history for the work that touches the same files the same way time after time and drafts a skill for the one you pick. The draft waits in review for your decision. Share it and a merge request opens on the team repo, so someone on the team reviews it before it goes in. Once someone merges that, everyone on the team has the skill at their next session.
Install
Requires Claude Code 2.1 or newer and Node.js 22 or newer. Licensed Apache-2.0.
One person does this, once.
/plugin marketplace add AhmetErenLapanta/TeamHandbook
/plugin install handbook@teamhandbook
Choose "Install for you (user scope)" when Claude Code asks. Project scope installs it for everyone who clones the repo.
Restart Claude Code so the hooks, the scripts the plugin runs at set points in a session, load. Then:
/handbook:init
Give it an empty git repository or let it create one. The output ends with the message you send to your team.
If your team already has one, run the same two commands and restart. Then:
/handbook:join <team-repo-url>
It prints two more commands for you to run. They bring your team's merged skills to this machine.
/plugin marketplace add <team-repo-url>
/plugin install <team-plugin-name>@<team-plugin-name>
How a skill gets made
/handbook:minereads the git history and lists the work the repository keeps repeating: the files each one touches, how often, and by how many people. Listing makes no model call./handbook:mine draft 1then writes a draft for the one you picked, using your ownclaudeCLI.- The draft carries a skeleton of the steps and the file map the history measured. What git cannot see, like why a job is done that way or a check someone runs by hand, stays as an open question.
/handbook:reviewshows you the draft and what it was written from, because a model can write something that looks right and is wrong. You answer the open questions, then choose where it goes. Sharing with the team opens a merge request on the team repository. Adding it to the project commits it once you approve the message.- When someone merges that request, the team plugin's version goes up and Claude Code refreshes every teammate's copy. Nobody installs anything by hand.
A draft sends only the screened evidence for the one workflow you picked to your own claude CLI. There is no bundled key and no telemetry.
Commands
| Command | What it does |
|---|---|
/handbook:mine | Lists the work this repo keeps repeating. draft <n> turns one into a draft skill. Listing sends nothing. |
/handbook:review | Keep, add to the project, share, edit or reject each draft. Nothing TeamHandbook wrote ships without this. |
/handbook:share | Pick which of this machine's skills, MCP servers (connections that give the agent extra tools) and slash commands (commands like the ones in this table) the team gets. |
/handbook:init | Scaffolds the team repo and prints the message your team needs. |
/handbook:init --upgrade | Updates an existing team repo's scaffold, file by file, diff shown. |
/handbook:join <url> | Points this machine at an existing team handbook. |
/handbook:status | Shows the drafts waiting for review, how often each skill was used, and your settings. |
/handbook:demo | Walks the whole path on a scratch repo, with no model call unless you ask. |
/handbook:learn | Captures one thing from this session as a skill. Off by default, you turn it on in ~/.teamhandbook/config.json. |
/handbook:doctor | Checks node, the claude CLI, hooks, config and the team repo. |
/handbook:leave | Drops the team target and goes back to solo. Deletes no skills. |
Why you might not want it
- You work alone. It still runs, but the payoff is other people reading a skill for work they also do.
- A draft is a start. Expect open questions, and answer them before you approve.
- A young repository has nothing to find. It takes several past jobs touching the same files before the pattern shows up. Until then, an empty list is the right answer.
- The secret screen is pattern matching. A secret in a format it does not know can get through, so read every draft before approving it.
- A private repository needs every teammate to sign in once, in their own terminal. The plugin cannot do that for you.
Where it is used
I've trained teams on working with agents at the companies I've worked with. Some of those teams use Claude Code with TeamHandbook today, and the session format on the work with me page took shape with them, in real code. If you want a skill repo for your own team, we set it up together and pull the first drafts from the work your repository already repeats.
Contribute
The code is on GitHub: AhmetErenLapanta/TeamHandbook. To contribute with an agent, start at AI_CONTRIBUTING.md, which says what to read first and what your agent may touch at each step.
Ten issues labeled good first agent task are set aside for a first contribution. You do one with your own Claude Code and open a merge request, which GitHub calls a pull request. When I merge it, it stays in the repo under your name.