# Automating Codebase Onboarding and Documentation with Claude Skills

> Automate codebase onboarding and documentation effortlessly. Claude Skills inspects repos, extracts artifacts, and generates guides in Markdown, Notion, or Confluence. Streamline your developer workflow today.

- Repository: [Alireza Rezvani/claude-skills](https://github.com/alirezarezvani/claude-skills)
- Tags: how-to-guide
- Published: 2026-03-09

---

**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`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/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`.

```bash

# 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`](https://github.com/alirezarezvani/claude-skills/blob/main/scripts/generate-docs.py) that can be repurposed for this workflow.

```python

# 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`](https://github.com/alirezarezvani/claude-skills/blob/main/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:

```python
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:

```javascript
// 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:

```bash
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`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/engineering/codebase-onboarding/SKILL.md) | Complete skill definition including command lists, templates, and export formats |
| [`README.md`](https://github.com/alirezarezvani/claude-skills/blob/main/README.md) | High-level catalogue listing all 169 skills with quick-install commands |
| [`mkdocs.yml`](https://github.com/alirezarezvani/claude-skills/blob/main/mkdocs.yml) | Configuration for the MkDocs site that renders the skill catalogue as a browsable knowledge base |
| [`.claude-plugin/marketplace.json`](https://github.com/alirezarezvani/claude-skills/blob/main/.claude-plugin/marketplace.json) | Marketplace manifest enabling one-click installation of skills within Claude Code |
| [`scripts/generate-docs.py`](https://github.com/alirezarezvani/claude-skills/blob/main/scripts/generate-docs.py) | Generic helper used by multiple skills to render Markdown templates from data |
| [`templates/CLAUDE.md`](https://github.com/alirezarezvani/claude-skills/blob/main/templates/CLAUDE.md) | Boilerplate template for skill documentation and agent prompts |
| [`docs/skills/engineering/codebase-onboarding.md`](https://github.com/alirezarezvani/claude-skills/blob/main/docs/skills/engineering/codebase-onboarding.md) | Rendered documentation page displayed on the MkDocs site |
| [`CLAUDE.md`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/mkdocs.yml)) guarantees the skill catalogue remains discoverable through a centralized documentation site.

## Summary

- The **Codebase Onboarding** skill in [`engineering/codebase-onboarding/SKILL.md`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/package.json), git history, and directory structures without external dependencies
- **Python automation scripts** (like those in [`scripts/generate-docs.py`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/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`](https://github.com/alirezarezvani/claude-skills/blob/main/CLAUDE.md) and [`.claude-plugin/marketplace.json`](https://github.com/alirezarezvani/claude-skills/blob/main/.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`](https://github.com/alirezarezvani/claude-skills/blob/main/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.