code-documentation | SkillBundle

Code Documentation Skill

Overview

This skill generates professional, comprehensive documentation for software projects, codebases, libraries, and APIs. It follows industry best practices from projects like React, Django, Stripe, and Kubernetes to produce documentation that is accurate, well-structured, and useful for both new contributors and experienced developers.

The output ranges from single-file READMEs to multi-document developer guides, always matched to the project's complexity and the user's needs.

Core Capabilities

Generate comprehensive README.md files with badges, installation, usage, and API reference
Create API reference documentation from source code analysis
Produce architecture and design documentation with diagrams
Write developer onboarding and contribution guides
Generate changelogs from commit history or release notes
Create inline code documentation following language-specific conventions
Support JSDoc, docstrings, GoDoc, Javadoc, and Rustdoc formats
Adapt documentation style to the project's language and ecosystem

When to Use This Skill

Always load this skill when:

User asks to "document", "create docs", or "write documentation" for any code
User requests a README, API reference, or developer guide
User shares a codebase or repository and wants documentation generated
User asks to improve or update existing documentation
User needs architecture documentation, including diagrams
User requests a changelog or migration guide

Documentation Workflow

Phase 1: Codebase Analysis

Before writing any documentation, thoroughly understand the codebase.

Step 1.1: Project Discovery

Identify the project fundamentals:

Field	How to Determine
Language(s)	Check file extensions, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.
Framework	Look at dependencies for known frameworks (React, Django, Express, Spring, etc.)
Build System	Check for `Makefile`, `CMakeLists.txt`, `webpack.config.js`, `build.gradle`, etc.
Package Manager	npm/yarn/pnpm, pip/uv/poetry, cargo, go modules, etc.
Project Structure	Map out the directory tree to understand the architecture
Entry Points	Find main files, CLI entry points, exported modules
Existing Docs	Check for existing README, docs/, wiki, or inline documentation

Step 1.2: Code Structure Analysis

Use sandbox tools to explore the codebase:

# Get directory structure
ls /mnt/user-data/uploads/project-dir/
 
# Read key files
read_file /mnt/user-data/uploads/project-dir/package.json
read_file /mnt/user-data/uploads/project-dir/pyproject.toml
 
# Search for public API surfaces
grep -r "export " /mnt/user-data/uploads/project-dir/src/
grep -r "def " /mnt/user-data/uploads/project-dir/src/

Step 1.3: Identify Documentation Scope

Based on analysis, determine what documentation to produce:

Project Size	Recommended Documentation
Single file / script	Inline comments + usage header
Small library	README with API reference
Medium project	README + API docs + examples
Large project	README + Architecture + API + Contributing + Changelog

Phase 2: Documentation Generation

Step 2.1: README Generation

Every project needs a README. Follow this structure:

Step 2.2: API Reference Generation

For each public API surface, document:

Function / Method Documentation:

Class Documentation:

Step 2.3: Architecture Documentation

For medium-to-large projects, include architecture documentation:

Step 2.4: Inline Code Documentation

Generate language-appropriate inline documentation:

Python (Docstrings — Google style):

TypeScript (JSDoc / TSDoc):

Go (GoDoc):

Phase 3: Quality Assurance

Step 3.1: Documentation Completeness Check

Verify the documentation covers:

What it is — Clear project description that a newcomer can understand
Why it exists — Problem it solves and value proposition
How to install — Copy-paste-ready installation commands
How to use — At least one minimal working example
API surface — All public functions, classes, and types documented
Configuration — All environment variables, config files, and options
Error handling — Common errors and how to resolve them
Contributing — How to set up dev environment and submit changes

Step 3.2: Quality Standards

Standard	Check
Accuracy	Every code example must actually work with the described API
Completeness	No public API surface left undocumented
Consistency	Same formatting and structure throughout
Freshness	Documentation matches the current code, not an older version
Accessibility	No jargon without explanation, acronyms defined on first use
Examples	Every complex concept has at least one practical example

Step 3.3: Cross-reference Validation

Ensure:

All mentioned file paths exist in the project
All referenced functions and classes exist in the code
All code examples use the correct function signatures
Version numbers match the project's actual version
All links (internal and external) are valid

Documentation Style Guide

Writing Principles

Lead with the "why" — Before explaining how something works, explain why it exists
Progressive disclosure — Start simple, add complexity gradually
Show, don't tell — Prefer code examples over lengthy explanations
Active voice — "The function returns X" not "X is returned by the function"
Present tense — "The server starts on port 8080" not "The server will start on port 8080"
Second person — "You can configure..." not "Users can configure..."

Formatting Rules

Use ATX-style headers (#, ##, ###)
Use fenced code blocks with language specification (```python, ```bash)
Use tables for structured information (parameters, options, configuration)
Use admonitions for important notes, warnings, and tips
Keep line length readable (wrap prose at ~80-100 characters in source)
Use code formatting for function names, file paths, variable names, and CLI commands

Language-Specific Conventions

Language	Doc Format	Style Guide
Python	Google-style docstrings	PEP 257
TypeScript/JavaScript	TSDoc / JSDoc	TypeDoc conventions
Go	GoDoc comments	Effective Go
Rust	Rustdoc (`///`)	Rust API Guidelines
Java	Javadoc	Oracle Javadoc Guide
C/C++	Doxygen	Doxygen manual

Output Handling

After generation:

Save documentation files to /mnt/user-data/outputs/
For multi-file documentation, maintain the project directory structure
Present generated files to the user using the present_files tool
Offer to iterate on specific sections or adjust the level of detail
Suggest additional documentation that might be valuable

Notes

Always analyze the actual code before writing documentation — never guess at API signatures or behavior
When existing documentation exists, preserve its structure unless the user explicitly asks for a rewrite
For large codebases, prioritize documenting the public API surface and key abstractions first
Documentation should be written in the same language as the project's existing docs; default to English if none exist
When generating changelogs, use the Keep a Changelog format
This skill works well in combination with the deep-research skill for documenting third-party integrations or dependencies