npx skills add ...
npx skills add ailabs-393/ai-labs-claude-skills --skill codebase-documenter
npx skills add ailabs-393/ai-labs-claude-skills --skill codebase-documenter
This skill should be used when writing documentation for codebases, including README files, architecture documentation, code comments, and API documentation. Use this skill when users request help documenting their code, creating getting-started guides, explaining project structure, or making codebases more accessible to new developers. The skill provides templates, best practices, and structured approaches for creating clear, beginner-friendly documentation.
This skill enables creating comprehensive, beginner-friendly documentation for codebases. It provides structured templates and best practices for writing READMEs, architecture guides, code comments, and API documentation that help new users quickly understand and contribute to projects.
When documenting code for new users, follow these fundamental principles:
When to create: For project root directories, major feature modules, or standalone components.
Structure to follow:
Best practices:
When to create: For projects with multiple modules, complex data flows, or non-obvious design decisions.
Structure to follow:
Best practices:
When to create: For complex logic, non-obvious algorithms, or code that requires context.
Annotation patterns:
Function/Method Documentation:
Complex Logic Documentation:
Best practices:
When to create: For any HTTP endpoints, SDK methods, or public interfaces.
Structure to follow:
Best practices:
Before writing documentation:
Based on user request and codebase analysis:
Use the templates from assets/templates/ as starting points:
assets/templates/README.template.md - For project READMEsassets/templates/ARCHITECTURE.template.md - For architecture docsassets/templates/API.template.md - For API documentationCustomize templates based on the specific codebase:
Before finalizing documentation:
This skill includes several templates in assets/templates/ that provide starting structures:
assets/templates/For detailed documentation best practices, style guidelines, and advanced patterns, refer to:
references/documentation_guidelines.md - Comprehensive style guide and best practicesreferences/visual_aids_guide.md - How to create effective diagrams and file treesLoad these references when:
File trees help new users understand project organization:
Use numbered steps with diagrams:
Capture the "why" behind architectural choices:
When generating documentation:
Command to generate README: "Create a README file for this project that helps new developers get started"
Command to document architecture: "Document the architecture of this codebase, explaining how the different modules interact"
Command to add code comments: "Add explanatory comments to this file that help new developers understand the logic"
Command to document API: "Create API documentation for all the endpoints in this file"
# Architecture Overview
## System Design
[High-level diagram and explanation]
## Directory Structure
[Detailed breakdown with purpose of each directory]
## Data Flow
[How data moves through the system]
## Key Design Decisions
[Why certain architectural choices were made]
## Module Dependencies
[How different parts interact]
## Extension Points
[Where and how to add new features]/**
* Calculates the prorated subscription cost for a partial billing period.
*
* Why this exists: Users can subscribe mid-month, so we need to charge
* them only for the days remaining in the current billing cycle.
*
* @param {number} fullPrice - The normal monthly subscription price
* @param {Date} startDate - When the user's subscription begins
* @param {Date} periodEnd - End of the current billing period
* @returns {number} The prorated amount to charge
*
* @example
* // User subscribes on Jan 15, period ends Jan 31
* calculateProratedCost(30, new Date('2024-01-15'), new Date('2024-01-31'))
* // Returns: 16.13 (17 days out of 31 days)
*/# Why this check exists: The API returns null for deleted users,
# but empty string for users who never set a name. We need to
# distinguish between these cases for the audit log.
if user_name is None:
# User was deleted - log this as a security event
log_deletion_event(user_id)
elif user_name == "":
# User never completed onboarding - safe to skip
continue## Endpoint Name
### What It Does
[Plain-English explanation of the endpoint's purpose]
### Endpoint
`POST /api/v1/resource`
### Authentication
[What auth is required and how to provide it]
### Request Format
[JSON schema or example request]
### Response Format
[JSON schema or example response]
### Example Usage
[Concrete example with curl/code]
### Common Errors
[Error codes and what they mean]
### Related Endpoints
[Links to related operations]project-root/
├── src/ # Source code
│ ├── components/ # Reusable UI components
│ ├── pages/ # Page-level components (routing)
│ ├── services/ # Business logic and API calls
│ ├── utils/ # Helper functions
│ └── types/ # TypeScript type definitions
├── public/ # Static assets (images, fonts)
├── tests/ # Test files mirroring src structure
└── package.json # Dependencies and scriptsUser Request Flow:
1. User submits form → 2. Validation → 3. API call → 4. Database → 5. Response
[1] components/UserForm.tsx
↓ validates input
[2] services/validation.ts
↓ sends to API
[3] services/api.ts
↓ queries database
[4] Database (PostgreSQL)
↓ returns data
[5] components/UserForm.tsx (updates UI)## Why We Use Redux
**Decision:** State management with Redux instead of Context API
**Context:** Our app has 50+ components that need access to user
authentication state, shopping cart, and UI preferences.
**Reasoning:**
- Context API causes unnecessary re-renders with this many components
- Redux DevTools helps debug complex state changes
- Team has existing Redux expertise
**Trade-offs:**
- More boilerplate code
- Steeper learning curve for new developers
- Worth it for: performance, debugging, team familiarity