onboard-repo

name	onboard-repo
description	This skill should be used when the user asks to "onboard", "analyze this repo", "understand this codebase", "familiarize yourself", "what is this project", or needs to deeply understand a codebase's architecture, patterns, and conventions before starting work.

Onboard

Deep-dive into the current working directory to fully understand the codebase architecture, patterns, and conventions.

Execution Strategy

Step 0: Ensure Default Branch

Onboarding must always run against the repository's default branch so the analysis reflects the canonical codebase.

1. Detect the default branch — run git remote show origin | grep 'HEAD branch' | awk '{print $NF}' (fall back to main if the remote query fails).
2. Check the current branch — run git branch --show-current.
3. If already on the default branch, skip ahead to Step 1.
4. If on a different branch: a. Save the current branch name for later. b. If there are uncommitted changes (git status --porcelain is non-empty), create a temporary commit:

   git add -A && git commit -m "ONBOARD_TEMP_COMMIT" --no-verify
   

   c. Switch to the default branch: git checkout <default-branch>. d. Continue with Step 1 through Step 6. e. After Step 6 completes, switch back to the saved branch:

   git checkout <saved-branch>
   

   f. If a temporary commit was created in (b), undo it while keeping the working-tree changes:

   git reset --soft HEAD~1 && git restore --staged .
   

Important: Steps 1–6 below always execute on the default branch. The switch-back and reset happen only after all analysis and instruction file updates are complete.

Step 1: Check for Existing Instruction Files

Check if either or both of these files exist in the project:

• CLAUDE.md (project root) — used by Claude Code
• .github/copilot-instructions.md — used by GitHub Copilot

If a file exists: Read it and note the contents. It will be validated and updated if needed after the analysis.

If a file does NOT exist: It will be generated in Step 5.

Step 2: Quick Initial Scan

Note the current working directory (pwd). Read these files if they exist:

• README.md, CONTRIBUTING.md
• package.json, go.mod, Gemfile, Cargo.toml, pyproject.toml, etc.
• Top-level directory listing

Step 3: Spawn Parallel Subagents

Use parallel subagents to analyze different aspects simultaneously. This cuts onboarding time from ~5 min to ~1-2 min.

Launch these 4 subagents simultaneously using the Agent tool with subagent_type: "Explore" and model: "haiku". Inject the working directory (from Step 2) into each prompt.

Agent 1: Structure & Entry Points

Prompt: "Working directory: {cwd}. Map this codebase structure. Find:
1. All top-level directories and their purpose
2. Entry points (main.go, index.ts, app.rb, etc.)
3. Config files (tsconfig, webpack, vite, docker-compose)
4. Test directories and testing framework
Return a concise summary."

Agent 2: Architecture & Dependencies

Prompt: "Working directory: {cwd}. Analyze this codebase architecture. Find:
1. Core modules/packages and their responsibilities
2. How modules depend on each other
3. Shared utilities, types, constants locations
4. Database/API patterns if present
Return a concise summary."

Agent 3: Patterns & Conventions

Prompt: "Working directory: {cwd}. Identify coding patterns in this codebase:
1. Naming conventions (files, functions, variables)
2. Error handling approach
3. Import/export patterns
4. Logging and observability patterns
5. Any consistent architectural patterns
Return a concise summary."

Agent 4: Dev Workflow

Prompt: "Working directory: {cwd}. Find the development workflow for this codebase:
1. Build commands (package.json scripts, Makefile, etc.)
2. Test commands and how to run specific tests
3. Linting and formatting setup
4. CI/CD pipeline (.github/workflows, etc.)
5. Environment setup (.env.example, docker-compose)
Return a concise summary."

Step 4: Synthesize Results

Combine all subagent findings into a unified summary using the Output Format template below.

Step 5: Generate or Update Instruction Files

Apply this step to both CLAUDE.md and .github/copilot-instructions.md. The analysis content is the same — tailor the format and framing to each tool.

5a: CLAUDE.md (Claude Code)

Place at the project root. Use a # CLAUDE.md heading. Content priorities:

1. Build/test/lint commands (most critical)
2. Non-obvious conventions specific to this project
3. Gotchas and known footguns
4. Key architectural decisions

Omit anything that is self-evident from reading the code.

If the file already exists: Do a section-by-section comparison. Only edit sections where a finding directly contradicts or is missing from the current content:

• Commands changed (build, test, lint scripts differ from what's documented)
• New conventions adopted that aren't documented
• Key directories or entry points changed
• Tooling shifted (e.g., migrated from Jest to Vitest)
• A section is entirely missing that would meaningfully help

Make targeted edits only — use the Edit tool, not a full rewrite. If the existing file is complete and accurate, leave it untouched.

5b: .github/copilot-instructions.md (GitHub Copilot)

Place inside the .github/ directory (create it if it doesn't exist). Content priorities are the same as 5a, but:

• Omit the # CLAUDE.md heading — use a project-appropriate heading instead (e.g., # Copilot Instructions or # Project: {name})
• Keep the same sections: build/test/lint commands, conventions, gotchas, architecture
• Apply the same targeted-edit rules if the file already exists

Prioritize build/test/lint commands first, then non-obvious conventions, then gotchas. Omit anything derivable from reading the code. Keep it focused — quality over quantity.

Step 6: Report Changes

Always end with a brief summary covering both files:

File	Status
CLAUDE.md	Created / Updated (list changes) / No changes needed
.github/copilot-instructions.md	Created / Updated (list changes) / No changes needed

For each file that was modified, note what was added, updated, or left unchanged.

Output Format

Use this exact structure when presenting the synthesis in Step 4:

## Project: {name}

**Stack**: {languages, frameworks, major deps}
**Architecture**: {monolith/microservices/monorepo, key patterns}
**Entry points**: {main files}
**Test command**: {how to run tests}
**Build command**: {how to build}

### Key directories
- src/: {purpose}
- lib/: {purpose}
...

### Conventions observed
- {pattern 1}
- {pattern 2}

### Ready to work on
- {what kinds of tasks I can now handle}