Monday Morning, 9:07 AM
It is Monday morning. A new engineer joins your team. Her name is Mei. She opens Slack, and there are 47 unread channels. Someone has pinned a Google Doc titled "Onboarding Guide (Updated Feb 2025)" -- fourteen months ago. She clicks it. The first link points to a wiki page that no longer exists. The second link opens a Jira board for a project that was decommissioned last quarter. The third link works but describes a deployment process that changed six months ago.
By noon, Mei has messaged four different people asking where to find things. Three of them sent slightly different answers. One of them forwarded an email thread from 2024 with the subject line "RE: RE: FWD: new hire setup notes (FINAL v2)."
This is not a people problem. It is a knowledge problem. The information exists. It is scattered across Notion pages, Slack bookmarks, Google Docs, and the memories of people who have been around long enough to know which wiki pages are lies. No single person has time to assemble a fresh, accurate, role-specific guide for every new hire. So everyone gets the same stale document, and the real onboarding happens through interruptions.
There is a better way. And it starts with a file called CLAUDE.md.
The Idea: Company Knowledge as Code
Think of onboarding knowledge like a library. A large, disorganized library where books are shelved randomly and the catalog was last updated two years ago. When a new person walks in, you hand them a photocopied map from 2024 and wish them luck.
What if the library had a living index? One that knew every shelf, every book, and could instantly assemble a reading list tailored to a specific person -- their role, their team, the tools they will actually use.
That is what CLAUDE.md becomes. It is a plain text file that sits in your project root and tells AI agents everything they need to know about your organization. Not everything about the world -- just the things your code and your tools cannot reveal on their own. When your company's onboarding knowledge lives in this file, generating a personalized guide becomes a ten-second operation, not a four-hour task.
Anthropic's own documentation shows a use case: "Create new hire onboarding guides." You paste company info into a chat, and Claude produces a welcome document. That works. But it is a one-shot interaction. The company info lives in your clipboard, not in your system. Every time you generate a guide, you re-paste, re-explain, re-format.
We can do better. We can make the knowledge permanent, the generation automatic, and the output tailored per person.
Architecture: Three Layers
The system has three layers. Each one solves a different problem.
Layer 1: CLAUDE.md -- the permanent knowledge base. This encodes what does not change between hires. Your tech stack. Your communication norms. Your team structure. Your security policies. It loads into every Claude Code session automatically, so the agent always knows the organizational context.
Layer 2: A Skill file -- the onboarding template. A Skill is a markdown file that activates on demand, not on every session. It defines the structure of your onboarding guide: what sections to include, what tone to use, what format to output. Think of it as a recipe. CLAUDE.md provides the ingredients. The Skill provides the cooking instructions.
Layer 3: MCP servers -- live data from HR systems. MCP stands for Model Context Protocol. It is a standard way for AI agents to connect to external tools -- think of MCP servers as bridges between your terminal and the outside world. An MCP server can pull the new hire's role, team, start date, and manager from your HR system (BambooHR, Rippling, or even a Google Sheet). No copy-pasting. The data flows in automatically.
Layer 1: Encoding Company Knowledge in CLAUDE.md
Your project-level CLAUDE.md should already exist if you use Claude Code. If it does not, see the CLAUDE.md Writing Guide for the full walkthrough. Here, we add an onboarding-specific section.
The key principle: only include information the agent cannot find by reading your codebase. Team names, Slack channels, tool access procedures, security requirements -- these are not in your package.json.
## Onboarding Context
### Team Structure
- Engineering: backend (Python/FastAPI), frontend (React/Next.js), platform (Terraform/K8s)
- Product: PM + designer pairs per squad
- Security: all new hires complete security training in Week 1 via KnowBe4
### Communication
- Slack: #general, #engineering, #deployments, #incidents
- Each team has a private channel: #team-backend, #team-frontend, #team-platform
- Standups: async in Slack threads, daily by 10 AM local time
- All-hands: Thursdays 2 PM UTC on Google Meet
### Tools & Access
- Code: GitHub (org: your-company), branch protection on main
- CI/CD: GitHub Actions, deploys via ArgoCD
- Monitoring: Datadog (request access via IT ticket)
- Docs: Notion workspace (auto-provisioned on first SSO login)
- Secrets: 1Password Teams (IT provisions on Day 1)
### Repositories
- your-company/api -- backend services (Python, FastAPI)
- your-company/web -- frontend app (Next.js 15, TypeScript)
- your-company/infra -- Terraform configs, Helm charts
- your-company/docs -- internal documentation site (Astro)
### First Week Milestones
- Day 1: laptop setup, SSO login, Slack introductions, 1:1 with manager
- Day 2: dev environment running locally, first PR (typo fix or README update)
- Day 3: shadow a deployment, read incident runbook
- Day 5: present a 5-minute "what I learned" to the team
That is about 35 lines. Lean enough to load on every session without burning context tokens. Rich enough that the agent can produce a guide without asking follow-up questions.
Notice what is not here: detailed setup instructions for each repo (those belong in each repo's own README), HR benefits information (that comes from the MCP layer), or anything that changes per hire (that is what the Skill handles).
Layer 2: The Onboarding Skill
A Skill file lives in .claude/skills/ and activates when the agent needs it. For onboarding, create .claude/skills/generate-onboarding-guide.md:
# Skill: Generate Onboarding Guide
## Trigger
When asked to generate an onboarding guide, welcome doc, or new hire document.
## Inputs Required
- New hire name
- Role (e.g., "Senior Backend Engineer")
- Team (e.g., "Platform")
- Start date
- Manager name
- Any role-specific notes (optional)
## Output Format
Generate a markdown document with these sections:
1. **Welcome** -- personal greeting, team intro, manager intro
2. **Your First Week** -- day-by-day schedule based on First Week Milestones in CLAUDE.md, customized for role
3. **Tools & Access** -- only the tools relevant to this role/team, with setup steps
4. **Key Repositories** -- only the repos this person will work in, with a one-line description of each
5. **Communication** -- relevant Slack channels (team-specific + general), meeting schedule
6. **Key Contacts** -- manager, team lead, buddy (if provided), IT support, security contact
7. **Learning Resources** -- internal docs, architecture decision records, relevant past incident postmortems
8. **FAQ** -- common questions for this role, pulled from historical onboarding feedback
## Tone
Warm but efficient. The reader is smart and anxious. Reduce uncertainty. Every link must be real and current.
## Output Filename
`onboarding-guide-{name}-{date}.md` in the `onboarding/` directory.
The Skill is a recipe card. It does not contain the ingredients -- those come from CLAUDE.md and MCP. It just tells the agent how to combine them.
Layer 3: MCP for Live HR Data
If your company uses an HR platform with an API, you can wire it in via MCP so the agent pulls new hire details automatically. No manual input needed.
Here is a configuration for a generic HR API MCP server in .mcp.json:
{
"mcpServers": {
"hr-system": {
"command": "node",
"args": ["./mcp-servers/hr-bridge/index.js"],
"env": {
"HR_API_BASE": "https://api.bamboohr.com/api/gateway.php/yourcompany/v1",
"HR_API_KEY": "${BAMBOOHR_API_KEY}"
}
}
}
}
The MCP server exposes tools like get_new_hires_this_week, get_employee_details, and get_team_members. When you ask the agent to generate an onboarding guide, it calls these tools to fetch the hire's role, team, manager, and start date -- then feeds that into the Skill.
If you do not have an HR API, the fallback is simple: pass the details as command arguments. The MCP layer is an optimization, not a requirement.
Running It
With all three layers in place, the generation command is one line:
claude "Generate an onboarding guide for Mei Chen, Senior Backend Engineer,
Platform team, starting 2026-03-24, reporting to James Wu"
The agent reads CLAUDE.md for company context, activates the onboarding Skill for structure, and produces a markdown file in onboarding/onboarding-guide-mei-chen-2026-03-24.md.
If MCP is configured, you can go even shorter:
claude "Generate onboarding guides for all new hires starting next Monday"
The agent queries the HR system, gets the list, and generates one guide per person. Each guide is tailored: a backend engineer's guide highlights the API repo, Python tooling, and FastAPI conventions. A frontend engineer's guide highlights the web repo, React patterns, and design system. A platform engineer's guide highlights the infra repo, Terraform workflow, and incident response procedures.
Converting to PDF
Markdown is great for version control. But HR might want a PDF to email on Day 1. Pandoc handles this:
pandoc onboarding/onboarding-guide-mei-chen-2026-03-24.md \
-o onboarding/onboarding-guide-mei-chen-2026-03-24.pdf \
--pdf-engine=weasyprint \
-V margin-top=2cm -V margin-bottom=2cm
Or let the agent do it. Add a line to the Skill:
## Post-Generation
After generating the markdown guide, also produce a PDF version using Pandoc.
Now claude "generate onboarding guide for Mei Chen..." outputs both files.
Version Control: The Hidden Advantage
Here is something the chat-based approach cannot do: version control.
Every generated guide lives in your repo as a markdown file. When your team structure changes -- a new Slack channel, a deprecated tool, a different deployment process -- you update CLAUDE.md. The next guide generated will reflect those changes automatically.
But you also have a history. git log onboarding/ shows every guide ever generated. git diff between two guides for the same role, three months apart, shows exactly what changed in your onboarding process. This is documentation that writes itself.
If you manage multiple onboarding projects simultaneously -- say, a batch of five new hires starting on the same Monday -- each guide can live in its own workspace. This is where a terminal workspace tool becomes genuinely useful: one pane per guide, each running its own generation command, all visible at once.
What Makes This Better Than a Google Doc
The comparison is not about AI versus no-AI. It is about architecture.
A Google Doc is a snapshot. The moment someone writes it, it starts decaying. Links break. Tools change. Teams reorganize. Nobody's job is to keep the onboarding doc updated, so nobody does.
This system has three properties that a Google Doc lacks:
It is compositional. Company knowledge (CLAUDE.md), guide structure (Skill), and live data (MCP) are separate layers. You update each one independently. A change to your team structure updates one section of CLAUDE.md. The Skill and MCP layer do not need to change.
It is personalized by default. There is no "generic" output. Every guide is role-specific because the agent reads the role and filters accordingly. A backend engineer does not see frontend tooling instructions. A designer does not see Terraform setup.
It is version-controlled. Every guide is a file in a repo. Changes are tracked. History is auditable. You can diff, review, and roll back.
Getting Started
If you want to try this today, start small:
- Add the onboarding section to your existing CLAUDE.md. Ten lines of team structure, tools, and channels.
- Create the Skill file in
.claude/skills/. Copy the template from this article and adjust the sections. - Run the command with one real new hire's details.
Skip the MCP layer for now. You can add it later when the value is proven. The first two layers alone -- permanent knowledge plus structured template -- already eliminate the "stale Google Doc" problem.
The goal is not to automate away the human parts of onboarding. The first coffee with the team lead, the hallway conversations, the "let me show you how we actually do this" moments -- those matter. The goal is to automate the mechanical parts: assembling the right links, the right channels, the right repos, the right contacts, for the right person. So that when Mei opens her onboarding guide on Monday morning, every single link works, and the document was written specifically for her.
That is a better first day.