# Onboarding Doc

> Write or audit onboarding documentation so a new engineer can get productive without ambient knowledge - setup, architecture, conventions, who to ask. Use when the user asks to write onboarding docs, improve dev setup instructions, create a getting-started guide, or audit new-hire experience.

- **Type:** Skill
- **Install:** `agentstack add skill-kwhorne-elyra-skills-onboarding-doc`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kwhorne](https://agentstack.voostack.com/s/kwhorne)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kwhorne](https://github.com/kwhorne)
- **Source:** https://github.com/kwhorne/elyra-skills/tree/main/skills/onboarding-doc
- **Website:** https://elyracode.com

## Install

```sh
agentstack add skill-kwhorne-elyra-skills-onboarding-doc
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Onboarding Doc

The goal: a new engineer with no prior context can **clone, run, change, and ship** a small fix on their first day or two. Without DMing anyone.

A README that says "install dependencies and run the app" doesn't pass that bar.

## When to use

- "Write onboarding docs for X"
- "Improve our README / setup guide"
- "What does a new dev need to get started?"
- "Audit the new-hire experience"
- "Make it easier to contribute"

## Procedure

1. **Find a recent new hire / outside contributor** and ask what tripped them up — that's your spec
2. **Read the current README cold**, pretending you've never seen the code. Note every "wait, what?"
3. **Try to bootstrap from scratch** on a clean machine (or container) — every command you have to figure out is a gap
4. **Structure as a journey**, not a reference (see structure below)
5. **Cut ruthlessly** — every paragraph the reader skips is a paragraph that doesn't exist

## The 30-minute rule

A reader should be running the app locally within **30 minutes** of opening the README. If they're not, you're losing them.

If the actual setup takes longer (DB seeding, build), the *first 30 minutes* should include the "press enter and wait" command.

## Structure

The order matters. People read top-down and stop when frustrated.

```markdown
# 

## Quick start

\`\`\`bash
git clone 
cd 

\`\`\`

You should see . If you don't, jump to [Troubleshooting](#troubleshooting).

## Requirements

- 
- 
- 

## Repository tour

Where things live. Don't list every file — describe the logical zones.

\`\`\`
src/
  domain/      ← business logic, no framework imports
  api/         ← HTTP layer
  jobs/        ← background workers
tests/         ← mirrors src/
docs/          ← architecture docs and ADRs
\`\`\`

## How things fit together

A diagram or short walkthrough of the request lifecycle.

## Conventions

The things tools can't enforce. Keep this short — link out for details.

- We use Conventional Commits → see `docs/contributing.md`
- Tests live next to code, named `*.test.ts`
- Migrations are expand/contract → see `docs/migrations.md`

## Common tasks

How to do the things you'll actually do daily:

- Run tests: ``
- Run only one test: ``
- Create a migration: ``
- Reset the database: ``
- Run against staging API: ``

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
|  |  |  |
|  |  |  |

## Where to ask

- General questions: #channel
- This codebase: @
- Security: security@example.com
```

## What to put in vs link out

### In the main onboarding doc

- Quick start
- Requirements
- Repo tour (paragraph + tree)
- Common tasks they'll actually do
- Troubleshooting top issues
- Where to get help

### Linked from it (separate docs)

- Architecture deep dive
- Coding conventions in detail
- Deployment / release process
- Security policy
- ADRs

The main doc is the **table of contents to the team's knowledge**, not all of it.

## Make every command runnable

```markdown
❌ "Set up your environment variables"
✅ "Copy the example env file and fill in the values:
     `cp .env.example .env`
     The placeholders work for local dev. For staging values, ask in #channel."
```

```markdown
❌ "Install dependencies"
✅ "`npm install` (uses the version in `.nvmrc`; install [nvm](https://...) first if missing)"
```

Every step should be **copy-pasteable** and produce visible output.

## `.env.example` matters more than you think

The single most common onboarding failure: an env var that's required but undocumented.

- [ ] `.env.example` lives in the repo, committed
- [ ] Every key has a one-line comment explaining what it does and where to get the value
- [ ] Defaults that work for local dev are filled in
- [ ] Secrets clearly marked: "ask in #channel for the staging value"

```bash
# .env.example
# App
APP_URL=http://localhost:3000
APP_ENV=local

# Database (local Docker default — see docker-compose.yml)
DATABASE_URL=postgresql://app:app@localhost:5432/app_dev

# Mailer (Mailtrap for local; production uses Postmark)
MAIL_FROM=hello@example.test
MAIL_API_KEY=  # ask in #infra for the staging key

# Feature flags (optional)
FLAGS_SDK_KEY=  # leave empty for local; flags default to off
```

## "First contribution" path

Bonus: identify a small task a new hire can do on day 1–2 to actually ship something.

- Tag good-first-issue / starter tickets
- Document the "first PR" path: fork (if external) → branch → push → PR template → who reviews
- Pair them with a buddy for the first one

## Output format

When auditing existing docs:

```markdown
## Onboarding audit: 

**Test scenario:** Cold clone on a fresh machine, no team context.

**Time to first run:** 
**Number of times I had to ask / search:** 

### What works
- ✅ 

### Gaps
- 🔴 
- 🟠 
- 🟡 

### Top 5 fixes (ordered by impact)
1.  — 
2. …

### Trial: ask  to follow the updated doc
- 
```

When writing a new onboarding doc, follow the structure template above.

## Anti-patterns

- ❌ Outdated commands ("we don't use that script anymore")
- ❌ "Just ask " — the doc is supposed to replace the asking
- ❌ Walls of prose where a code block would do
- ❌ Setup that requires access you have to request through five channels with no instructions on which
- ❌ "Run `make setup`" where `make setup` does undocumented magic
- ❌ Docs that describe what the team *will* do, not what it currently does
- ❌ Burying critical info under "Advanced topics"
- ❌ Treating onboarding as a one-time event rather than an artifact you can run
- ❌ No troubleshooting section — every team has a known list of "if you see X, do Y"
- ❌ Different commands in README, Makefile, and CI — pick one source of truth

## Tips

- **Audit annually**, ideally by sitting next to a new hire. Most onboarding bugs are invisible to those with context.
- **Track time-to-first-PR** as a metric — it should trend down.
- **Make setup scriptable**: `bin/setup` that does the right thing on a fresh machine is the gold standard. README then becomes "run `bin/setup`, then …"
- **Devcontainers / Nix / `bin/setup` scripts** save more onboarding pain than any prose.
- **The team's tribal knowledge is the bug** — every "you have to know that…" goes in the doc.
- **Read the doc out loud** to find dropped antecedents and assumptions.
- **Don't fear redundancy** — repeat critical things; readers don't read linearly.

## References

- [GitLab Handbook](https://handbook.gitlab.com/) — extreme example of writing everything down
- [Stripe README guide](https://stripe.com/blog/canon) — internal-docs philosophy
- [The Documentation System (Diátaxis)](https://diataxis.fr/) — tutorial vs how-to vs reference vs explanation
- [Write the Docs guides](https://www.writethedocs.org/guide/)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kwhorne](https://github.com/kwhorne)
- **Source:** [kwhorne/elyra-skills](https://github.com/kwhorne/elyra-skills)
- **License:** MIT
- **Homepage:** https://elyracode.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kwhorne-elyra-skills-onboarding-doc
- Seller: https://agentstack.voostack.com/s/kwhorne
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.