The Onboarding Skill That Rewrites Itself
Stop writing wikis. Your codebase already knows, and the skill that reads it gets better every hire.
TL;DR
The conventional new-joiner ramp at a hedge fund or prop trading firm runs three to six months. Most of that time is spent reading documentation that drifted out of date the moment it was written, and pulling senior engineers off their work to translate it. A well-structured onboarding skill, pointed at a live codebase with a master repo and per-repo CLAUDE.md files, collapses the wiki-reading phase from weeks to days. It does not replace human mentorship. It replaces the parts of onboarding that should never have been human work in the first place.
The cost nobody puts in the spreadsheet
A senior engineer at a London hedge fund costs roughly £200k fully loaded. Three months to productivity is £50k of burn before they ship anything that matters. Multiply that across a team of ten hires a year and the onboarding tax is half a million pounds, before counting the senior engineer hours pulled away to walk new joiners through the codebase.
The defence of this model is that knowledge transfer is inherently slow. That was true when the only way to understand a system was to read its documentation and ask its authors. It is no longer true.
Why wikis fail at onboarding specifically
Onboarding documentation is the worst-maintained surface in any engineering organisation. It is written once, by someone leaving the team, then revised reluctantly when a new hire complains. The architecture diagrams reference services that were renamed two years ago. The “getting started” guide installs a version of the runtime that no longer ships. The list of who-owns-what points to people who left.
Every engineer reading this has had the experience of being onboarded against a wiki page and quietly suspecting that the diagram on screen has no relationship to the system in production. That suspicion is usually correct.
The reason wikis rot is structural, not cultural. Documentation lives in a different repository, on a different cadence, edited by different people, with no test that fails when it diverges from reality. A code change does not break the docs. So the docs break themselves.
The skill is the artefact
A skill is a versioned, repo-resident instruction set that an agent loads on demand. Unlike a wiki page, it is checked in alongside the code it describes. Unlike a prompt, it is reusable and reviewable. Unlike a runbook, it is executed by an agent that can read the current state of the codebase and produce answers grounded in what is actually there.
An /onboarding skill turns the new-joiner experience into a guided traversal of the live system. The agent does not paraphrase a stale diagram. It opens the actual entrypoint, follows the actual call graph, surfaces the actual configuration, and explains what it found. When the system changes, the explanation changes with it.
This is the same pattern I described in the previous post, applied to the highest-stakes documentation surface in the organisation.
Live docs are the substrate
A skill is only as good as the documentation it reads. If your CLAUDE.md files, architecture READMEs, and service boundary diagrams have rotted, the skill confidently presents rotted information. That is worse than a wiki, because the agent’s voice carries authority the wiki never had.
The fix is structural. Documentation has to live where code lives, and it has to be updated by the same act that changes the code. A code-generating skill that ships a new endpoint also updates the relevant CLAUDE.md. A refactor that renames a service also rewrites the architecture README section that references it. The test is simple: a pull request that changes behaviour without updating the doc that describes that behaviour should fail review. Make doc updates a first-class part of the change, not an afterthought.
The skill is the reader. The live docs are what it reads. Both have to work.
What the skill actually does
Rather than list benefits, here is a concrete first morning:
A new joiner clones the master repo, runs claude /onboarding, and is asked three questions: what they have worked on before, which area of the system they have been hired into, and how they prefer to learn (top-down architecture first, or bottom-up by following a single request through the stack).
The agent then opens the relevant per-repo CLAUDE.md, walks the new hire through the bounded contexts of the platform, and produces a personalised reading order across the actual code. When the hire has a question, the agent answers from the codebase rather than from memory. At the end of the first day, the agent surfaces three candidate starter tickets from the connected ticketing system, with a short rationale for why each one would be a good first task, and hands those candidates to the engineering manager for a human decision.
The session leaves two artefacts behind. A personal log file in .onboarding/<joiner>.md that belongs to the new joiner and nobody else. And a pull request, drafted by the agent against the skill itself, proposing improvements based on what went wrong during the session. Files that did not exist. Questions the skill should have pre-empted. Steps where the agent had to improvise. A human reviews the PR, the new joiner often comments on it, and the skill compounds. The first contribution most new hires make to the codebase is the review that makes the next hire’s onboarding slightly better.
What the agent does not do: assess whether the new hire has genuinely understood anything, sign off on their readiness, or assign work autonomously. Those remain human responsibilities. The agent collapses the information transfer part of onboarding. It does not pretend to replace mentorship.
The skill, in skeleton form
This is a sanitised version of the skill I use as a reference architecture. It expects a master repo with per-service CLAUDE.md files and a ticketing MCP connection. The specific tools and paths will differ in your environment.
---
name: onboarding
description: Guides a new engineer through a personalised
traversal of the live codebase, producing a reading order
grounded in the current state of the system and a shortlist
of candidate starter tickets for human approval.
---
# /onboarding
You are guiding a new engineer through their first days on
the team. Your job is to produce a personalised, codebase-
grounded ramp plan. You are not an assessor and you do not
assign work.
## Step 1: Establish context
Ask the new joiner three short questions:
1. Prior experience (languages, domains, scale)
2. Team or service area they are joining
3. Preferred learning order: top-down (architecture first)
or bottom-up (trace a single request end to end)
Wait for answers before proceeding.
## Step 2: Read the master repo
Open `/master/README.md` and the index of services. Identify
the bounded contexts most relevant to the new joiner's area.
Do not summarise from memory. Open and read the current files.
## Step 3: Produce a reading order
For the relevant services, open each per-repo CLAUDE.md and
produce a numbered reading order. For each item, include:
- The actual file path
- A one-line explanation of why this file matters
- The concept it illustrates
Reference live code only. If a file referenced in CLAUDE.md
no longer exists, surface this as a documentation defect
and continue with what is present.
## Step 4: Walk a representative request
Pick one user-facing flow in the new joiner's area. Trace it
from entrypoint to persistence, opening each file as you go.
Explain each hop in plain language. Pause for questions.
## Step 5: Surface candidate starter tickets
Query the ticketing MCP for open tickets in the new joiner's
area, filtered by:
- Label: good-first-issue OR estimated effort: small
- Status: open, unassigned
- Touches files already covered in the reading order
Return three candidates with a rationale for each. Do not
assign. Hand the list to the engineering manager for a
human decision.
## Step 6: Log the session for the new joiner
Append a short summary to `.onboarding/<joiner>.md`. This file
is the new joiner's personal reference, owned by them. It is
not a manager artefact and it is not used to assess them.
Include:
- Questions asked and answers given
- Reading order produced
- Candidate tickets surfaced
- Outstanding questions for human follow-up
The new joiner can edit, delete, or keep this file as they
choose. It belongs to them.
## Step 7: Propose improvements to the skill itself
At the end of the session, review your own transcript and
identify structural failures in the skill, not in the new
joiner. Look for:
- Files referenced in CLAUDE.md that did not exist
- Questions the new joiner asked that the skill should
have pre-empted
- Steps where you had to improvise because the skill did
not specify what to do
- Concepts the new joiner asked about more than once,
suggesting the underlying docs were unclear
Draft a pull request against this skill file with the
proposed improvements. Open the PR for human review.
Do not auto-merge.
The new joiner's first contribution to the codebase is
often a review of this PR. Each onboarding session leaves
the skill slightly better for the next one.
## What you do not do
- You do not assess understanding.
- You do not assign tickets.
- You do not paraphrase stale documentation. If a file is
missing or contradicts the code, say so.
- You do not replace the buddy. You complement them.
The maturity ladder
This skill returns value in proportion to the foundation underneath it. The honest version of the prerequisites is a ladder, not a checklist:
At the floor, you need one repo with a passable CLAUDE.md and a connected ticketing system. The skill will work, narrowly, on that repo. At the next rung, a master repo and per-service CLAUDE.md files turn the skill into a coherent tour of the platform rather than a single building. At the top, the live-docs discipline from earlier is enforced by tooling, not memory. Every code-generating skill updates the relevant CLAUDE.md as a side effect of its work. Every PR that changes behaviour without updating the corresponding doc fails review. Each new feature shipped makes the next new hire’s ramp slightly faster.
Most enterprises are at the floor. That is the work.
Where this fails
Three failure modes are worth naming. First, if the underlying CLAUDE.md files are themselves stale, the skill inherits their staleness. Garbage in, confidently presented garbage out. Second, if the ticketing MCP is connected without scope controls, the agent will happily surface tickets the new joiner should not see. Scope it to the team’s board. Third, if the skill’s self-improvement PRs are allowed to merge without human review, the skill drifts. Each session edits the skill in small ways, errors compound across sessions, and within a quarter the skill no longer reflects how the team actually wants to onboard. Human review of every improvement PR is the safeguard. The agent proposes, a human disposes.
What to do this week
Pick one team. Pick one repo. Write the /onboarding skill against that repo’s CLAUDE.md. Run it on the next new hire and the most recent one, in parallel. Compare what the agent surfaces against what the wiki said. The gap between those two is the size of the problem you have been paying for, and the size of the opportunity.
The conventional new-joiner ramp was designed for a world where the codebase could not explain itself. That world is over.
About me
I’m Ahmed El-Refee - fifteen years in financial services engineering across Credit Suisse, Daiwa, Elliott Management, and LMR Partners, building real-time risk, P&L, VaR engines, and trading systems. I’m now Co-founder and CTO of Fortius Technology, working at the intersection of production software engineering and applied AI: skills libraries, agentic coding workflows, and AI-native delivery systems for teams that take their codebases seriously.
If you’re a founder, engineering leader, or hiring manager thinking about how to get this kind of leverage in your own team - full-time, fractional, or consulting - I’d like to hear from you. Reach me on LinkedIn or at ahmed@fortius-app.com or at ahmedelrefee.com.
If this was useful, subscribe - I write about the seam between financial services engineering and applied AI, and there’s more in this series coming. Let me know what other interesting topics you’d like me to write about