Team Onboarding Buddy: Claude Code Skills vs the Wiki Maze

Some teams live on a hot plate: customer support, payments and billing ops, engineering when incidents are part of the job, product and design when every launch touches a shared surface, legal and compliance when “ship it” is not a binary. Different domains, same onboarding shape. The work is high stakes and high interruption, so week one has to be right, not just busy.

Onboarding for those teams is never “read the README and go.” It is access to the right systems, a path through tooling that matches how work really flows, habits that stay safe under pressure, and knowing who to ping when something breaks.

We stopped treating that ramp like a scavenger hunt through stale wikis and shipped it as something you can run: a team-scoped Claude Code plugin made of skills, small playbooks the agent follows, with MCP checks so “connected” means verified, not hoped for.

Hypothesis

A Team Onboarding Buddy should beat the default experience: read twelve pages, miss the thirteenth, ping three people, discover your MCP tokens are wrong, and lose a week proving you are not incompetent, you are just new.

If onboarding is small, invocable skills with explicit triggers, and those skills include MCP health checks plus a real access checklist, a new hire should get to first useful work with less thrash. The skills do not replace humans. They replace the worst part of onboarding: reconstructing tribal knowledge from stale breadcrumbs.

Setup

What we built. A team-scoped plugin: four skills in one bundle, installable the same way you would ship any other Claude Code plugin to a group that should share one playbook.

Our first internal cut targeted one engineering sub-team's playbook before we framed this as a pattern anyone could clone.

Repo shape (quick and dirty). In a Claude Code plugin marketplace repo you usually get one folder per plugin: a small manifest under .claude-plugin/ and a skills/ directory full of SKILL.md playbooks. The folder name should match the plugin id in plugin.json (that becomes the /namespace:skill prefix in Claude Code). Rename team-name to whatever id you pick in plugin.json.

Examples of folder / namespace names (illustrative only): engineering, marketing, product, design, legal, finance, people-ops.

text
your-plugin-marketplace/
├── .claude-plugin/
│   └── marketplace.json          # register ./team-name (e.g. ./marketing, ./product, ./people-ops, etc.)
└── team-name/                    # e.g. marketing/, product/, people-ops/, etc.; name = plugin id in plugin.json
    ├── .claude-plugin/
    │   └── plugin.json           # plugin manifest (name, version, ...)
    └── skills/
        ├── onboarding/SKILL.md
        ├── access/SKILL.md
        ├── local-dev/SKILL.md
        └── team/SKILL.md

Why this shape. The skills are modular on purpose. Nobody wants a forty-page monolith. A new hire can pick sections like a menu instead of pretending they will read the whole handbook on day one.

The MCP angle. The access skill does something wikis are bad at. It tells the agent to verify integrations with real reads through connected tools, not to assume OAuth worked because nothing exploded yet.

The human angle. Long-form runbooks still live wherever your company keeps them. Escalation still names real humans. The goal is not autonomous HR. The goal is fewer round trips for questions the team has already answered a hundred times.

Results

What we shipped.

• A versioned, team-scoped bundle so one group can adopt the buddy without forking the whole company agent config.
• Hundreds of lines of structured guidance across the four skills: MCP verification steps, access and tooling checks, and a clear path from “green integrations” toward first safe change.

What we learned in practice (qualitative).

• The entry skill actually gets used. People do not have to remember the “right” order. The plugin encodes it.
• MCP verification turns a vague “I think I am set up” into a pass or fail list. When something is wrong, the output is actionable instead of confidently wrong.
• The team skill fills a gap most organizations leave empty: who shows up from outside the group, for what reasons, and where the sharp edges are. That is context people often learn only after they step on a rake.

How to sanity-check your own build (five minutes).

• Invoke the entry skill and confirm it routes into access, local-dev, and team flows in a sensible order.
• Run the MCP verification path and confirm failures degrade gracefully: they say what is broken and what to check next, instead of inventing green checks.

On metrics. We have strong internal signal on usability and fewer “false start” access threads. A controlled before/after (time to first local run, time to green MCP matrix, week-one ticket volume, short confidence survey) is the right next step if we want a chart in a sequel post. This write-up is the pattern and the ship story, not that chart yet.

Takeaway

Onboarding is not an information problem. It is a routing problem. You do not need more wiki pages. You need a default path that is hard to screw up, plus checks that fail loud when your tooling is not actually connected.

Packaging that path as Claude Code skills is a bet on where engineers already live (NOTE: It could be Cowork, in the case of a non-engineering team.).

Whether Claude Code or Cowork, the buddy belongs in the editor session, not on page seventeen of a PDF nobody opened.

The bundle bakes in habits that matter whenever financial correctness, access control, or customer-visible production behavior is on the line: look before you change anything (read-only checks first), exercise mutations in a safe mode (dry-run or sandbox before you touch live state), and do not solo your first production-adjacent change (pair with someone who has muscle memory).

That is not moralizing. It is how you avoid the expensive failure mode where a small onboarding shortcut becomes a customer-visible incident or a long support recovery.

Credits

Team Onboarding Buddy was a collaboration. Thanks to the team of engineers who built, reviewed, and tried it in real onboarding flows:

• Andrea Morato Dixon
• Fernando Lima
• Ryan Hamilton (yours truly)

If this pattern helps your org, please let us know!

What's Next

1. Run a small cohort study with agreed metrics so we can publish numbers, not just vibes.
2. Reuse the skeleton across the org, for other teams: same four-skill shape (onboarding, access, local-dev, team), different playbooks for both engineering and non-engineering teams.
3. Treat rosters and paths as perishable data. Point people at live chat and authoritative docs, refresh the skills when reality drifts.

Bottom line for anyone pitching this upstairs

This is not “AI replaces onboarding.” It is AI holds the checklist and verifies the wiring so humans spend time on judgment, not detective work.