What good engineering onboarding actually looks like

I ran into an issue this week, that most if not all of us software engineers run into in our careers. I was handed a codebase and asked to help push some tickets to closure ASAP.

As an old school engineer, my first step was to look for a README file and some other documentation. None of it existed. Obviously, I then tried having an LLM explain the codebase to me, but it just printed out a huge blob of text that with references to so many different files that it actually became harder to understand.

So, I decided to build something small, that could be re-used and help engineers anywhere, a Gemini CLI Agent Skill. It’s called codebase-onboarding. Most onboarding tools try to generate exhaustive documentation. That’s rarely what a new engineer needs. Good onboarding is conversational: orient first, then go deeper based on what the engineer is trying to do.

Onboarding doesn’t mean “read everything”. It’s answering four questions in order:

1. What does this project do?
2. What’s the stack?
3. Where do I look first?
4. How does a real user action flow through the code?

Most AI tools either dump the entire repository tree immediately or dive into architecture before you even understand the product. This is why codebase-onboarding focuses on orientation.

What is an Agent skill? And why not just use a Prompt?

If you’ve used Cursor, Claude Code or Gemini CLI, you’ve probably saved a “good prompt” somewhere. Prompts drift. Context gets forgotten. Every session re-invents the workflow.

A skill is different: a folder with a SKILL.md file that tells the agent how to behave, plus optional scripts, reference docs, and templates. Gemini CLI activates the skill when prompts match onboarding-style requests like: “onboard me”, “explain the codebase” or “where do I start”.

The skill doesn’t replace senior engineers, it encodes a repeatable onboarding ritual so every engineer gets the same shape of answer.

The single design decision that makes this skill usable is progressive disclosure.

It doesn’t dump entire architecture diagrams, auth deep dives, and folder maps in one message. It gives a 30-second orientation. Stops and then asks what you want next.

I split the skill into 3 levels.

Levels 2 and 3 only run when you ask. Same rhythm as a good staff engineer: “Read these 2 files. Then we’ll talk about auth”. Not a wiki dump.

What happens under the hood?

Level 1 runs a bash script before the model speaks. It emits facts — language, framework, entry point, top-level directories, file count, whether a README/tests/CI exists.

The agent summarises the README in plain English then returns a fixed Project Orientation block and three options: go deeper on architecture, deep dive a topic, or save a ONBOARDING.md file.

Level 2 loads a reference guide and names the pattern as it appears in the repo’s folders, draws layers from real modules and walks one action (eg, login) end-to-end.

Level 3 does the same for a topic you name — central files, sequence diagram, non-obvious gotchas.

Saving only happens on confirmation. Unexplored sections get a _Not yet explored_. You can commit the ONBOARDING.md and re-run the skill after refactors.

Limits

1. The scanner reads manifests, not meaning. “utils” might be your entire payments domain.
2. Dumping five topics in one prompt fights the design; treat it like a conversation.
3. Tribal knowledge in Slack/email, still needs humans; this maps code, not org history.
4. This was made for Gemini CLI today; the pattern (script + levelled SKILL.md + template) ports elsewhere.

The best onboarding I got never opened with a diagram of every layer. This skill encodes what actually works: orient fast, go deep on demand, save only when asked.

If your AI keeps writing essays when you wanted a map — you don’t need a bigger wiki. You need a 30 second tour and permission to ask for more.