Smithery is now a part of Arcade.dev! Read more in our announcement here

project-onboarding

oimiragieo/project-onboarding

Communication

About

SKILL.md

project-onboarding

oimiragieo/project-onboarding

Communication

About

Guided project onboarding for new codebases. Helps agents understand project structure, build systems, test commands, and development workflows by creating persistent knowledge memories.

SKILL.md

Project Onboarding Specialist - Guided codebase exploration and knowledge capture for rapid project understanding. - Discovering project structure and organization patterns - Identifying build systems and package managers - Finding test commands and coverage configuration - Mapping key directories and entry points - Creating persistent memories for future sessions - Generating project overview documentation - Identifying development workflows and conventions

When to Use

Invoke this skill when:

Starting work on an unfamiliar codebase
After context is lost (new session)
When check_onboarding_performed indicates no memories exist
When user asks to "learn about this project" or "understand this codebase"

Onboarding Workflow

Step 1: Check Existing Knowledge

First, check if onboarding was already performed:

List files in: .claude/context/memory/
Look for: project-structure.md, build-commands.md, test-commands.md

If memories exist, read them and skip to Step 6 (Validation).

Step 2: Project Discovery

First, classify the project:

Greenfield vs Brownfield Detection

Indicator	Present?	Classification
`.git` directory with history	Yes	Brownfield
Package manifest (`package.json`, `requirements.txt`, etc.)	Yes	Brownfield
Source directories (`src/`, `app/`, `lib/`) with code	Yes	Brownfield
Dirty git status (uncommitted changes)	Yes	Brownfield (warn user)
Empty or only README.md	None of above	Greenfield

For Brownfield Projects:

Respect Ignore Files: Check .gitignore and .claudeignore BEFORE scanning
Efficient File Triage:
- Use git ls-files to list tracked files (respects .gitignore)
- For large files (>1MB): Read only head/tail (first and last 20 lines)
- Skip binary files, node_modules, build artifacts
Infer Tech Stack: Analyze manifests before asking questions
Context-Aware Questions: Base questions on discovered patterns

# Efficient file listing (respects .gitignore)
git ls-files --exclude-standard -co | head -100

# For non-git projects with manual ignores
find . -type f \
  -not -path '*/node_modules/*' \
  -not -path '*/.git/*' \
  -not -path '*/dist/*' \
  -not -path '*/build/*' \
  | head -100

For Greenfield Projects:

Create fresh context artifacts
Use interactive-requirements-gathering skill for setup

Analyze the project root to identify:

Package Manager & Language:
- package.json - Node.js/JavaScript/TypeScript
- pyproject.toml, requirements.txt - Python
- Cargo.toml - Rust
- go.mod - Go
- pom.xml, build.gradle - Java
- composer.json - PHP
Project Type:
- Frontend, Backend, Fullstack, Library, CLI, Mobile, Monorepo
Framework Detection:
- Parse dependencies for frameworks (React, Next.js, FastAPI, etc.)

Step 3: Build System Analysis

Identify how to build/run the project:

Check package.json scripts (Node.js):

{
  "scripts": {
    "dev": "...",
    "build": "...",
    "start": "...",
    "test": "..."
  }
}

Check Makefiles (Python, Go, Rust):
```
build:
test:
lint:
```
Check pyproject.toml (Python):
```
[tool.poetry.scripts]
[tool.poe.tasks]
```
Document discovered commands:
- Development: npm run dev, uv run dev
- Build: npm run build, cargo build
- Test: npm test, pytest
- Lint: npm run lint, ruff check

Step 4: Directory Structure Mapping

Map key directories:

Directory	Purpose
`src/`	Source code
`lib/`	Library code
`test/`, `tests/`, `__tests__/`	Test files
`docs/`	Documentation
`scripts/`	Utility scripts
`config/`	Configuration files

Identify:

Entry points (index.ts, main.py, app.py)
Component directories
API routes
Database models

Step 5: Create Onboarding Memories

Save discovered information to persistent memories:

Memory: project-structure.md

# Project Structure

## Overview

- Project Type: [fullstack/backend/frontend/library]
- Primary Language: [TypeScript/Python/Go/Rust]
- Framework: [Next.js/FastAPI/Express/etc.]

## Key Directories

- Source: `src/`
- Tests: `test/`
- Config: `.claude/`

## Entry Points

- Main: `src/index.ts`
- API: `src/api/`

## Important Files

- Configuration: `package.json`, `tsconfig.json`
- Environment: `.env.example`

Memory: build-commands.md

# Build Commands

## Development

- Start dev server: `npm run dev`
- Watch mode: `npm run watch`

## Build

- Production build: `npm run build`
- Type check: `npm run typecheck`

## Clean

- Clean build: `npm run clean`

Memory: test-commands.md

# Test Commands

## Unit Tests

- Run all: `npm test`
- Watch mode: `npm test -- --watch`
- Coverage: `npm test -- --coverage`

## E2E Tests

- Run: `npm run test:e2e`

## Linting

- Lint: `npm run lint`
- Fix: `npm run lint:fix`

Step 6: Validation

Validate discovered information:

Test Commands (if safe):
- Run npm --version or equivalent to verify package manager
- Run npm run --silent to list available scripts
- Do NOT run build or test without user permission
Verify Paths:
- Confirm key directories exist
- Verify entry points are correct

Step 7: Report Summary

Output a concise summary:

## Onboarding Complete

**Project**: [name]
**Type**: [fullstack/backend/etc.]
**Framework**: [Next.js/FastAPI/etc.]

**Quick Commands**:
- Dev: `npm run dev`
- Test: `npm test`
- Build: `npm run build`

**Key Locations**:
- Source: `src/`
- Tests: `test/`
- API: `src/api/`

**Memories Created**:
- .claude/context/memory/project-structure.md
- .claude/context/memory/build-commands.md
- .claude/context/memory/test-commands.md

**User Request**: "I need to understand this codebase"

Agent Actions:

Check for existing memories in .claude/context/memory/
If no memories, run project discovery
Analyze package.json, directory structure
Create memory files
Report summary

Output:

## Onboarding Complete

**Project**: agent-studio
**Type**: Multi-agent orchestration framework
**Framework**: Claude Code + Custom agents

**Quick Commands**:
- Validate: `node .claude/tools/cli/validate-agents.mjs`
- Test hooks: `node .claude/hooks/routing/router-enforcer.cjs` (uses `.claude/lib/routing/routing-table.cjs`)

**Key Locations**:
- Agents: `.claude/agents/`
- Skills: `.claude/skills/`
- Memory: `.claude/context/memory/`

**Memories Created**: 3 files

**Related Skills**: - `project-analyzer` - Deep automated analysis (complements onboarding) - `repo-rag` - Semantic search for patterns - `session-handoff` - Prepare context for new sessions

Iron Laws

ALWAYS check for existing onboarding memories before running discovery — duplicate onboarding creates contradictory knowledge entries that mislead future agents.
NEVER assume standard conventions without verification — run commands to confirm what actually works in this specific project environment.
ALWAYS write discovered commands and paths to persistent memory files — session context resets, but named memory files survive indefinitely.
ALWAYS verify discovered commands with a safe test step before documenting — incorrect commands in onboarding memories mislead every agent that reads them.
NEVER complete onboarding without revisiting memories when the project evolves — stale onboarding artifacts are more dangerous than no onboarding.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Assuming standard conventions without checking	Every project has unique build/test/lint commands; wrong assumptions cause silent failures	Read package.json, Makefile, or pyproject.toml and run `--version` to confirm
Skipping verification of discovered commands	Documented-but-wrong commands mislead every future agent session	Run each command with a safe no-op or `--help` flag to confirm it works
Storing onboarding only in session context	Context resets on every new conversation; discoveries are permanently lost	Write all findings to named memory files in `.claude/context/memory/named/`
Treating onboarding as a one-time event	Projects evolve; stale commands fail silently and waste agent time	Update onboarding memories after any significant project structure change
Over-documenting without prioritizing key commands	Long files with low-priority info bury the critical build/test commands	Structure memories with Quick Start commands at the top, details below

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

New pattern discovered -> .claude/context/memory/learnings.md
Issue encountered -> .claude/context/memory/issues.md
Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

About

SKILL.md

About

Guided project onboarding for new codebases. Helps agents understand project structure, build systems, test commands, and development workflows by creating persistent knowledge memories.

SKILL.md

When to Use

Invoke this skill when:

Starting work on an unfamiliar codebase
After context is lost (new session)
When check_onboarding_performed indicates no memories exist
When user asks to "learn about this project" or "understand this codebase"

Onboarding Workflow

Step 1: Check Existing Knowledge

First, check if onboarding was already performed:

List files in: .claude/context/memory/
Look for: project-structure.md, build-commands.md, test-commands.md

If memories exist, read them and skip to Step 6 (Validation).

Step 2: Project Discovery

First, classify the project:

Greenfield vs Brownfield Detection

Indicator	Present?	Classification
`.git` directory with history	Yes	Brownfield
Package manifest (`package.json`, `requirements.txt`, etc.)	Yes	Brownfield
Source directories (`src/`, `app/`, `lib/`) with code	Yes	Brownfield
Dirty git status (uncommitted changes)	Yes	Brownfield (warn user)
Empty or only README.md	None of above	Greenfield

For Brownfield Projects:

Respect Ignore Files: Check .gitignore and .claudeignore BEFORE scanning
Efficient File Triage:
- Use git ls-files to list tracked files (respects .gitignore)
- For large files (>1MB): Read only head/tail (first and last 20 lines)
- Skip binary files, node_modules, build artifacts
Infer Tech Stack: Analyze manifests before asking questions
Context-Aware Questions: Base questions on discovered patterns

# Efficient file listing (respects .gitignore)
git ls-files --exclude-standard -co | head -100

# For non-git projects with manual ignores
find . -type f \
  -not -path '*/node_modules/*' \
  -not -path '*/.git/*' \
  -not -path '*/dist/*' \
  -not -path '*/build/*' \
  | head -100

For Greenfield Projects:

Create fresh context artifacts
Use interactive-requirements-gathering skill for setup

Analyze the project root to identify:

Package Manager & Language:
- package.json - Node.js/JavaScript/TypeScript
- pyproject.toml, requirements.txt - Python
- Cargo.toml - Rust
- go.mod - Go
- pom.xml, build.gradle - Java
- composer.json - PHP
Project Type:
- Frontend, Backend, Fullstack, Library, CLI, Mobile, Monorepo
Framework Detection:
- Parse dependencies for frameworks (React, Next.js, FastAPI, etc.)

Step 3: Build System Analysis

Identify how to build/run the project:

Check package.json scripts (Node.js):

{
  "scripts": {
    "dev": "...",
    "build": "...",
    "start": "...",
    "test": "..."
  }
}

Check Makefiles (Python, Go, Rust):
```
build:
test:
lint:
```
Check pyproject.toml (Python):
```
[tool.poetry.scripts]
[tool.poe.tasks]
```
Document discovered commands:
- Development: npm run dev, uv run dev
- Build: npm run build, cargo build
- Test: npm test, pytest
- Lint: npm run lint, ruff check

Step 4: Directory Structure Mapping

Map key directories:

Directory	Purpose
`src/`	Source code
`lib/`	Library code
`test/`, `tests/`, `__tests__/`	Test files
`docs/`	Documentation
`scripts/`	Utility scripts
`config/`	Configuration files

Identify:

Entry points (index.ts, main.py, app.py)
Component directories
API routes
Database models

Step 5: Create Onboarding Memories

Save discovered information to persistent memories:

Memory: project-structure.md

# Project Structure

## Overview

- Project Type: [fullstack/backend/frontend/library]
- Primary Language: [TypeScript/Python/Go/Rust]
- Framework: [Next.js/FastAPI/Express/etc.]

## Key Directories

- Source: `src/`
- Tests: `test/`
- Config: `.claude/`

## Entry Points

- Main: `src/index.ts`
- API: `src/api/`

## Important Files

- Configuration: `package.json`, `tsconfig.json`
- Environment: `.env.example`

Memory: build-commands.md

# Build Commands

## Development

- Start dev server: `npm run dev`
- Watch mode: `npm run watch`

## Build

- Production build: `npm run build`
- Type check: `npm run typecheck`

## Clean

- Clean build: `npm run clean`

Memory: test-commands.md

# Test Commands

## Unit Tests

- Run all: `npm test`
- Watch mode: `npm test -- --watch`
- Coverage: `npm test -- --coverage`

## E2E Tests

- Run: `npm run test:e2e`

## Linting

- Lint: `npm run lint`
- Fix: `npm run lint:fix`

Step 6: Validation

Validate discovered information:

Test Commands (if safe):
- Run npm --version or equivalent to verify package manager
- Run npm run --silent to list available scripts
- Do NOT run build or test without user permission
Verify Paths:
- Confirm key directories exist
- Verify entry points are correct

Step 7: Report Summary

Output a concise summary:

## Onboarding Complete

**Project**: [name]
**Type**: [fullstack/backend/etc.]
**Framework**: [Next.js/FastAPI/etc.]

**Quick Commands**:
- Dev: `npm run dev`
- Test: `npm test`
- Build: `npm run build`

**Key Locations**:
- Source: `src/`
- Tests: `test/`
- API: `src/api/`

**Memories Created**:
- .claude/context/memory/project-structure.md
- .claude/context/memory/build-commands.md
- .claude/context/memory/test-commands.md

**User Request**: "I need to understand this codebase"

Agent Actions:

Check for existing memories in .claude/context/memory/
If no memories, run project discovery
Analyze package.json, directory structure
Create memory files
Report summary

Output:

## Onboarding Complete

**Project**: agent-studio
**Type**: Multi-agent orchestration framework
**Framework**: Claude Code + Custom agents

**Quick Commands**:
- Validate: `node .claude/tools/cli/validate-agents.mjs`
- Test hooks: `node .claude/hooks/routing/router-enforcer.cjs` (uses `.claude/lib/routing/routing-table.cjs`)

**Key Locations**:
- Agents: `.claude/agents/`
- Skills: `.claude/skills/`
- Memory: `.claude/context/memory/`

**Memories Created**: 3 files

**Related Skills**: - `project-analyzer` - Deep automated analysis (complements onboarding) - `repo-rag` - Semantic search for patterns - `session-handoff` - Prepare context for new sessions

Iron Laws

ALWAYS check for existing onboarding memories before running discovery — duplicate onboarding creates contradictory knowledge entries that mislead future agents.
NEVER assume standard conventions without verification — run commands to confirm what actually works in this specific project environment.
ALWAYS write discovered commands and paths to persistent memory files — session context resets, but named memory files survive indefinitely.
ALWAYS verify discovered commands with a safe test step before documenting — incorrect commands in onboarding memories mislead every agent that reads them.
NEVER complete onboarding without revisiting memories when the project evolves — stale onboarding artifacts are more dangerous than no onboarding.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Assuming standard conventions without checking	Every project has unique build/test/lint commands; wrong assumptions cause silent failures	Read package.json, Makefile, or pyproject.toml and run `--version` to confirm
Skipping verification of discovered commands	Documented-but-wrong commands mislead every future agent session	Run each command with a safe no-op or `--help` flag to confirm it works
Storing onboarding only in session context	Context resets on every new conversation; discoveries are permanently lost	Write all findings to named memory files in `.claude/context/memory/named/`
Treating onboarding as a one-time event	Projects evolve; stale commands fail silently and waste agent time	Update onboarding memories after any significant project structure change
Over-documenting without prioritizing key commands	Long files with low-priority info bury the critical build/test commands	Structure memories with Quick Start commands at the top, details below

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

New pattern discovered -> .claude/context/memory/learnings.md
Issue encountered -> .claude/context/memory/issues.md
Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.