Automating Codebase Onboarding and Documentation with Claude Skills

The Claude Skills repository provides a reusable, command-driven workflow that inspects repositories, extracts architectural artifacts, and generates complete onboarding guides in Markdown, Notion, or Confluence.

This guide explores how to implement automated documentation generation using the Codebase Onboarding skill from the alirezarezvani/claude-skills repository. By leveraging this Powerful-tier skill located at engineering/codebase-onboarding/SKILL.md, teams can transform manual onboarding processes into repeatable, version-controlled workflows that keep documentation synchronized with actual code changes.

How the Codebase Onboarding Skill Works

The Codebase Onboarding skill follows a three-phase automation pipeline designed to run once per repository (or whenever the codebase changes significantly). According to the skill definition in engineering/codebase-onboarding/SKILL.md, the workflow captures project metadata through shell commands, processes the output through Claude Code (or local Python scripts), and renders the final document via parameterized templates.

The skill generates six core sections parameterized by audience level (junior, senior, or contractor):

• Architecture overview with tech-stack and data-flow diagrams
• Key-file map with purpose annotations
• Local setup guide covering clone-to-test workflows
• Common developer tasks including API endpoints and database migrations
• Debugging guide for runtime errors and SQL diagnostics
• Contribution workflow with branching models and PR checklists

Unlike static documentation, this approach uses the repository itself as the source of truth, extracting data from package.json, git history, test coverage reports, and directory structures to ensure accuracy.

Generating Onboarding Documentation Automatically

Step 1: Collect Repository Facts

The skill prescribes a specific set of shell commands to capture project metadata. These commands extract structured data without dependencies on external tools beyond standard Unix utilities and jq.

# Gather architectural facts

project_overview=$(cat package.json | jq '{name, version, scripts, dependencies: (.dependencies|keys), devDependencies: (.devDependencies|keys)}')
dir_structure=$(find . -maxdepth 2 -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/.next/*' | sort | head -60)
largest_files=$(find src/ -name "*.ts" -not -path "*/test*" -exec wc -l {} + | sort -rn | head -20)
routes=$(find app/ -name "route.ts" -o -name "page.tsx" | sort)
git_changes=$(git log --oneline --since="90 days ago" | grep -E "feat|refactor|breaking")
contributors=$(git shortlog -sn --no-merges | head -10)
coverage=$(pnpm test:ci --coverage 2>&1 | tail -20)

These variables capture the directory tree, recent architectural changes, code ownership, and test coverage metrics required to populate the onboarding template.

Step 2: Populate the Markdown Template

Once collected, the facts feed into a Python formatter that injects the data into the Markdown template defined in the skill documentation. The repository includes generic helpers like scripts/generate-docs.py that can be repurposed for this workflow.

# generate_onboarding.py

import subprocess, json, pathlib, textwrap

def run(cmd):
    return subprocess.check_output(cmd, shell=True, text=True).strip()

# Collect facts dictionary

facts = {
    "project": json.loads(run("cat package.json | jq '{name, version, scripts, dependencies: (.dependencies|keys), devDependencies: (.devDependencies|keys)}'")),
    "dir_tree": run("find . -maxdepth 2 -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/.next/*' | sort | head -60"),
    "largest_files": run('find src/ -name "*.ts" -not -path "*/test*" -exec wc -l {} + | sort -rn | head -20'),
    "routes": run('find app/ -name "route.ts" -o -name "page.tsx" | sort'),
    "recent_changes": run('git log --oneline --since="90 days ago" | grep -E "feat|refactor|breaking"'),
    "contributors": run('git shortlog -sn --no-merges | head -10'),
    "coverage": run('pnpm test:ci --coverage 2>&1 | tail -20')
}

# Load and populate template

template = pathlib.Path("templates/onboarding_template.md").read_text()
filled = template.format(**{
    k: textwrap.indent(v, "  ") if isinstance(v, str) else json.dumps(v, indent=2) 
    for k, v in facts.items()
})

pathlib.Path("ONBOARDING.md").write_text(filled)
print("✅ Onboarding guide generated → ONBOARDING.md")

Running python3 generate_onboarding.py produces the complete onboarding document matching the Generated Documentation Template specified in engineering/codebase-onboarding/SKILL.md.

Step 3: Export to Knowledge Bases

The skill supports three output formats: Markdown (default), Notion blocks, and Confluence storage format. The repository includes export snippets for each platform.

Complete Implementation Examples

Python Automation Script

For teams preferring a pure-Python approach without shell intermediaries, the following implementation uses only the standard library to achieve the same result:

import subprocess, json, pathlib, textwrap

def run(cmd):
    return subprocess.check_output(cmd, shell=True, text=True).strip()

facts = {
    "project": json.loads(run("cat package.json | jq '{name, version, scripts, dependencies: (.dependencies|keys), devDependencies: (.devDependencies|keys)}'")),
    "dir_tree": run("find . -maxdepth 2 -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/.next/*' | sort | head -60"),
    "largest_files": run('find src/ -name "*.ts" -not -path "*/test*" -exec wc -l {} + | sort -rn | head -20'),
    "routes": run('find app/ -name "route.ts" -o -name "page.tsx" | sort'),
    "recent_changes": run('git log --oneline --since="90 days ago" | grep -E "feat|refactor|breaking"'),
    "contributors": run('git shortlog -sn --no-merges | head -10'),
    "coverage": run('pnpm test:ci --coverage 2>&1 | tail -20')
}

template = pathlib.Path("templates/onboarding_template.md").read_text()
filled = template.format(**{k: textwrap.indent(v, "  ") if isinstance(v, str) else json.dumps(v, indent=2) for k, v in facts.items()})

pathlib.Path("ONBOARDING.md").write_text(filled)
print("✅ Onboarding guide generated → ONBOARDING.md")

This script can be integrated into CI pipelines (e.g., GitHub Actions) to regenerate documentation on every push to main, ensuring the onboarding guide never drifts from the actual codebase state.

Notion Publishing Pipeline

To publish the generated Markdown to Notion, use the Node.js snippet provided in the skill documentation. This converts the Markdown blocks to Notion's block structure and creates a page under a specified parent:

// notion_publish.js
const { Client } = require('@notionhq/client');
const fs = require('fs');
const markdownToNotion = require('markdown-to-notion');

const notion = new Client({ auth: process.env.NOTION_TOKEN });
const markdown = fs.readFileSync('ONBOARDING.md', 'utf8');

(async () => {
  const blocks = await markdownToNotion(markdown);
  await notion.pages.create({
    parent: { page_id: process.env.NOTION_PARENT_PAGE_ID },
    properties: { title: [{ text: { content: 'Engineers Onboarding – MyProject' } }] },
    children: blocks,
  });
  console.log('✅ Notion page created');
})();

Set the NOTION_TOKEN and NOTION_PARENT_PAGE_ID environment variables to authenticate and route the page to the correct knowledge base location.

Confluence Integration

For Atlassian environments, the skill provides a cURL-based approach that posts the Markdown content directly to the Confluence REST API:

curl -X POST \
  -H "Content-Type: application/json" \
  -u "user@example.com:${CONFLUENCE_TOKEN}" \
  "https://yourorg.atlassian.net/wiki/rest/api/content" \
  -d '{
        "type": "page",
        "title": "Codebase Onboarding",
        "space": {"key": "ENG"},
        "body": {
          "storage": {
            "value": "<p>'$(sed ':a;N;$!ba;s/\n/\\n/g' ONBOARDING.md)'</p>",
            "representation": "storage"
          }
        }
      }'

This follows the Confluence Export example from engineering/codebase-onboarding/SKILL.md and requires a Confluence API token with write permissions to the target space.

Key Files and Architecture

The alirezarezvani/claude-skills repository organizes functionality through a skill-first architecture that separates concerns across specific file paths:

File	Purpose
engineering/codebase-onboarding/SKILL.md	Complete skill definition including command lists, templates, and export formats
README.md	High-level catalogue listing all 169 skills with quick-install commands
mkdocs.yml	Configuration for the MkDocs site that renders the skill catalogue as a browsable knowledge base
.claude-plugin/marketplace.json	Marketplace manifest enabling one-click installation of skills within Claude Code
scripts/generate-docs.py	Generic helper used by multiple skills to render Markdown templates from data
templates/CLAUDE.md	Boilerplate template for skill documentation and agent prompts
docs/skills/engineering/codebase-onboarding.md	Rendered documentation page displayed on the MkDocs site
CLAUDE.md	Root-level guidance for Claude Code agents on navigating and utilizing the repository

The zero-dependency Python scripts ensure portability across environments, while the MkDocs integration (mkdocs.yml) guarantees the skill catalogue remains discoverable through a centralized documentation site.

Summary

• The Codebase Onboarding skill in engineering/codebase-onboarding/SKILL.md provides a repeatable checklist for generating documentation from live repository data
• Shell command fact-gathering extracts metadata from package.json, git history, and directory structures without external dependencies
• Python automation scripts (like those in scripts/generate-docs.py) can wrap the skill workflow for CI/CD integration
• Export snippets for Notion and Confluence enable automatic publishing to internal knowledge bases
• The skill-first architecture ensures modular, portable documentation tools that work across Claude Code, OpenAI Codex, and OpenClaw agents

Frequently Asked Questions

How often should I regenerate the onboarding documentation?

Regenerate the documentation whenever significant architectural changes occur—ideally automating this through CI triggers on every push to your default branch. Because the skill extracts data from live sources like package.json and git logs, running it monthly or per-release ensures the onboarding guide accurately reflects current dependencies, file structures, and contribution workflows.

Does the skill require Claude Code to run, or can I use it standalone?

While the skill is optimized for Claude Code (as defined in CLAUDE.md and .claude-plugin/marketplace.json), the workflow uses standard shell commands and Python scripts that run independently. You can execute the fact-gathering commands manually or via the provided Python automation script without the Claude Code agent, making it compatible with any CI system or local development environment.

What directories does the fact-gathering command exclude?

The standard commands exclude node_modules/, .git/, and .next/ directories to avoid noise from dependency files and build artifacts. The find command uses -not -path filters for these patterns, focusing instead on source files in src/ and app/ directories, along with configuration files in the repository root.

Can I customize the template for different team roles?

Yes, the SKILL.md specifies that all sections are parameterized by audience (junior, senior, contractor). You can modify the Markdown template to include conditional blocks or create separate template files for each role, then adjust the Python formatter to select the appropriate template based on an environment variable or command-line argument passed to the generation script.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}