Guide for writing clear, comprehensive technical documentation including README files, API docs, guides, and inline documentation
Activates when writing or improving technical documentation like READMEs, API docs, guides, and inline comments. Provides guidance on structure, best practices, and language-specific formatting for clear, comprehensive documentation.
/plugin marketplace add vinnie357/claude-skills/plugin install core@vinnie357This skill inherits all available tools. When active, it can use any tool Claude has access to.
This skill activates when writing or improving technical documentation, including README files, API documentation, user guides, and inline code documentation.
Activate when:
Every README should include:
# Project Name
Brief one-liner description of the project.
## Overview
2-3 paragraphs explaining what the project does, why it exists, and who it's for.
## Features
- Key feature 1
- Key feature 2
- Key feature 3
## Installation
### Prerequisites
- Requirement 1 (with version)
- Requirement 2 (with version)
### Install Steps
```bash
# Clone repository
git clone https://github.com/user/project.git
cd project
# Install dependencies
npm install # or pip install -r requirements.txt, mix deps.get, etc.
# Configure
cp .env.example .env
# Edit .env with your settings
# Run
npm start
# Minimal example to get started
npm start
// Clear, runnable example
const example = new Project()
example.doSomething()
More complex examples with explanations.
| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | - | API key for authentication |
timeout | number | 5000 | Request timeout in ms |
Link to detailed API documentation or include core APIs here.
# Development-specific setup
npm install --dev
npm run setup
npm test
npm run test:coverage
npm run build
Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.
This project is licensed under the MIT License - see the LICENSE file for details.
### README Best Practices
- **Start with a clear one-liner**: Immediately tell readers what the project does
- **Include badges**: Build status, coverage, version, license
- **Show, don't tell**: Use code examples liberally
- **Keep it scannable**: Use headers, lists, and code blocks
- **Make examples runnable**: Readers should be able to copy-paste and run
- **Include visual aids**: Screenshots, diagrams, GIFs when appropriate
- **Update regularly**: Keep documentation in sync with code
- **Think about newcomers**: Write for someone seeing the project for the first time
## API Documentation
### Documenting Functions
**Elixir (@doc):**
```elixir
@doc """
Calculates the sum of two numbers.
## Parameters
- `a` - The first number (integer or float)
- `b` - The second number (integer or float)
## Returns
The sum of `a` and `b`.
## Examples
iex> Math.add(2, 3)
5
iex> Math.add(2.5, 3.7)
6.2
"""
@spec add(number(), number()) :: number()
def add(a, b) do
a + b
end
JavaScript (JSDoc):
/**
* Calculates the sum of two numbers.
*
* @param {number} a - The first number
* @param {number} b - The second number
* @returns {number} The sum of a and b
*
* @example
* add(2, 3)
* // => 5
*/
function add(a, b) {
return a + b
}
Python (docstring):
def add(a: float, b: float) -> float:
"""
Calculate the sum of two numbers.
Args:
a: The first number
b: The second number
Returns:
The sum of a and b
Examples:
>>> add(2, 3)
5
>>> add(2.5, 3.7)
6.2
Raises:
TypeError: If arguments are not numbers
"""
return a + b
Rust (doc comments):
/// Calculates the sum of two numbers.
///
/// # Arguments
///
/// * `a` - The first number
/// * `b` - The second number
///
/// # Returns
///
/// The sum of `a` and `b`
///
/// # Examples
///
/// ```
/// use mylib::add;
///
/// assert_eq!(add(2, 3), 5);
/// assert_eq!(add(2.5, 3.7), 6.2);
/// ```
pub fn add(a: f64, b: f64) -> f64 {
a + b
}
Document the purpose, usage, and public API:
defmodule MyApp.UserManager do
@moduledoc """
Manages user accounts and authentication.
The UserManager provides functions for creating, updating, and authenticating
users. It handles password hashing, session management, and user validation.
## Usage
# Create a new user
{:ok, user} = UserManager.create_user(%{
email: "alice@example.com",
password: "secure_password"
})
# Authenticate
{:ok, user} = UserManager.authenticate("alice@example.com", "secure_password")
# Update user
{:ok, updated} = UserManager.update_user(user, %{name: "Alice Smith"})
## Configuration
Configure in `config/config.exs`:
config :my_app, MyApp.UserManager,
password_min_length: 8,
session_timeout: 3600
"""
end
Document RESTful APIs clearly:
## Endpoints
### Create User
Creates a new user account.
**Endpoint:** `POST /api/users`
**Authentication:** Not required
**Request Body:**
```json
{
"email": "alice@example.com",
"password": "secure_password",
"name": "Alice Smith"
}
Response (201 Created):
{
"id": "123",
"email": "alice@example.com",
"name": "Alice Smith",
"created_at": "2024-01-15T10:30:00Z"
}
Error Responses:
400 Bad Request - Invalid input
{
"error": "validation_error",
"details": {
"email": ["must be a valid email address"],
"password": ["must be at least 8 characters"]
}
}
409 Conflict - Email already exists
{
"error": "email_taken",
"message": "An account with this email already exists"
}
Example:
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{
"email": "alice@example.com",
"password": "secure_password",
"name": "Alice Smith"
}'
## User Guides and Tutorials
### Tutorial Structure
```markdown
# Tutorial: Building Your First [Feature]
## What You'll Build
Brief description of the end result.
## Prerequisites
- Knowledge requirement 1
- Installed tool 1
- Account/access requirement
## Step 1: [First Major Step]
Explanation of what we're doing and why.
```language
// Code for this step
What's happening here:
Continue with incremental steps...
How to verify it works.
### Tutorial Best Practices
- **Show working code first**: Let readers see the goal before diving into details
- **Explain the 'why'**: Don't just show what to do, explain reasoning
- **Incremental steps**: Each step should build on the previous
- **Include checkpoints**: Ways to verify progress
- **Provide complete code**: Include a repository or final code snippet
- **Anticipate problems**: Address common mistakes
- **Link to references**: Point to relevant API docs and resources
## Inline Code Documentation
### When to Write Comments
**DO write comments for:**
- Complex algorithms or business logic
- Non-obvious decisions ("why" not "what")
- Workarounds for bugs or limitations
- Public APIs and exported functions
- Configuration and constants
**DON'T write comments for:**
- Obvious code
- What the code does (prefer clear naming)
- Outdated information
- Commented-out code (use version control)
### Good Comment Examples
```elixir
# Good: Explains WHY
# Use exponential backoff to avoid overwhelming the API after rate limit errors
defp retry_with_backoff(attempt) do
:timer.sleep(:math.pow(2, attempt) * 1000)
end
# Bad: Explains WHAT (obvious from code)
# Multiply 2 to the power of attempt and multiply by 1000
defp retry_with_backoff(attempt) do
:timer.sleep(:math.pow(2, attempt) * 1000)
end
# Good: Documents workaround
# NOTE: Using String.to_existing_atom because the Erlang VM limits atoms to ~1M.
# All valid status atoms are pre-defined in this module.
def parse_status(status_string) do
String.to_existing_atom(status_string)
end
# Good: Explains business rule
# Users must be at least 13 years old per COPPA regulations
@minimum_age 13
Document significant architectural decisions:
# ADR 001: Use PostgreSQL for Primary Database
## Status
Accepted
## Context
We need to choose a database for our application that supports:
- ACID transactions
- Complex queries with joins
- JSON data storage
- Full-text search
- Horizontal scalability (future requirement)
## Decision
We will use PostgreSQL as our primary database.
## Consequences
### Positive
- Mature, stable, well-documented
- Excellent JSON support with JSONB
- Built-in full-text search
- Strong consistency guarantees
- Large ecosystem of tools and extensions
- Can scale with read replicas and partitioning
### Negative
- More complex to operate than simpler databases
- Vertical scaling has limits (though sufficient for our needs)
- Requires more server resources than lighter alternatives
### Neutral
- Team needs to learn PostgreSQL-specific features
- May need to hire PostgreSQL expertise as we scale
## Alternatives Considered
- **MySQL**: Weaker JSON support, less feature-rich
- **MongoDB**: No ACID guarantees, eventual consistency issues
- **SQLite**: Not suitable for multi-user web applications
Follow Keep a Changelog format:
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- New feature in development
## [1.2.0] - 2024-01-15
### Added
- User profile pictures
- Email notification preferences
- Dark mode support
### Changed
- Improved search performance by 40%
- Updated UI to match new brand guidelines
### Fixed
- Login redirect loop on Safari
- Memory leak in background sync process
### Deprecated
- Old `/v1/users` endpoint (use `/v2/users` instead)
## [1.1.0] - 2024-01-01
### Added
- Two-factor authentication
- Export user data to JSON
### Security
- Fixed XSS vulnerability in comment rendering
## [1.0.0] - 2023-12-15
### Added
- Initial release
- User registration and authentication
- Basic user profiles
mix docscargo doc```mermaid
graph TD
A[User] -->|Requests| B[Load Balancer]
B --> C[Web Server 1]
B --> D[Web Server 2]
C --> E[Database]
D --> E
backticks for inline code$ prefix or in code blockscode formatting# Elixir doctests - examples in docs are actual tests
defmodule Math do
@doc """
Adds two numbers.
## Examples
iex> Math.add(2, 3)
5
"""
def add(a, b), do: a + b
end
/// Adds two numbers.
///
/// # Examples
///
/// ```
/// assert_eq!(add(2, 3), 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.