project-onboarding
Guided project onboarding for new codebases. Helps agents understand project structure, build systems, test commands, and development workflows by creating persistent knowledge memories.
How do I install this agent skill?
npx skills add https://github.com/oimiragieo/agent-studio --skill project-onboardingIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill facilitates codebase onboarding by analyzing project files to discover build and test workflows. It includes an indirect prompt injection surface because it parses untrusted configuration files which could contain malicious commands. It mitigates this by instructing agents to seek user permission before executing significant tasks.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
3/10 files flagged
What does this agent skill do?
When to Use
Invoke this skill when:
- Starting work on an unfamiliar codebase
- After context is lost (new session)
- When
check_onboarding_performedindicates 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
.gitignoreand.claudeignoreBEFORE scanning - Efficient File Triage:
- Use
git ls-filesto 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
- Use
- 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/TypeScriptpyproject.toml,requirements.txt- PythonCargo.toml- Rustgo.mod- Gopom.xml,build.gradle- Javacomposer.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
- Development:
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 --versionor equivalent to verify package manager - Run
npm run --silentto list available scripts - Do NOT run build or test without user permission
- Run
-
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
</instructions>
<examples>
<usage_example>
**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
</usage_example> </examples>
<integration> **Related Skills**: - `project-analyzer` - Deep automated analysis (complements onboarding) - `repo-rag` - Semantic search for patterns - `session-handoff` - Prepare context for new sessions </integration>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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/oimiragieo/agent-studio/project-onboarding">View project-onboarding on skillZs</a>