Team Onboarding in Claude Code

Problem: You spent three months building a custom Claude Code harness. Dozens of skills. A handful of custom slash commands. Two or three subagents. Your own usage of it is second nature. Every new teammate who tries to use it is lost inside the first hour.

Quick Win: Added in v2.1.101. Run the command once at the root of your project and it writes a full ramp-up doc based on how you actually work:

claude -p "/team-onboarding"

Claude reads your last 30 days of local usage, scans the .claude/ folder, inspects CLAUDE.md, walks the project structure, and drops a markdown file you can hand to a new teammate. No manual README. No "tribal knowledge" spreadsheet. No quarterly onboarding audit.

What /team-onboarding Actually Is

It is a built-in slash command that generates a ramp-up guide from two very different data sources. Structural data: your .claude/commands/, .claude/skills/, .claude/agents/, CLAUDE.md, configured MCP servers, sibling repos. Behavioral data: how often you ran each command in the last 30 days, which work types those commands map to, which MCP servers you touched.

The two sources are combined into one markdown doc that reads like a senior engineer writing a first-day guide for the new hire who is shadowing them.

It is not a real-time onboarding interface. It is not a chat. It runs once, writes a file, and quits. The file you get is a snapshot of how the tool has been used inside your repo.

What It Reads

Six inputs feed the guide. Every input is local. Nothing leaves your machine except the calls to Claude itself.

The usage history is the reason this feature is interesting. Any tool can list files. Very few can tell a new hire that the senior dev runs /claude-scout seven times a month and has never touched MCP. That second layer is what turns a file listing into a ramp-up doc.

What The Output Looks Like

Here is a real, unedited sample from a content-factory repo that has been in active use for a month:

# Welcome to Build This Now

## How We Use Claude

Based on speedy_devv's usage over the last 30 days:

Work Type Breakdown:
  Write Docs        █████████░░░░░░░░░░░  44%
  Build Feature     ███████░░░░░░░░░░░░░  33%
  Plan Design       ████░░░░░░░░░░░░░░░░  22%

Top Skills & Commands:
  /claude-scout     ████████████████████  7x/month
  /carousel         ██████░░░░░░░░░░░░░░  2x/month
  /compact          ██████░░░░░░░░░░░░░░  2x/month
  /claude-research  ███░░░░░░░░░░░░░░░░░  1x/month
  /resume           ███░░░░░░░░░░░░░░░░░  1x/month

Top MCP Servers:
  _None configured yet_

## Your Setup Checklist

### Codebases
- [ ] btn-content-factory (this repo, content generation pipeline)
- [ ] claude-code-seo-machine, sibling repo (blog paraphrase + SEO)
- [ ] build-kit-template, the framework itself

### MCP Servers to Activate
- [ ] _None in use yet_

### Skills to Know About
- /claude-scout: hourly scout for Anthropic/Claude Code news. Most-used
  command on the team.
- /carousel: builds an Instagram carousel via the carousel-designer +
  carousel-evaluator GAN loop.
- /blog-post: turns a carousel into a /blog/guide/ MDX page + hero image.

## Team Tips
_TODO_

## Get Started
_TODO_

Five sections come back. The header pulls the team name from CLAUDE.md. "How We Use Claude" is the behavioral layer. "Your Setup Checklist" is structural. "Team Tips" and "Get Started" are interactive placeholders the command asks you to fill in after the first run.

The bar charts are not decoration. They are shell-safe ASCII, so you can paste the file anywhere and the rhythm of the team's work is visible at a glance. A new teammate skimming it knows, in ten seconds, that this team documents more than it builds, lives in /claude-scout, and has no MCP wired up. That is better context than most onboarding decks.

How To Run It

Two ways to invoke it. Both land on the same output.

Run it headless, pipe to a file:

claude -p "/team-onboarding" > ONBOARDING.md

Or run it inside an interactive session:

/team-onboarding

The interactive version asks three follow-up questions after the first draft. What the team is called. Whether there is a good first task for the new hire. What team tips you want written down that are not already in CLAUDE.md. Answer them and the _TODO_ sections get filled in. Skip them and the file ships with the placeholders.

The headless version does not ask. It writes the draft as-is, _TODO_ sections and all.

Day One Versus Week One

Here is the part most people miss. The command blends structural data with behavioral data. The structural data exists on day one. The behavioral data does not.

A fresh clone of your repo with zero usage history gives you a half-filled doc. You get the setup checklist, the skills inventory, the MCP list. You do not get the work type breakdown, the frequency bars, or the signal that tells the new hire which command is most-used.

Run the command too early and the output reads like a dry file listing. Run it after a week of real work and it reads like a senior engineer wrote it for you.

The right play is not "new teammate runs it on day one." The right play is "the experienced engineer runs it on their own environment, edits the output, and hands the curated file to the new hire."

Ship It With Your Harness

If you maintain a framework, template, or internal toolkit that other people use, the command becomes a distribution feature.

Run /team-onboarding in your main dev environment. Your usage history is rich by now. You get the full behavioral layer. Edit out any personal paths you do not want to share. Commit the result to your repo as docs/how-we-use-claude-code.md. Ship it with your next release.

Your users now get something no boilerplate or starter kit has ever given them. A snapshot of how the people who built the framework actually use it day to day. Not the marketing version. Not the feature list. The real usage patterns.

Refresh it on every release. New commands you added show up automatically because you have been running them. New skills you wired in show up because the structural scan catches them. Old commands you stopped using fade out of the top list. The doc evolves with the tool, without you writing a single sentence by hand.

The same pattern works inside a company. Run it on the staff engineer's environment. Commit the output as your team's canonical "how we use Claude Code" file. Review it once a quarter. Update when it drifts.

Configuration And Control

Three knobs worth knowing about.

Output destination. Pipe the headless run anywhere you want. Into a repo file, into a team wiki, into a shared doc. The output is plain markdown with ASCII-safe bars.

Lookback window. The default is 30 days. For a senior engineer who has been in the repo for months, this is the right window. For a short project, 30 days may cover everything you ever did.

Interactive follow-ups. The interactive version asks questions. The headless version skips them. If you want to script the whole flow, use headless and fill in the _TODO_ sections by hand. If you want Claude to help you draft the team tips, use interactive.

There is also a hidden signal at the bottom of the file. An HTML comment that reads onboarding buddy mode. That is a follow-up hook. The next time a teammate opens a Claude Code session in the same repo, Claude treats itself as the onboarding buddy for that file. You hand the new hire the markdown doc and Claude Code itself. Claude walks them through the doc, one section at a time, answering questions along the way.

Best Practices

Run it on the environment with the richest usage. The behavioral layer only pays off if the command has real data to read. Do not run it on a fresh clone. Run it on the laptop where the work actually happens.

Edit before you ship. The first draft has personal paths, sibling repo references, and sometimes a teammate's GitHub handle baked in. Scrub these before you commit the file. Treat the output as a first draft, not a final doc.

Regenerate on every release. Set up a just onboarding or npm script. One line, one command. Re-run it when you cut a new version. The doc stays current without you touching it.

Pair it with CLAUDE.md. CLAUDE.md is your rules for the AI. The onboarding doc is your rules for the human. They complement each other. One tells Claude how to behave. The other tells the new hire how the team works.

Read the output yourself. The first time you run it, spend five minutes reading what Claude noticed about your own work. You will learn something. Most engineers do not know their own top three commands until they see the bar chart.

Next Steps

• Set up CLAUDE.md to anchor your team's rules for Claude
• Explore auto memory for per-project knowledge that Claude writes for itself
• Learn the .claude/rules/ directory for modular project instructions
• Read about custom skills to understand what your onboarding doc is inventorying
• Look at agent teams if your workflow spans multiple parallel subagents

Team onboarding closes the loop between what you built and what your team can actually use. Your harness stops being a personal cockpit and starts being a shared workbench. Run it once, hand the file to the new hire, and get back to shipping.