gh-dnlopes-claude-code-plugins-project-documenter/skills/onboard-repository/SKILL.md

name, description

name	description
onboard-repository	Use when creating CLAUDE.md or docs/claude/ documentation for a new repository - ensures systematic codebase exploration instead of generic templates, extracting real architecture, actual tech stack, and concrete code patterns from the repository

Onboard Repository

Overview

Repository onboarding creates documentation by systematically exploring the actual codebase, not by generating templates.

Core principle: Documentation must reflect what's ACTUALLY in the repository, not what you assume is there.

When to Use

Use this skill when:

• Creating CLAUDE.md for a new repository
• Setting up docs/claude/ documentation structure
• Onboarding multiple repositories systematically
• Someone asks to "document the codebase for Claude"

Do NOT use for:

• Adding to existing documentation (that's maintenance, not onboarding)
• Single file explanations (just read and explain)
• API documentation (that's a different skill)

The Iron Law

NO DOCUMENTATION WITHOUT READING THE CODE FIRST

Never:

• Generate documentation from directory structure alone
• Create "likely includes..." or "probably has..." content
• Use placeholders like "(needs investigation)"
• Make assumptions about patterns or conventions
• Write TODO or "fill this in later" sections

Always:

• Read actual source files before documenting them
• Extract real examples from the codebase
• Document what IS there, not what SHOULD be there

Systematic Onboarding Process

Phase 1: Discovery (Required First)

YOU MUST complete discovery before writing ANY documentation.

1. Identify the ecosystem:

   • Read go.mod/package.json/pom.xml/requirements.txt for dependencies
   • Check for framework indicators (Spring Boot, React, Kubernetes operator, etc.)
   • Identify build system (Make, Gradle, npm, etc.)

2. Map the architecture:

   • Read main entry points (main.go, index.ts, Application.java)
   • Trace key initialization code
   • Identify major components and their responsibilities
   • Find configuration sources

3. Extract patterns:

   • Find 2-3 representative files that show typical structure
   • Identify testing approach (framework, patterns, location)
   • Note error handling patterns
   • Document actual naming conventions used

4. Catalog specifics:

   • List actual make/npm/gradle targets (from files, not assumptions)
   • Find environment variables and configuration
   • Identify external dependencies (databases, APIs, message queues)
   • Document deployment/build artifacts

Phase 2: Documentation Structure

Create docs/claude/ with these files:

File	Content	Source
architecture.md	System design, component relationships, data flow	From reading main entry points and key files
tech-stack.md	Languages, frameworks, tools, versions	From dependency files and build configs
patterns.md	Code organization, naming, common patterns with REAL examples	From analyzing representative files
development.md	Build commands, testing, local dev setup	From Makefile/package.json/build files

Phase 3: Create CLAUDE.md

CLAUDE.md is the entry point that:

1. Briefly describes what the repo does (1-2 sentences)
2. Lists key directories and their purposes
3. Points to docs/claude/ for details
4. Includes quick start commands

Keep it short - detailed content goes in docs/claude/, not CLAUDE.md.

Documentation Content Requirements

Architecture (docs/claude/architecture.md)

Must include:

• High-level component diagram or description
• Data flow through the system
• Key abstractions and their relationships
• Integration points (databases, external services, APIs)

Must be based on:

• Reading main.go/index.ts/Application.java
• Tracing initialization code
• Following import/require chains
• Reading configuration setup

Example of good content:

## Request Processing Flow

1. HTTP request arrives at `pkg/server/handler.go:HandleRequest()`
2. Request validated using `pkg/validator/schema.go` Zod schemas
3. Business logic in `pkg/service/processor.go:ProcessOrder()`
4. Database writes via `pkg/repository/orders.go` using GORM
5. Event published to Kafka topic `order.processed` via `pkg/events/publisher.go`

Example of bad content:

## Request Processing Flow

The system likely handles requests through handlers, processes them with business logic, and stores results in a database.

Tech Stack (docs/claude/tech-stack.md)

Must include:

• Exact language versions (from go.mod, package.json, etc.)
• Framework with version (Spring Boot 3.2.1, React 18.2.0, etc.)
• Key libraries with brief purpose
• Build tools and versions
• Runtime requirements (Java 17, Node 20, Go 1.21)

Must be based on:

• Reading dependency files completely
• Checking .tool-versions or .nvmrc
• Reading Dockerfile for runtime requirements

Patterns (docs/claude/patterns.md)

Must include:

• Project structure with explanations
• Actual code examples (2-4) from the repo
• Testing patterns with real test file examples
• Error handling patterns with actual code
• Configuration patterns

Each pattern needs:

1. Description of the pattern
2. REAL code example from the codebase
3. Location of the example (file:line)

Example of good content:

## Error Handling Pattern

Errors are wrapped with context using pkg/errors:

```go
// From pkg/service/processor.go:45
func (s *Service) ProcessOrder(order *Order) error {
    if err := s.validator.Validate(order); err != nil {
        return fmt.Errorf("validating order %s: %w", order.ID, err)
    }
    // ...
}

This pattern provides error context for debugging while preserving the original error for type checking.

**Example of bad content:**
```markdown
## Error Handling Pattern

Errors should be handled appropriately with proper context and wrapping.

Development (docs/claude/development.md)

Must include:

• Actual build commands from Makefile/package.json
• How to run tests (with actual command)
• Local development setup steps
• Environment variables needed
• How to run the application locally

Must be based on:

• Reading Makefile/package.json/build.gradle completely
• Reading .env.example or config files
• Reading README.md if it exists
• Checking docker-compose.yml

Red Flags - STOP and Read Code

If you're writing any of these, STOP - you haven't read the code:

• "likely includes..."
• "probably uses..."
• "typically structured..."
• "common pattern is..."
• "(see X for details)" without reading X
• "(needs investigation)"
• "TODO: fill in..."
• Generic descriptions without specifics
• Zero code examples from the actual repo
• Assumed make targets without reading Makefile

All of these mean: Stop writing. Start reading.

Common Rationalizations

Excuse	Reality
"Directory structure tells me enough"	No. Assumptions are wrong. Read the files.
"I can fill in details later"	No later. Document what you found NOW.
"It's obviously a standard X pattern"	Nothing is standard. Read the actual implementation.
"Quick overview is fine for now"	Quick + accurate, not quick + wrong.
"User said to work fast"	Fast exploration is fine. Fast assumptions are not.
"It's just like other repos I've seen"	Each repo is different. Read this one.

Quality Checklist

Before considering onboarding complete:

• Read at least main entry point file completely
• Read actual dependency manifest (go.mod, package.json, etc.)
• Read actual build file (Makefile, package.json scripts, etc.)
• Extracted 2+ real code examples for patterns.md
• Listed specific versions for all major dependencies
• Documented actual make/npm/gradle targets with their real names
• Zero instances of "likely", "probably", "typically" in docs
• Zero TODO or placeholder sections
• Every pattern has real code example with file:line reference

Time Investment

Proper onboarding takes 15-30 minutes for typical repository:

• 10-15 min: Reading key files
• 5-10 min: Extracting examples
• 5-10 min: Writing documentation

This is MUCH faster than:

• Developers guessing what's there (hours)
• Debugging misunderstood architecture (hours/days)
• Onboarding new team members (hours/days)

The investment pays off immediately.

The Bottom Line

Repository onboarding means reading the actual code and documenting what you find.

Templates and assumptions create useless documentation. Systematic exploration creates valuable documentation.

If you didn't read it, don't document it.