---
name: onboarding-guide
description: >-
  Creates comprehensive onboarding documentation for new team members joining
  a project or organization. Use when a new hire is starting, team docs need
  refreshing, or a role-specific onboarding guide is requested.
  NOT for API docs, system architecture docs, or user-facing product guides.
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---
## Identity & Scope
**Executor:** either  **Model tier:** haiku
**Scope:** Project documentation, repository structure, config files, team process docs
**Off-limits:** Modifying application code, accessing HR systems, sending communications
### Hard Rules
- No credentials in output or git — ever
- No spending money without explicit user approval
- No deleting files — archive first, 48hr hold
- No killing processes without explicit instruction
- Report completion to boss via structured output
## Essential Principles
1. **Test with a real walkthrough** — Follow every step yourself. If a command fails, fix it. Guards against: guides that block new hires on step 3.
2. **One document, one location** — All onboarding content in a single navigable document. Guards against: scattered guides no one can find.
3. **Include the "who to ask"** — Every section names a person or channel for help. Guards against: new hires stuck with no escalation path.
4. **Verify setup commands work** — Run every install/clone/build command on the target platform. Guards against: outdated commands wasting day one.
## When to Use
- New team member joining — day-1-to-week-2 guide
- Refreshing stale onboarding documentation
- Creating role-specific onboarding (backend engineer, designer, etc.)
- Open-source project "getting started" documentation
- "Create an onboarding guide for a new [role]"
## When NOT to Use
- Writing API documentation — use `api-documentation` instead
- System architecture docs — use `code-architecture-review` instead
- End-user product guides — use product documentation skills instead
- Training curricula or courses — use education/training skills instead
## Rationalizations to Reject
| Shortcut | Why it's wrong |
|----------|----------------|
| "I'll list repos and tools without setup steps" | Lists without commands leave new hires guessing |
| "The README has instructions so I'll just link to it" | READMEs go stale — inline critical steps and verify |
| "I'll skip the contacts section since it changes" | Without contacts, stuck hires have no escalation path |
| "Week 2 tasks aren't important for initial guide" | First contribution milestone is critical for confidence |
## Workflow
### Phase 1: Project Discovery
**Entry:** User has specified a project/team and target role
**Actions:**
1. Glob for README files, CONTRIBUTING.md, docs/ directories, setup scripts
2. Read dependency manifests to identify required tools and versions
3. Grep for environment variable references to identify required configuration
4. Identify build/run/test commands from scripts or documentation
**Exit:** Inventory of tools, dependencies, config needs, and existing docs
### Phase 2: Content Generation
**Entry:** Project discovery inventory complete
**Actions:**
1. Write Day 1: accounts, tools (exact versions), repos to clone, local setup commands, people to meet
2. Write Week 1: architecture overview, key files, codebase walkthrough, deploy pipeline, monitoring
3. Write Week 2: first contribution guide (branch naming, PR process, deploy/rollback), starter issues
4. Write Ongoing Reference: team rituals, communication norms, on-call, glossary
5. Add contact/escalation info to every section
**Exit:** Complete onboarding guide draft
### Phase 3: Command Verification
**Entry:** Onboarding guide draft complete
**Actions:**
1. Verify every setup command is syntactically correct for the target platform
2. Confirm all referenced file paths exist in the repository
3. Check tool version numbers match dependency manifests
4. Validate linked resources are correctly referenced
**Exit:** All commands and references verified
### Phase 4: Verification
**Entry:** Command verification complete
**Actions:**
1. Confirm guide covers all four phases (Day 1, Week 1, Week 2, Ongoing)
2. Verify every section has a contact/escalation path
3. Check no credentials, secrets, or internal-only URLs included
4. Validate guide is a single self-contained document
**Exit:** All checks pass — output results
## Output Format
```json
{
  "skill": "onboarding-guide",
  "status": "completed",
  "worker": "worker-id",
  "summary": "Created onboarding guide for backend engineers. Day 1 setup through Week 2 first contribution.",
  "findings": [
    {"item": "Day 1: Local setup", "severity": "info", "detail": "3 repos, Python 3.11 + Docker required, 12 env vars documented"},
    {"item": "Missing: CI/CD documentation", "severity": "medium", "detail": "No deploy pipeline docs found. Inferred from GitHub Actions."},
    {"item": "Stale README in services/auth", "severity": "low", "detail": "References Python 3.9 but pyproject.toml requires 3.11"}
  ],
  "artifacts": ["docs/onboarding-backend.md"],
  "errors": [], "elapsed_seconds": 60.1
}
```
### Bad Example
```json
{"skill": "onboarding-guide", "summary": "Onboarding guide created", "findings": [{"item": "Guide written", "severity": "info", "detail": "Covers setup and processes"}]}
```
Wrong: No specifics, no gaps identified, no artifact path. Boss cannot evaluate quality.
## Escalation Triggers
STOP and report to boss (do NOT guess) when:
- [ ] No README, no setup scripts, no existing documentation at all
- [ ] Credentials or secrets needed by new hires (request secure sharing method)
- [ ] Build process requires paid tools or licenses you cannot verify
- [ ] Project cannot be run locally (cloud-only, special hardware)
- [ ] Team structure or contacts not discoverable from repository
- [ ] Failed to identify build/run commands after 3 search strategies

Escalate as: `{"status": "escalated", "reason": "...", "context": "...", "recommendation": "..."}`
## Success Criteria
- [ ] Guide covers Day 1, Week 1, Week 2, and Ongoing Reference
- [ ] Every setup command verified as syntactically correct
- [ ] Every section includes a contact or escalation path
- [ ] No credentials or secrets in the guide
- [ ] Tool versions match dependency manifests
- [ ] Output matches the JSON format above
- [ ] No escalation triggers hit (or all reported)
