How to use the Project Onboarding Guide agent skill

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent how to perform a specific task. This skill's SKILL.md is the only file in its package. Its description reads: use it when you need to generate an onboarding guide for new team members joining a project.

The skill does not analyse your code from scratch. It reads a knowledge graph that was previously generated by the /understand command, which is a structured JSON map of the project's files, components, layers and suggested tour. The agent then writes a guide covering a project overview, architecture layers, key concepts, a guided tour, a file map and complexity hotspots.

Before you start: what the skill needs

The skill has specific requirements. Check them first so you are not surprised partway through.

It needs Git, because Git is used to compare the commit recorded in the graph with the current state of the repo. It also needs a knowledge graph file, either at .ua/knowledge-graph.json or at the legacy path .understand-anything/knowledge-graph.json, generated by the /understand command. If that file is missing, the skill stops and asks you to run /understand first.

The skill runs scripts. It does not use the network, according to the listing.

• Git installed and the project under version control
• A knowledge graph at .ua/knowledge-graph.json or .understand-anything/knowledge-graph.json, created by /understand
• Permission for the agent to run scripts (see safety notes below)

Install the skill from the ZIP download

Download the ZIP for this skill from the page. Then choose one of two locations. Unzip it into ~/.claude/skills/ to make the skill available across your projects. Or unzip it into a project's .claude/skills/ folder to make it available only in that project.

If you use the Claude apps instead of Claude Code, you can upload the ZIP under Settings → Capabilities → Skills.

• Personal (all projects): unzip into ~/.claude/skills/
• Single project: unzip into the project's .claude/skills/ folder
• Claude apps: upload the ZIP under Settings → Capabilities → Skills

Generate the knowledge graph first

The skill cannot work without a graph. Run the companion /understand command in your project to create the knowledge graph. Once the file exists, you can ask for the onboarding guide.

The skill checks which data directory to use: the legacy .understand-anything/ folder if it already exists, otherwise the newer .ua/ folder. You do not need to set this yourself.

Trigger the skill with a natural request

You do not need to type a special command to use the skill. Describe what you need in plain language and the agent should pick up the skill from its description. Requests that match the skill's purpose include asking for an onboarding guide for new team members, or asking for a readable overview of the project for someone joining the team.

The skill is also named understand-onboard and its instructions refer to /understand-onboard, so you can name it directly if your agent setup supports that.

• Create an onboarding guide for new hires joining this project.
• Write a readable overview of this codebase for a new developer.
• Generate a project onboarding document from the knowledge graph.

What happens when you run it

The agent first confirms the graph exists. Then it checks whether the graph is out of date. It compares the commit hash recorded in the graph with the current repo, and looks at committed and uncommitted changes to project files. If it finds changes, it warns you that the guide may omit them and suggests running /understand to refresh the graph. A hash mismatch on its own does not count as stale when the project diff is empty.

If Git metadata is missing or invalid, the skill gives a brief best-effort warning and continues. Otherwise it reads the project metadata, layers, tour and file-level nodes, and writes the guide. At the end it offers to save the guide to docs/UA_ONBOARDING.md in the project and suggests committing it for the team.

• Confirms the graph file exists
• Warns if the graph may be out of date
• Writes the six guide sections
• Offers to save the result as docs/UA_ONBOARDING.md

Safety notes: scripts and network

The skill runs scripts, including Git commands and a shell line that picks the data directory. Review what your agent is about to run if your setup asks for confirmation, and only install skills from sources you trust. The listing states that the skill does not use the network.

The skill only reads from the project folder and offers to write one markdown file. Its instructions do not describe sending the graph or your code anywhere.

• The skill runs Git and shell commands to check freshness and locate the graph.
• The listing says it uses no network access.
• Its only suggested write is docs/UA_ONBOARDING.md, and only after you agree.

Tips for a better onboarding guide

The guide is only as current as the graph. If you have changed code since the last /understand run, refresh the graph before generating the guide. Treat the output as a starting document rather than a guaranteed-accurate reference, because the skill may continue with a stale graph after showing a warning.

Reading the guide yourself before sharing it is worthwhile. Check that the tour and file map match what new hires will actually find in the repo.

• Run /understand again after significant changes.
• Read the guide before sending it to new hires.
• Commit docs/UA_ONBOARDING.md so the whole team can see it.