Free SKILL.md scraped from GitHub. Clone the repo or copy the file directly into your Claude Code skills directory.
npx versuz@latest install seb155-atlas-plugin-dist-atlas-admin-addon-skills-onboarding-checkgit clone https://github.com/seb155/atlas-plugin.gitcp atlas-plugin/SKILL.MD ~/.claude/skills/seb155-atlas-plugin-dist-atlas-admin-addon-skills-onboarding-check/SKILL.md---
name: onboarding-check
description: "Team readiness assessment (12 checks). This skill should be used when the user asks to '/atlas onboard', 'team readiness', 'onboarding check', 'new developer', 'discipline engineer onboard', or needs an A-F score across docs/dev/CI/Forgejo."
mode: [ops, engineering]
effort: medium
---
# Onboarding Check — Team Readiness Assessment
Validates project readiness for new team members. Scores 12 dimensions across Documentation, Environment, Workflow, Team Support.
## When to Use
- "onboard", "onboarding", "ready for new dev", "team ready"
- "contributing", "CONTRIBUTING.md", "dev setup", "first commit"
- Before new dev joins
- After major infra changes (CI, auth, env)
- Periodically (quarterly)
## Subcommands
| Command | Mode | Output |
|---------|------|--------|
| `/atlas onboard` | **Full Check** | 12-dim scorecard + grade |
| `/atlas onboard gaps` | **Gap List** | Actionable missing items |
| `/atlas onboard fix` | **Auto-Fix** | Create missing docs/configs (HITL) |
| `/atlas onboard simulate` | **Dry Run** | Simulate fresh clone → first commit |
## Pipeline
```
SCAN → CHECK → SCORE → REPORT → FIX (optional)
```
## The 12 Checks
### Category 1: Documentation (4 checks, 35% weight)
#### 1.1 CONTRIBUTING.md (10%)
```bash
test -f CONTRIBUTING.md || test -f .github/CONTRIBUTING.md || test -f docs/CONTRIBUTING.md
```
**Score**: 100 = exists + Quick Start + PR workflow + conventions | 70 = incomplete | 30 = minimal | 0 = missing
**Content check** (if exists, verify): Quick Start (clone→install→run) | PR/branch workflow | Code conventions (lint/format/naming) | Testing instructions | Link to detailed docs
#### 1.2 Per-Module READMEs (8%)
```bash
test -f frontend/README.md && test -f backend/README.md
```
**Score**: 100 = both with start/test/build | 50 = one exists | 0 = neither
#### 1.3 Architecture Documentation (10%)
```bash
test -f .blueprint/INDEX.md || test -f docs/ARCHITECTURE.md || test -f ARCHITECTURE.md
```
**Score**: 100 = index + module links + entry points | 70 = sparse | 30 = no clear entry | 0 = missing
#### 1.4 Onboarding Runbook (7%)
```bash
test -f .blueprint/ONBOARDING-RUNBOOK.md || test -f docs/ONBOARDING.md
```
**Score**: 100 = step-by-step + SSO + access + first task | 50 = outdated/incomplete | 0 = missing
### Category 2: Development Environment (4 checks, 30% weight)
#### 2.1 One-Command Dev Setup (10%)
```bash
grep -q "^dev:" Makefile 2>/dev/null || grep -q "^dev " Makefile 2>/dev/null
test -f docker-compose.yml
```
**Score**: 100 = `make dev` documented | 70 = compose only, no Makefile | 30 = manual multi-step | 0 = no dev setup
#### 2.2 Environment Variables (8%)
```bash
test -f .env.example || test -f .env.template || test -f .envrc.example
```
**Score**: 100 = `.env.example` complete + documented | 70 = missing descriptions/stale | 30 = incomplete | 0 = missing
**Validation**: compare `.env.example` vars vs code references (`os.environ`, `process.env`); flag undocumented refs.
#### 2.3 Dependency Installation (7%)
```bash
test -f bun.lockb || test -f package-lock.json || test -f yarn.lock # FE
test -f requirements.txt || test -f pyproject.toml || test -f Pipfile # BE
```
**Score**: 100 = lock files + install documented | 70 = lock files only | 30 = no lock (drift risk) | 0 = no manifests
#### 2.4 Dev Tooling (5%)
```bash
test -f .editorconfig # Editor
test -f .vscode/settings.json || test -f .idea # IDE
grep -rq "pre-commit\|lefthook\|husky" . 2>/dev/null # Git hooks
```
**Score**: 100 = editor + IDE + hooks + lint | 70 = most | 30 = some | 0 = none
### Category 3: Workflow (2 checks, 20% weight)
#### 3.1 CI/CD Pipeline (12%)
```bash
test -f .forgejo/workflows/*.yml 2>/dev/null || \
test -f .github/workflows/*.yml 2>/dev/null || \
test -f .gitlab-ci.yml
```
**Score**: 100 = CI on PR + lint/test/build + green | 70 = exists not all checks or red | 30 = minimal | 0 = none
**Live check** (if CI exists): query CI status (Forgejo/GitHub API) → report last run date, status, duration.
#### 3.2 Branch Protection & PR Template (8%)
```bash
test -f .forgejo/PULL_REQUEST_TEMPLATE.md || test -f .github/PULL_REQUEST_TEMPLATE.md
# Branch protection: GET /api/v1/repos/{owner}/{repo}/branch_protections (Forgejo)
```
**Score**: 100 = PR template + protection on main + review required | 70 = some protection no template | 30 = minimal | 0 = none
### Category 4: Team Support (2 checks, 15% weight)
#### 4.1 Good First Issues (8%)
```bash
# Forgejo
curl -s "http://localhost:3000/api/v1/repos/{owner}/{repo}/issues?labels=good-first-issue&state=open"
# GitHub
gh issue list --label "good first issue" --state open
```
**Score**: 100 = 5+ open with clear desc | 70 = 2-4 | 30 = 1 or unclear | 0 = none
#### 4.2 Test Coverage & Safety Net (7%)
```bash
find . -name "test_*.py" -o -name "*.test.ts" -o -name "*.spec.ts" | wc -l
```
**Score**: 100 = >200 tests + CI runs + coverage >50% | 70 = 100-200 + CI | 30 = some not in CI | 0 = <10
## Scoring & Grading
### Weight Distribution
| Category | Weight | Checks |
|----------|--------|--------|
| Documentation | 35% | CONTRIBUTING, READMEs, Architecture, Runbook |
| Environment | 30% | Dev setup, Env vars, Dependencies, Tooling |
| Workflow | 20% | CI/CD, Branch protection |
| Team Support | 15% | Good first issues, Test safety net |
### Grade Scale
| Grade | Score | Meaning |
|-------|-------|---------|
| **A** | 90-100 | Ready for any developer, minimal friction |
| **B** | 75-89 | Ready with minor gaps, quick fixes needed |
| **C** | 60-74 | Passable but significant friction |
| **D** | 40-59 | Major gaps — new dev will struggle |
| **F** | 0-39 | Not ready — invest before onboarding |
## Output Format
```
🏛️ ATLAS │ Onboarding Check — Team Readiness — {date}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Grade: {grade} ({score}/100) │ Time to first commit: ~{minutes} min
📚 Documentation (35%) {cat_score}/100
─────────────────────────────────────────────────────────────────
{icon} CONTRIBUTING.md {score} {detail}
{icon} Module READMEs {score} {detail}
{icon} Architecture docs {score} {detail}
{icon} Onboarding runbook {score} {detail}
🔧 Development Environment (30%) {cat_score}/100
─────────────────────────────────────────────────────────────────
{icon} One-command dev setup {score} {detail}
{icon} Environment variables {score} {detail}
{icon} Dependency installation {score} {detail}
{icon} Dev tooling {score} {detail}
🔄 Workflow (20%) {cat_score}/100
─────────────────────────────────────────────────────────────────
{icon} CI/CD pipeline {score} {detail}
{icon} Branch protection + PR {score} {detail}
👥 Team Support (15%) {cat_score}/100
─────────────────────────────────────────────────────────────────
{icon} Good first issues {score} {detail}
{icon} Test safety net {score} {detail}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{If gaps:}
🔴 Gaps to Fix (priority order):
1. {highest impact + estimated fix time}
2. ...
💡 Quick Wins (<30 min each):
- {item}
🎯 Recommendation: {overall}
```
Status icons: ✅ 90+ | ⚠️ 50-89 | ❌ <50
## Auto-Fix Mode (`/atlas onboard fix`)
When gaps found, create missing items with HITL approval.
### Fixable Items
| Gap | Auto-Fix Action | HITL Gate |
|-----|----------------|-----------|
| Missing CONTRIBUTING.md | Generate from project context (README+Makefile) | Review before write |
| Missing frontend/README.md | Generate from package.json + Makefile targets | Review before write |
| Missing backend/README.md | Generate from pyproject.toml + Makefile targets | Review before write |
| Missing .env.example | Scan code for env refs, generate template | Review vars before write |
| Missing PR template | Generate standard template + checklist | Review before write |
| No good-first-issues | Scan TODO/FIXME, create 5 Forgejo issues | Review issues before create |
| Missing Forgejo labels | Create standard label set via API | Confirm label list |
### Process
1. AskUserQuestion: "{N} gaps found. Fix all / fix some / skip?"
2. Per fixable gap: generate content → preview → AskUserQuestion: "Create?" (Yes / Edit first / Skip)
3. After all fixes: re-run scorecard to show improvement
### Safety Rules
- NEVER create files without HITL approval
- NEVER modify existing files (only create missing)
- NEVER push to remote (local only)
- Generated content uses project conventions from scan
- Forgejo API unavailable → skip issue/label creation (report as manual)
## Simulate Mode (`/atlas onboard simulate`)
Simulate new developer experience:
1. Check prerequisites: git, docker, bun/node, python — documented?
2. Simulate clone: `git clone` + `make install` work?
3. Simulate dev: `make dev` starts all services?
4. Simulate test: `make test` passes?
5. Simulate first PR: workflow documented?
6. Time estimate: minutes to first commit
Output: Step-by-step walkthrough with pass/fail per step.
## Integration with Other Skills
| Skill | Integration |
|-------|------------|
| `product-health` | References health grade ("is app working?") |
| `feature-board` | Links to `/atlas board suggest` for first-task suggestions |
| `context-discovery` | Shares doc quality assessment |
| `atlas-doctor` | Shares tool/service health for env check |
## Personas
Different roles need different checks:
| Persona | Focus | Skip |
|---------|-------|------|
| **Full-stack dev** | All 12 | None |
| **Backend dev** | Docs, BE env, CI, tests | FE README, FE tooling |
| **Frontend dev** | Docs, FE env, CI, tests | BE README, DB setup |
| **Discipline engineer** | Docs, feature workflow, domain guides | Dev env, CI, tests |
AskUserQuestion at start: "Who are you onboarding?" to adapt check weights.