Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.
npxskills add skillcreatorai/ai-agent-skills--skill code-documentationLoading…
# Project Name
Brief description of what this project does.
## Quick Start
\`\`\`bash
npm install
npm run dev
\`\`\`
## Installation
Detailed installation instructions...
## Usage
\`\`\`typescript
import { something } from 'project';
// Example usage
const result = something.doThing();
\`\`\`
## API Reference
### `functionName(param: Type): ReturnType`
Description of what the function does.
**Parameters:**
- `param` - Description of parameter
**Returns:** Description of return value
**Example:**
\`\`\`typescript
const result = functionName('value');
\`\`\`
## Configuration
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `option1` | `string` | `'default'` | What it does |
## Contributing
How to contribute...
## License
MIT
/**
* Creates a new user account.
*
* @param userData - The user data for account creation
* @param options - Optional configuration
* @returns The created user object
* @throws {ValidationError} If email is invalid
* @example
* ```ts
* const user = await createUser({
* email: '[email protected]',
* name: 'John'
* });
* ```
*/
async function createUser(
userData: UserInput,
options?: CreateOptions
): Promise<User> {
// Implementation
}
/**
* Configuration options for the API client.
*/
interface ClientConfig {
/** The API base URL */
baseUrl: string;
/** Request timeout in milliseconds @default 5000 */
timeout?: number;
/** Custom headers to include in requests */
headers?: Record<string, string>;
}
openapi: 3.0.0
info:
title: My API
version: 1.0.0
paths:
/users:
post:
summary: Create a user
description: Creates a new user account
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserInput'
responses:
'201':
description: User created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description: Invalid input
components:
schemas:
UserInput:
type: object
required:
- email
- name
properties:
email:
type: string
format: email
name:
type: string
User:
type: object
properties:
id:
type: string
email:
type: string
name:
type: string
createdAt:
type: string
format: date-time
// GOOD: Explain WHY, not WHAT
// Use binary search because the list is always sorted and
// can contain millions of items - O(log n) vs O(n)
const index = binarySearch(items, target);
// GOOD: Explain complex business logic
// Users get 20% discount if they've been members for 2+ years
// AND have made 10+ purchases (per marketing team decision Q4 2024)
if (user.memberYears >= 2 && user.purchaseCount >= 10) {
applyDiscount(0.2);
}
// GOOD: Document workarounds
// HACK: Safari doesn't support this API, fallback to polling
// TODO: Remove when Safari adds support (tracking: webkit.org/b/12345)
if (!window.IntersectionObserver) {
startPolling();
}
// BAD: Stating the obvious
// Increment counter by 1
counter++;
// BAD: Explaining clear code
// Check if user is admin
if (user.role === 'admin') { ... }
// BAD: Outdated comments (worse than no comment)
// Returns the user's full name <-- Actually returns email now!
function getUserIdentifier(user) {
return user.email;
}
# ADR-001: Use PostgreSQL for Primary Database
## Status
Accepted
## Context
We need a database for storing user data and transactions.
Options considered: PostgreSQL, MySQL, MongoDB, DynamoDB.
## Decision
Use PostgreSQL with Supabase hosting.
## Rationale
- Strong ACID compliance needed for financial data
- Team has PostgreSQL experience
- Supabase provides auth and realtime features
- pgvector extension for future AI features
## Consequences
- Need to manage schema migrations
- May need read replicas for scale
- Team needs to learn Supabase-specific features
## Authentication Module
### Overview
Handles user authentication using JWT tokens with refresh rotation.
### Flow
1. User submits credentials to `/auth/login`
2. Server validates and returns access + refresh tokens
3. Access token used for API requests (15min expiry)
4. Refresh token used to get new access token (7d expiry)
### Dependencies
- `jsonwebtoken` - Token generation/validation
- `bcrypt` - Password hashing
- `redis` - Refresh token storage
### Configuration
- `JWT_SECRET` - Secret for signing tokens
- `ACCESS_TOKEN_EXPIRY` - Access token lifetime
- `REFRESH_TOKEN_EXPIRY` - Refresh token lifetime
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).