borghei/Claude-Skills / engineering/codebase-onboarding
codebase-onboarding
VerifiedGathers facts about a codebase (stack, layers, entry points, setup gaps) and turns them into onboarding docs: architecture overview, file map, setup guide, debugging guide. Use when onboarding engineers or re-documenting after a refactor.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.3 KB |
| assets/sample_project/.env.example | other | 104 B |
| assets/sample_project/README.md | markdown | 88 B |
| assets/sample_project/package.json | manifest | 196 B |
| assets/sample_project/src/index.ts | script | 151 B |
| assets/sample_project/tests/orders.test.ts | script | 129 B |
| references/documentation-templates.md | markdown | 6.3 KB |
| references/fact-gathering-and-patterns.md | markdown | 2.9 KB |
| references/quality-and-best-practices.md | markdown | 4.4 KB |
| scripts/architecture_mapper.pyexecutable | script | 14.8 KB |
| scripts/onboarding_generator.pyexecutable | script | 14.9 KB |
| scripts/setup_validator.pyexecutable | script | 13.6 KB |
scripts/architecture_mapper.py
View on GitHub#!/usr/bin/env python3
"""Analyze project structure and generate a high-level architecture map.
Scans directories, detects architectural patterns, maps dependencies,
identifies layers, and produces a structured architecture overview
with Mermaid diagram markup.
"""
import argparse
import json
import os
import re
import sys
from collections import defaultdict
from pathlib import Path
IGNORE_DIRS = {
"node_modules", ".git", "__pycache__", ".next", "dist", "build",
".venv", "venv", "env", ".tox", ".mypy_cache", ".pytest_cache",
"vendor", "target", "bin", "obj", ".idea", ".vscode", "coverage",
".nyc_output", ".cache", ".turbo", ".svelte-kit",
}
LAYER_PATTERNS = {
"api": {"patterns": ["api", "routes", "endpoints", "controllers", "handlers", "views"],
"label": "API Layer", "description": "HTTP handlers and route definitions"},
"service": {"patterns": ["services", "service", "usecases", "use-cases", "interactors", "domain"],
"label": "Service/Business Logic", "description": "Core business rules and orchestration"},
"data": {"patterns": ["models", "entities", "schema", "db", "database", "repositories", "repo",
"dal", "prisma", "migrations", "drizzle"],
"label": "Data Layer", "description": "Database models, schemas, and data access"},
"ui": {"patterns": ["components", "pages", "views", "screens", "layouts", "templates", "ui"],
"label": "UI Layer", "description": "User interface components and page layouts"},
"config": {"patterns": ["config", "configuration", "settings", "constants"],
"label": "Configuration", "description": "Application settings and constants"},
"infrastructure": {"patterns": ["infra", "infrastructure", "deploy", "k8s", "terraform",
"docker", "ci", "scripts"],
"label": "Infrastructure", "description": "Deployment, CI/CD, and infrastructure"},
"shared": {"patterns": ["lib", "utils", "helpers", "common", "shared", "core", "pkg"],
"label": "Shared/Utilities", "description": "Reusable utilities and shared code"},
"tests": {"patterns": ["tests", "test", "__tests__", "spec", "specs", "e2e", "integration"],
"label": "Tests", "description": "Test suites and test utilities"},
"docs": {"patterns": ["docs", "documentation", "doc", "wiki"],
"label": "Documentation", "description": "Project documentation and guides"},
"assets": {"patterns": ["assets", "static", "public", "media", "images", "fonts", "styles"],
"label": "Static Assets", "description": "Images, fonts, stylesheets, and static files"},
}
ARCHITECTURE_PATTERNS = {
"monorepo": {
"signals": ["packages", "apps", "libs", "modules"],
"description": "Monorepo with multiple packages or applications",
},
"microservices": {
"signals": ["services", "microservices"],
"description": "Microservices architecture with independent services",
},
"mvc": {
"signals": ["controllers", "models", "views"],
"description": "Model-View-Controller pattern",
},
"layered": {
"signals": ["api", "services", "repositories"],
"description": "Layered architecture with clear separation of concerns",
},
"feature-based": {
"signals": ["features", "modules"],
"description": "Feature-based module organization",
},
"nextjs-app": {
"signals": ["app"],
"description": "Next.js App Router with file-based routing",
},
}
def should_ignore(name):
"""Check if a directory name should be ignored."""
return name in IGNORE_DIRS or name.startswith(".")
def scan_top_dirs(root):
"""Get top-level directories with metadata."""
root_path = Path(root).resolve()
dirs = []
for item in sorted(root_path.iterdir()):
if item.is_dir() and not should_ignore(item.name):
file_count = 0
extensions = defaultdict(int)
for dirpath, dirnames, filenames in os.walk(item):
dirnames[:] = [d for d in dirnames if not should_ignore(d)]
for f in filenames:
ext = Path(f).suffix.lower()
if ext:
extensions[ext] += 1
file_count += 1
if len(Path(dirpath).relative_to(item).parts) > 4:
dirnames.clear()
top_ext = sorted(extensions.items(), key=lambda x: -x[1])[:5]
dirs.append({
"name": item.name,
"file_count": file_count,
"top_extensions": dict(top_ext),
"subdirs": sorted([
d.name for d in item.iterdir()
if d.is_dir() and not should_ignore(d.name)
])[:10],
})
return dirs
def classify_layers(top_dirs):
"""Map top-level directories to architectural layers."""
classified = {}
unclassified = []
for d in top_dirs:
name_lower = d["name"].lower()
matched = False
for layer_id, layer_info in LAYER_PATTERNS.items():
if name_lower in layer_info["patterns"]:
classified[d["name"]] = {
"layer": layer_id,
"label": layer_info["label"],
"description": layer_info["description"],
"file_count": d["file_count"],
}
matched = True
break
if not matched:
unclassified.append(d["name"])
return classified, unclassified
def detect_architecture_pattern(top_dirs):
"""Detect the dominant architecture pattern."""
dir_names = {d["name"].lower() for d in top_dirs}
detected = []
for pattern_id, pattern_info in ARCHITECTURE_PATTERNS.items():
matches = [s for s in pattern_info["signals"] if s in dir_names]
if matches:
detected.append({
"pattern": pattern_id,
"description": pattern_info["description"],
"signals": matches,
"confidence": len(matches) / len(pattern_info["signals"]),
})
detected.sort(key=lambda x: -x["confidence"])
return detected
def parse_dependencies(root):
"""Extract dependency names from common manifest files."""
root_path = Path(root).resolve()
deps = {"runtime": [], "dev": []}
# package.json
pkg_path = root_path / "package.json"
if pkg_path.exists():
try:
data = json.loads(pkg_path.read_text(errors="ignore"))
deps["runtime"].extend(sorted(data.get("dependencies", {}).keys()))
deps["dev"].extend(sorted(data.get("devDependencies", {}).keys()))
except (ValueError, OSError):
pass
# requirements.txt
req_path = root_path / "requirements.txt"
if req_path.exists():
try:
for line in req_path.read_text(errors="ignore").splitlines():
line = line.strip()
if line and not line.startswith("#") and not line.startswith("-"):
pkg = re.split(r"[>=<!\[\];]", line)[0].strip()
if pkg:
deps["runtime"].append(pkg)
except OSError:
pass
# go.mod
gomod_path = root_path / "go.mod"
if gomod_path.exists():
try:
in_require = False
for line in gomod_path.read_text(errors="ignore").splitlines():
line = line.strip()
if line.startswith("require ("):
in_require = True
continue
if in_require and line == ")":
in_require = False
continue
if in_require and line:
parts = line.split()
if parts:
deps["runtime"].append(parts[0])
except OSError:
pass
# Cargo.toml
cargo_path = root_path / "Cargo.toml"
if cargo_path.exists():
try:
in_deps = False
for line in cargo_path.read_text(errors="ignore").splitlines():
if re.match(r"\[dependencies\]", line):
in_deps = True
continue
if re.match(r"\[dev-dependencies\]", line):
in_deps = True
continue
if line.startswith("[") and in_deps:
in_deps = False
continue
if in_deps:
match = re.match(r"^(\w[\w-]*)\s*=", line)
if match:
deps["runtime"].append(match.group(1))
except OSError:
pass
return deps
def generate_mermaid_diagram(layers, pattern):
"""Generate a Mermaid diagram of the architecture."""
lines = ["graph TD"]
layer_order = ["ui", "api", "service", "data", "shared", "config", "infrastructure", "tests"]
nodes = {}
for dir_name, info in layers.items():
layer = info["layer"]
node_id = f"{layer}_{dir_name}".replace("-", "_")
label = f"{dir_name}/ ({info['file_count']} files)"
nodes[layer] = nodes.get(layer, [])
nodes[layer].append((node_id, label))
lines.append(f" {node_id}[\"{label}\"]")
# Add edges based on typical flow
flow_edges = [
("ui", "api"), ("api", "service"), ("service", "data"),
("api", "shared"), ("service", "shared"),
]
added_edges = set()
for from_layer, to_layer in flow_edges:
if from_layer in nodes and to_layer in nodes:
f_id = nodes[from_layer][0][0]
t_id = nodes[to_layer][0][0]
edge_key = (f_id, t_id)
if edge_key not in added_edges:
lines.append(f" {f_id} --> {t_id}")
added_edges.add(edge_key)
return "\n".join(lines)
def generate_report(root):
"""Generate the full architecture analysis report."""
root_path = Path(root).resolve()
top_dirs = scan_top_dirs(root)
layers, unclassified = classify_layers(top_dirs)
patterns = detect_architecture_pattern(top_dirs)
deps = parse_dependencies(root)
mermaid = generate_mermaid_diagram(layers, patterns[0] if patterns else None)
# Count root-level files
root_files = sorted([
f.name for f in root_path.iterdir()
if f.is_file() and not f.name.startswith(".")
])
return {
"project_name": root_path.name,
"project_path": str(root_path),
"architecture_patterns": patterns,
"layers": layers,
"unclassified_directories": unclassified,
"directory_details": top_dirs,
"dependencies": {
"runtime_count": len(deps["runtime"]),
"dev_count": len(deps["dev"]),
"runtime": deps["runtime"][:30],
"dev": deps["dev"][:20],
},
"root_files": root_files,
"mermaid_diagram": mermaid,
}
def format_human(report):
"""Format report as human-readable text."""
lines = []
lines.append(f"{'=' * 60}")
lines.append(f" ARCHITECTURE MAP: {report['project_name']}")
lines.append(f"{'=' * 60}")
lines.append(f"\nProject: {report['project_path']}")
# Architecture patterns
lines.append(f"\n--- Detected Architecture Patterns ---")
if report["architecture_patterns"]:
for p in report["architecture_patterns"]:
conf = f"{p['confidence']:.0%}"
lines.append(f" {p['pattern'].upper()} ({conf} confidence)")
lines.append(f" {p['description']}")
lines.append(f" Signals: {', '.join(p['signals'])}")
else:
lines.append(" No standard architecture pattern detected.")
# Layers
lines.append(f"\n--- Architectural Layers ---")
if report["layers"]:
for dir_name, info in sorted(report["layers"].items(),
key=lambda x: x[1]["layer"]):
lines.append(f" {dir_name}/")
lines.append(f" Layer: {info['label']}")
lines.append(f" Purpose: {info['description']}")
lines.append(f" Files: {info['file_count']}")
else:
lines.append(" No directories matched known layer patterns.")
if report["unclassified_directories"]:
lines.append(f"\n Unclassified directories: {', '.join(report['unclassified_directories'])}")
# Directory details
lines.append(f"\n--- Directory Breakdown ---")
for d in report["directory_details"]:
lines.append(f"\n {d['name']}/ ({d['file_count']} files)")
if d["top_extensions"]:
ext_str = ", ".join(f"{ext}({cnt})" for ext, cnt in d["top_extensions"].items())
lines.append(f" File types: {ext_str}")
if d["subdirs"]:
lines.append(f" Subdirs: {', '.join(d['subdirs'])}")
# Dependencies
deps = report["dependencies"]
lines.append(f"\n--- Dependencies ---")
lines.append(f" Runtime: {deps['runtime_count']} | Dev: {deps['dev_count']}")
if deps["runtime"]:
lines.append(f"\n Key runtime dependencies:")
for dep in deps["runtime"][:15]:
lines.append(f" - {dep}")
if deps["dev"]:
lines.append(f"\n Key dev dependencies:")
for dep in deps["dev"][:10]:
lines.append(f" - {dep}")
# Root files
if report["root_files"]:
lines.append(f"\n--- Root-Level Files ---")
for f in report["root_files"]:
lines.append(f" {f}")
# Mermaid diagram
lines.append(f"\n--- Mermaid Architecture Diagram ---")
lines.append(" (Copy into a Mermaid-compatible renderer)\n")
lines.append("```mermaid")
lines.append(report["mermaid_diagram"])
lines.append("```")
lines.append(f"\n{'=' * 60}")
return "\n".join(lines)
def main():
parser = argparse.ArgumentParser(
description="Analyze project structure and generate a high-level architecture map.",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=(
"Examples:\n"
" %(prog)s /path/to/project\n"
" %(prog)s . --json\n"
" %(prog)s ~/my-app --json > architecture.json\n"
),
)
parser.add_argument(
"directory",
nargs="?",
default=".",
help="Project directory to analyze (default: current directory)",
)
parser.add_argument(
"--json",
action="store_true",
dest="json_output",
help="Output results as JSON instead of human-readable format",
)
args = parser.parse_args()
target = Path(args.directory).resolve()
if not target.is_dir():
print(f"Error: '{args.directory}' is not a valid directory.", file=sys.stderr)
sys.exit(2)
report = generate_report(str(target))
if args.json_output:
print(json.dumps(report, indent=2))
else:
print(format_human(report))
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |