Skip to content

skillDocumentation

Onboarding Guide

Builds a developer onboarding doc from the repo's actual setup, scripts, conventions and CI, so day-one questions get answered in writing.

npx workspacetemplates add onboarding-guide --tool claude-code

Writes 1 file to .claude/skills/onboarding-guide/

.claude/skills/onboarding-guide/SKILL.md26 lines · 1.5 KBFile
---
name: onboarding-guide
description: "Builds a developer onboarding doc from the repo's actual setup, scripts, conventions and CI, so day-one questions get answered in writing."
---

# Onboarding guide

Describe how this team really works, as proven by the repository.

## Steps

1. Survey the repo: top-level layout, manifests, scripts, Docker and compose files, CI workflows, linters and formatters, test setup, pre-commit hooks, CODEOWNERS and any existing docs.
2. Mine conventions from evidence. Use recent history (`git log --oneline -50`) for commit message style, branch naming and PR size. Read lint and format config for code style. Read CI for what must pass before merge.
3. Write the guide with these sections: What this system does and who uses it; Architecture in one page (main modules and how a request or job flows through them); Local setup (verified commands); Daily workflow (branch, test, lint, open PR, review, deploy); Conventions (naming, errors, logging, tests); Where things live (a table of folder to purpose); Who to ask (from CODEOWNERS only).
4. Add a "first task" walkthrough: a tiny real change such as editing a message string, taken from setup to merged.
5. Finish with Open questions, listing facts you could not find.

## Rules

- State only what you found. Cite the file for each convention.
- No org charts, no wishes, no marketing text.
- Keep it under 800 lines and link to deeper docs.

## Report

The guide path, what you verified by running it, and the open questions for the team to answer.

What it does

Onboarding docs go stale because they are written from memory. Here the agent derives the guide from evidence: package scripts, CI jobs, lint config, branch rules, the commit history and the folder structure.

The result covers a first-week path for a new engineer: set up, make a small change, get it reviewed and shipped. Parts nobody documented are listed as open questions for the team.

Example

you › Create an onboarding doc for this repo

agent › Wrote docs/onboarding.md (240 lines). Verified setup with docker compose up and npm test. Conventions came from commitlint, ESLint config and CI: conventional commits, squash merges, required checks lint, unit, e2e. Open questions: how staging deploys are approved, and who owns the billing module.

Questions

Does it invent team norms?
No. Each convention is tied to a file or to repeated history. Anything without evidence goes into the open questions list.
Should it replace our wiki?
It lives next to the code, so it changes with it. Link it from the wiki rather than copying it there.
  • API Documentation

    SkillDocumentation

    Free
  • Architecture Decision Records

    SkillDocumentation

    Free
  • Code Comments Docstrings

    SkillDocumentation

    Free
  • Design Doc Writing

    SkillDocumentation

    Free