Atlas onboard
A person has joined a team that already has a lot of material: code, pull requests, tickets, meeting transcripts and a
large amount of documentation, much of it AI-generated, so fluent but of unknown accuracy. Your job is to get them
productive quickly and leave the workspace knowledge base better than you found it, so the next person starts further ahead.
Read AGENTS.md first if it is not already in context: the trust order, grounding rules and page style there apply to
everything below. The reasoning behind the main rules, so you can handle cases this skill does not cover:
- Code is the highest source, and docs are claims. New joiners believe what they read and repeat it to the team. A doc that
sounds right but describes last year's system does more harm than no doc. So you verify before you assert.
- Gaps become questions, not guesses. "I could not find this" is useful and honest; a plausible invention is not. Put gaps on
kb/open-questions.md, with a suggested person to ask (who wrote or reviewed the code).
- A page contains only what a registered source states, with a citation. Not your reasoning, not what a system like this usually does, not a summary of your impressions. The person will repeat what they read here to the team, so a
fluent sentence with no source behind it is the most expensive thing you can write.
AGENTS.md ("Grounding") has the rules and the citation format; a script checks them and a second agent verifies the rest.
- Stop at the end of each stage. The person knows things you do not (what they care about, what they already know). Let them steer.
- Wide and shallow first, deep only where their role and first task need it. Ten shallow-but-true pages beat one deep tangent.
Step 0: Read the workspace before doing anything
- Read
atlas.config.yaml (roles, declared sources), sources/manifest.yaml and kb/index.md.
- Decide which situation you are in:
- Empty knowledge base: every page under
kb/ has status: placeholder, and the manifest has no sources. You are the first
joiner; you will build the pages as you go (stages 1-3 below say which).
- Knowledge base has content: a previous joiner or the team has been here. Follow "When the knowledge base already has
content" at the end, instead of re-investigating from scratch.
- Check the tools:
node scripts/doctor.mjs. Missing tools matter only for the sources the person actually has.
- No sources, no pages. Run
node scripts/doctor.mjs --require-sources. If it fails (nothing is registered), you may still do the intake and help register sources with the atlas-ingest skill, but write no page under kb/ until at
least one source is registered, and say so plainly. If the person has nothing to ingest yet, tell them what could be (a local clone of the team's code, exports of design docs, meeting transcripts, pull requests) and stop here. Never produce a
plausible-looking orientation from general knowledge of the domain, the team's name, or the contents of this skill.
Intake
Ask these before starting, in one message, skipping anything the person has already said, and skipping sources that are already in sources/manifest.yaml (check it first, and ask only about what is missing):
- Role: developer, tech lead, solution designer (or architect), BA or product, designer, QA, or something else.
- Background: what they already know (the domain, the tech stack, similar systems). This sets how much to explain.
- First task or area they will own, if known.
- Time available to catch up (a day? two weeks?). This decides how deep stage 3 goes.
- Sources outside the repo: Confluence, OneDrive/SharePoint, Rally or Jira, shared drives, meeting recordings, anything else.
Also ask for the paths of local clones of the team's code repositories; you cannot verify anything without the code. If the manifest already lists the repository (a member cloning a workspace the team has), do not re-ingest it (that would replace the snapshot the existing pages cite): write the clone's path into
.atlas/local.yaml (repo_paths: {<source id>: <path>}, git-ignored) and run node scripts/lint-kb.mjs to see the code citations resolve.
Once you have the role (and the first task, if they gave one), record it: node scripts/explore.mjs role <role> --first-task "<one line>". It is kept on this machine only (git-ignored, per person), and it is what lets /atlas-explore start without asking the same question again. Record what the person said, not what you infer.
For each source, follow the atlas-ingest skill (.cursor/skills/atlas-ingest/SKILL.md) so it lands in sources/normalized/
with a manifest entry. If a source cannot be reached (no access, no adapter yet), say so plainly and carry on; do not fill
the gap from imagination. Raw exports go in sources/exports/ (never committed).
Stage 1: Map the sources (keep it short)
Inventory what exists: code repos, doc sets, tickets, transcripts, PRs. Then judge how far each doc set can be trusted by
spot-checking:
- Pick a handful of specific, checkable claims in each doc set (file paths, service names, endpoints, config keys, command lines) and
see whether they exist in the code. Five to ten claims per doc set is enough to tell a reliable doc from a stale one.
- Compare the doc's last-modified date against how much the code it describes has changed since (
git log --since=<date> -- <path>).
- Docs that sound authoritative but are undated or machine-written are tier 6 in the trust order: treat their claims as claims to check.
Report which docs are worth reading, which are stale, which to ignore, and what could not be accessed. Record each verdict with
node scripts/ingest.mjs mark <source-id> --reliability reliable|mixed|stale|unverified --note "<what you checked>", and
file every contradiction you found as a finding (node scripts/findings.mjs new ...: what the doc says and what the code does, each side cited with a citation from node scripts/cite.mjs, never a line number typed from memory; kb/doc-vs-code.md is generated from these and never edited by hand). A person decides whether the doc is stale or the code is unfinished.
Stop. Present the inventory and verdicts; ask whether to continue or adjust.
Stage 2: One-page orientation, readable in ten minutes
Write kb/orientation.md (use templates/page.md, kind: overview). Every paragraph, list item and table row carries a footnote citation (find locations with node scripts/cite.mjs, copy quotes from its output, never from memory). It covers only what the sources state:
- what the product does and for whom
- the main parts and how they connect
- the two or three flows that matter most
- what the team is working on now (last 60 to 90 days of commits, PRs and tickets)
- the vocabulary heard in meetings
with one flowchart. Also create or extend kb/glossary.md (terms as the team uses them, one line each, linked to where they matter)
and kb/system/map.md (flowchart of the main parts) only if every box and arrow is named in a cited statement on the page. Vocabulary from meeting transcripts can go in the glossary as what was said ("the team says X, in the 3 Sep sync", cited with the
transcript time), not as a definition, until the code or a doc confirms it; a name or number that appears only in a transcript is a likely speech-to-text error, so confirm it elsewhere before stating it.
For "what the team is working on now", use git history and PRs first (they show what is actually active), tickets second (intent),
and transcripts last (discussion). Say which is which, citing each (the repo snapshot's commit list, a PR, a ticket export, a transcript turn). Do not summarise a direction or theme the sources do not state.
Stop. Ask whether the orientation matches the person's expectations and where they want to go deeper. Offer /atlas-explore in one line for a person who does not yet know what to ask: it plays a curious newcomer in their role, proposes the questions this system raises, and answers them from the sources. It is an offer, not a stage: the stages below still stand.
Stage 3: Depth for the role
Read role-guides.md and follow the section for the person's role. It lists, per role, what to cover, how to
gather it, and which kb/ page to write it into. Everyone also gets: the glossary, the system map, who owns what (from commit and
review history), and current priorities.
General rules for this stage:
- Prefer verifying by doing where it is safe: run local build and test commands to confirm they work. Never deploy, never migrate a
shared database, never touch shared environments.
- Every statement gets a footnote citation, defined in the page's
## Evidence section. Set verified_at (date and repo commit), cite code at that commit, and list
sources[].paths so check-stale can notice when it ages. The page's evidence: label follows from the citations (AGENTS.md, rule 5).
- What you work out rather than read (counts, rankings, "it looks like", why something was probably done) does not go on a page. Tell the person in the conversation, labelled as your reading, and put what is worth confirming on
kb/open-questions.md as a question with a person to ask.
- Write the findings into
kb/ as pages (not only into the chat) so they outlive this conversation. Use the templates, one
Mermaid diagram per page at most, of the fixed type for the page kind.
- Create
roles/<role>.md as a reading path: an ordered list of links into kb/ with one line on why each matters. Never copy
content into it. If the role already has a path, extend it only with what this person's role needs.
- Things only people know (why, what is about to change) go on
kb/open-questions.md with a suggested person to ask. A decision page states the reason only if a source records it (attributed, quoted); otherwise it says no record was found.
Work in this order and stop after each chunk the role guide defines (not after every page): the person's time budget from the
intake decides how many chunks you do now.
Stage 4: The first task (only if one was named)
Cover: the code and docs it touches; the pattern similar past changes followed (find one or two example PRs with
git log --follow or gh pr list --search, and say what they changed); who to ask (from history and review comments); and what
could go wrong (fragile areas, coupling, hidden dependencies, tests that cover it and tests that do not). Keep this in the conversation unless
parts are useful to everyone, in which case put those parts in the relevant kb/ page.
Before anything is proposed: verify
You wrote these pages, so you cannot check them. For every page you added or changed (including open-questions and glossary entries; findings are checked by the linter), run the atlas-verify skill: a separate agent checks each statement and diagram element against the
cited text, and whatever is not supported is removed or becomes a question. Do this after each stage's pages are written, before presenting them as ready or offering them for commit. If you cannot start a separate agent, say so and leave the pages unverified; their banner then says
"second-agent check: not done". Never tell the person a page is verified, or reviewed by a human, beyond what its banner says.
After the walk-through: questions and answers
If the person does not know what to ask, point them to /atlas-explore. Otherwise stay available for questions in Q&A mode: answer only from the sources, with citations; say "the sources do not say" when they do not, and add the question to kb/open-questions.md; mark general background as such and keep it out of statements about the team's system
(AGENTS.md, rule 9). Write anything new back to the knowledge base (the atlas-ask skill describes how). If the person asks to be tested, ask five questions about what they should know by now,
drawn from the pages you built, one at a time, then correct their answers with references (file paths or page links). Do not hint
at answers beforehand, and say when an answer is genuinely uncertain in the knowledge base rather than pretending it is settled.
When the knowledge base already has content
A previous joiner or the team has been here. The pages are an asset and also a liability if stale, so:
- Run
node scripts/check-stale.mjs and read the report. For each page the person's role would read, check what changed since its
recorded verified_at.commit (git diff --stat <commit>..HEAD -- <paths>), and update what is out of date (follow the
atlas-refresh skill for the mechanics).
- Build the role path from existing pages (
roles/<role>.md): read kb/index.md ("By role"), list what exists, and note what is
missing for this role.
- Add only what this role needs and is missing, using stage 3's role guide as a checklist rather than a script.
- Still do the intake, and still stop at the end of each stage; the stages become shorter because you are reading, not discovering.
- Do not delete other people's pages. If a page is wrong, correct it and note the correction in
CHANGELOG.md; if you cannot tell,
put the doubt on kb/open-questions.md. Pages written before citations existed (a workspace upgraded from engine 0.1) fail the linter until each statement is cited: treat them as drafts to re-cite with atlas-refresh, not as sources.
- Pages that a person has reviewed (their banner says so) are the team's most trusted content: change them only with a reason, and expect the change to need review again.
Finish
atlas-verify has passed on every page you added or changed (or you have said it could not be run).
node scripts/sync-status.mjs, node scripts/build-index.mjs then node scripts/lint-kb.mjs; fix everything it reports.
- Add entries under
## Unreleased in CHANGELOG.md for the pages you added or changed.
- Offer to put the changes on a branch (
atlas/onboard-<name>) and commit them, for a current team member to review as a pull request. The reviewer confirms pages with node scripts/review.mjs (you never run it).
Do not push or open the PR unless asked.
- Tell the person what you could not verify, what you removed or turned into questions because the sources did not support it, and what is on the open-questions list. Say which pages are still unreviewed by a human: all of them, until a teammate runs the review.
1---2name: atlas-onboard3description: Walks a new team member through catching up on the team's system, tailored to their role (developer, tech lead, solution designer or architect, BA/product, designer, QA or other), and builds that knowledge into the workspace knowledge base. Use when someone joins the team, asks to be onboarded, wants a role-specific reading path, or runs /atlas-onboard.4disable-model-invocation: true5metadata:6 source: https://skillmd.com/skills/chauthehienp3c1/atlas-onboard7---89# Atlas onboard1011A person has joined a team that already has a lot of material: code, pull requests, tickets, meeting transcripts and a12large amount of documentation, much of it AI-generated, so fluent but of unknown accuracy. Your job is to get them13productive quickly *and* leave the workspace knowledge base better than you found it, so the next person starts further ahead.1415Read `AGENTS.md` first if it is not already in context: the trust order, grounding rules and page style there apply to16everything below. The reasoning behind the main rules, so you can handle cases this skill does not cover:1718- **Code is the highest source, and docs are claims.** New joiners believe what they read and repeat it to the team. A doc that19 sounds right but describes last year's system does more harm than no doc. So you verify before you assert.20- **Gaps become questions, not guesses.** "I could not find this" is useful and honest; a plausible invention is not. Put gaps on21 `kb/open-questions.md`, with a suggested person to ask (who wrote or reviewed the code).22- **A page contains only what a registered source states, with a citation.** Not your reasoning, not what a system like this usually does, not a summary of your impressions. The person will repeat what they read here to the team, so a23 fluent sentence with no source behind it is the most expensive thing you can write. `AGENTS.md` ("Grounding") has the rules and the citation format; a script checks them and a second agent verifies the rest.24- **Stop at the end of each stage.** The person knows things you do not (what they care about, what they already know). Let them steer.25- **Wide and shallow first, deep only where their role and first task need it.** Ten shallow-but-true pages beat one deep tangent.2627## Step 0: Read the workspace before doing anything28291. Read `atlas.config.yaml` (roles, declared sources), `sources/manifest.yaml` and `kb/index.md`.302. Decide which situation you are in:31 - **Empty knowledge base**: every page under `kb/` has `status: placeholder`, and the manifest has no sources. You are the first32 joiner; you will build the pages as you go (stages 1-3 below say which).33 - **Knowledge base has content**: a previous joiner or the team has been here. Follow "When the knowledge base already has34 content" at the end, instead of re-investigating from scratch.353. Check the tools: `node scripts/doctor.mjs`. Missing tools matter only for the sources the person actually has.364. **No sources, no pages.** Run `node scripts/doctor.mjs --require-sources`. If it fails (nothing is registered), you may still do the intake and help register sources with the `atlas-ingest` skill, but **write no page under `kb/`** until at37 least one source is registered, and say so plainly. If the person has nothing to ingest yet, tell them what could be (a local clone of the team's code, exports of design docs, meeting transcripts, pull requests) and stop here. Never produce a38 plausible-looking orientation from general knowledge of the domain, the team's name, or the contents of this skill.3940## Intake4142Ask these before starting, in one message, skipping anything the person has already said, and skipping sources that are already in `sources/manifest.yaml` (check it first, and ask only about what is missing):43441. **Role**: developer, tech lead, solution designer (or architect), BA or product, designer, QA, or something else.452. **Background**: what they already know (the domain, the tech stack, similar systems). This sets how much to explain.463. **First task or area** they will own, if known.474. **Time available** to catch up (a day? two weeks?). This decides how deep stage 3 goes.485. **Sources outside the repo**: Confluence, OneDrive/SharePoint, Rally or Jira, shared drives, meeting recordings, anything else.49 Also ask for the **paths of local clones of the team's code repositories**; you cannot verify anything without the code. If the manifest already lists the repository (a member cloning a workspace the team has), do not re-ingest it (that would replace the snapshot the existing pages cite): write the clone's path into `.atlas/local.yaml` (`repo_paths: {<source id>: <path>}`, git-ignored) and run `node scripts/lint-kb.mjs` to see the code citations resolve.5051Once you have the role (and the first task, if they gave one), record it: `node scripts/explore.mjs role <role> --first-task "<one line>"`. It is kept on this machine only (git-ignored, per person), and it is what lets `/atlas-explore` start without asking the same question again. Record what the person said, not what you infer.5253For each source, follow the `atlas-ingest` skill (`.cursor/skills/atlas-ingest/SKILL.md`) so it lands in `sources/normalized/`54with a manifest entry. If a source cannot be reached (no access, no adapter yet), say so plainly and carry on; do not fill55the gap from imagination. Raw exports go in `sources/exports/` (never committed).5657## Stage 1: Map the sources (keep it short)5859Inventory what exists: code repos, doc sets, tickets, transcripts, PRs. Then judge how far each doc set can be trusted by60**spot-checking**:6162- Pick a handful of specific, checkable claims in each doc set (file paths, service names, endpoints, config keys, command lines) and63 see whether they exist in the code. Five to ten claims per doc set is enough to tell a reliable doc from a stale one.64- Compare the doc's last-modified date against how much the code it describes has changed since (`git log --since=<date> -- <path>`).65- Docs that sound authoritative but are undated or machine-written are tier 6 in the trust order: treat their claims as claims to check.6667Report which docs are worth reading, which are stale, which to ignore, and what could not be accessed. Record each verdict with68`node scripts/ingest.mjs mark <source-id> --reliability reliable|mixed|stale|unverified --note "<what you checked>"`, and69file every contradiction you found as a finding (`node scripts/findings.mjs new ...`: what the doc says and what the code does, each side cited with a citation from `node scripts/cite.mjs`, never a line number typed from memory; `kb/doc-vs-code.md` is generated from these and never edited by hand). A person decides whether the doc is stale or the code is unfinished.7071**Stop.** Present the inventory and verdicts; ask whether to continue or adjust.7273## Stage 2: One-page orientation, readable in ten minutes7475Write `kb/orientation.md` (use `templates/page.md`, `kind: overview`). Every paragraph, list item and table row carries a footnote citation (find locations with `node scripts/cite.mjs`, copy quotes from its output, never from memory). It covers only what the sources state:7677- what the product does and for whom78- the main parts and how they connect79- the two or three flows that matter most80- what the team is working on now (last 60 to 90 days of commits, PRs and tickets)81- the vocabulary heard in meetings8283with **one flowchart**. Also create or extend `kb/glossary.md` (terms as the team uses them, one line each, linked to where they matter)84and `kb/system/map.md` (flowchart of the main parts) only if every box and arrow is named in a cited statement on the page. Vocabulary from meeting transcripts can go in the glossary as what was said ("the team says X, in the 3 Sep sync", cited with the85transcript time), not as a definition, until the code or a doc confirms it; a name or number that appears only in a transcript is a likely speech-to-text error, so confirm it elsewhere before stating it.8687For "what the team is working on now", use git history and PRs first (they show what is actually active), tickets second (intent),88and transcripts last (discussion). Say which is which, citing each (the repo snapshot's commit list, a PR, a ticket export, a transcript turn). Do not summarise a direction or theme the sources do not state.8990**Stop.** Ask whether the orientation matches the person's expectations and where they want to go deeper. Offer `/atlas-explore` in one line for a person who does not yet know what to ask: it plays a curious newcomer in their role, proposes the questions this system raises, and answers them from the sources. It is an offer, not a stage: the stages below still stand.9192## Stage 3: Depth for the role9394Read [role-guides.md](role-guides.md) and follow the section for the person's role. It lists, per role, what to cover, how to95gather it, and which `kb/` page to write it into. Everyone also gets: the glossary, the system map, who owns what (from commit and96review history), and current priorities.9798General rules for this stage:99100- Prefer **verifying by doing** where it is safe: run local build and test commands to confirm they work. Never deploy, never migrate a101 shared database, never touch shared environments.102- Every statement gets a footnote citation, defined in the page's `## Evidence` section. Set `verified_at` (date and repo commit), cite code at that commit, and list103 `sources[].paths` so `check-stale` can notice when it ages. The page's `evidence:` label follows from the citations (`AGENTS.md`, rule 5).104- What you work out rather than read (counts, rankings, "it looks like", why something was probably done) does not go on a page. Tell the person in the conversation, labelled as your reading, and put what is worth confirming on105 `kb/open-questions.md` as a question with a person to ask.106- Write the findings into `kb/` as pages (not only into the chat) so they outlive this conversation. Use the templates, one107 Mermaid diagram per page at most, of the fixed type for the page kind.108- Create `roles/<role>.md` as a reading path: an ordered list of links into `kb/` with one line on why each matters. Never copy109 content into it. If the role already has a path, extend it only with what this person's role needs.110- Things only people know (why, what is about to change) go on `kb/open-questions.md` with a suggested person to ask. A decision page states the reason only if a source records it (attributed, quoted); otherwise it says no record was found.111112Work in this order and **stop after each chunk** the role guide defines (not after every page): the person's time budget from the113intake decides how many chunks you do now.114115## Stage 4: The first task (only if one was named)116117Cover: the code and docs it touches; the pattern similar past changes followed (find one or two example PRs with118`git log --follow` or `gh pr list --search`, and say what they changed); who to ask (from history and review comments); and what119could go wrong (fragile areas, coupling, hidden dependencies, tests that cover it and tests that do not). Keep this in the conversation unless120parts are useful to everyone, in which case put those parts in the relevant `kb/` page.121122## Before anything is proposed: verify123124You wrote these pages, so you cannot check them. For **every page you added or changed** (including open-questions and glossary entries; findings are checked by the linter), run the `atlas-verify` skill: a separate agent checks each statement and diagram element against the125cited text, and whatever is not supported is removed or becomes a question. Do this after each stage's pages are written, before presenting them as ready or offering them for commit. If you cannot start a separate agent, say so and leave the pages unverified; their banner then says126"second-agent check: not done". Never tell the person a page is verified, or reviewed by a human, beyond what its banner says.127128## After the walk-through: questions and answers129130If the person does not know what to ask, point them to `/atlas-explore`. Otherwise stay available for questions in Q&A mode: answer only from the sources, with citations; say "the sources do not say" when they do not, and add the question to `kb/open-questions.md`; mark general background as such and keep it out of statements about the team's system131(`AGENTS.md`, rule 9). Write anything new back to the knowledge base (the `atlas-ask` skill describes how). If the person asks to be tested, ask **five questions** about what they should know by now,132drawn from the pages you built, one at a time, then correct their answers with references (file paths or page links). Do not hint133at answers beforehand, and say when an answer is genuinely uncertain in the knowledge base rather than pretending it is settled.134135## When the knowledge base already has content136137A previous joiner or the team has been here. The pages are an asset and also a liability if stale, so:1381391. Run `node scripts/check-stale.mjs` and read the report. For each page the person's role would read, check what changed since its140 recorded `verified_at.commit` (`git diff --stat <commit>..HEAD -- <paths>`), and update what is out of date (follow the141 `atlas-refresh` skill for the mechanics).1422. Build the role path from existing pages (`roles/<role>.md`): read `kb/index.md` ("By role"), list what exists, and note what is143 missing for this role.1443. Add **only** what this role needs and is missing, using stage 3's role guide as a checklist rather than a script.1454. Still do the intake, and still stop at the end of each stage; the stages become shorter because you are reading, not discovering.1465. Do not delete other people's pages. If a page is wrong, correct it and note the correction in `CHANGELOG.md`; if you cannot tell,147 put the doubt on `kb/open-questions.md`. Pages written before citations existed (a workspace upgraded from engine 0.1) fail the linter until each statement is cited: treat them as drafts to re-cite with `atlas-refresh`, not as sources.1486. Pages that a person has reviewed (their banner says so) are the team's most trusted content: change them only with a reason, and expect the change to need review again.149150## Finish151152- `atlas-verify` has passed on every page you added or changed (or you have said it could not be run).153- `node scripts/sync-status.mjs`, `node scripts/build-index.mjs` then `node scripts/lint-kb.mjs`; fix everything it reports.154- Add entries under `## Unreleased` in `CHANGELOG.md` for the pages you added or changed.155- Offer to put the changes on a branch (`atlas/onboard-<name>`) and commit them, for a current team member to review as a pull request. The reviewer confirms pages with `node scripts/review.mjs` (you never run it).156 Do not push or open the PR unless asked.157- Tell the person what you could not verify, what you removed or turned into questions because the sources did not support it, and what is on the open-questions list. Say which pages are still unreviewed by a human: all of them, until a teammate runs the review.