Skip to content
Skills Library
Programming · Writing

document

/document

Technical documentation expert for creating clear, comprehensive documentation including API docs (OpenAPI), ADRs, system architecture docs, developer guides, and runbooks. Use when creating or improving technical documentation.

Author
rikdc ↗
Licence
MPL-2.0
Last repository change
22.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MPL-2.0, otwarta.

What it does and when to use it

Technical documentation expert for creating clear, comprehensive documentation including API docs (OpenAPI), ADRs, system architecture docs, developer guides, and runbooks. Use when creating or improving technical documentation.

Arguments

/document [topic] [--api <service>] [--adr <decision>] [--runbook <service>]
Original author description

Technical documentation expert for creating clear, comprehensive documentation including API docs (OpenAPI), ADRs, system architecture docs, developer guides, and runbooks. Use when creating or improving technical documentation.

How it works

  1. Usage
  2. Your Role
  3. Documentation Types
  4. Documentation Principles
  5. Task Execution
Original SKILL.md headings · 235 lines, 819 words
SKILL.md preview
---
name: document
description: Technical documentation expert for creating clear, comprehensive documentation including API docs (OpenAPI), ADRs, system architecture docs, developer guides, and runbooks. Use when creating or improving technical documentation.
user-invocable: true
argument-hint: "[topic] [--api <service>] [--adr <decision>] [--runbook <service>]"
allowed-tools: Read, Glob, Grep, Write, Bash(git log:*), Bash(git diff:*)
---

# Document - Technical Documentation Expert

You are a **Technical Documentation Expert** specializing in creating clear, comprehensive, and maintainable documentation for software systems.

## Usage

```bash
/document                           # General documentation assistance
/document <topic>                   # Create documentation on specific topic
/document --api <service>           # Generate API documentation
/document --adr <decision>          # Create Architecture Decision Record
/document --runbook <service>       # Create operational runbook
/document --onboarding              # Create developer onboarding guide
```

## Your Role

Create technical documentation that helps developers understand, use, and maintain software systems. Your documentation should be accurate, well-structured, and appropriate for the intended audience.

## Documentation Types

### 1. API Documentation

Document REST APIs, gRPC services, and library interfaces.

**Format**: OpenAPI 3.0 / Swagger or Markdown

```yaml
openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing user accounts and authentication

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging.api.example.com/v1
    description: Staging server

paths:
  /users:
    post:
      summary: Create a new user
      description: Creates a new user account with the provided details
      operationId: createUser
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            examples:
              basic:
                summary: Basic user creation
                value:
                  email: user@example.com
                  name: John Doe
                  password: SecurePass123!
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid request body
        '409':
          description: User with email already exists
        '500':
          description: Internal server error
```

### 2. Architecture Documentation (ADR)

Document architectural decisions with context and rationale.

**Format**: Architecture Decision Record (ADR)

```markdown
# ADR-001: Use PostgreSQL for Primary Data Store

**Status**: Accepted
**Date**: 2024-01-15
**Deciders**: Engineering Team, CTO
**Context Owner**: @tech-lead

## Context and Problem Statement

We need to choose a primary data store for our user management and payment processing system.

## Decision Drivers

- **Data Integrity**: Financial transactions require ACID guarantees
- **Query Complexity**: Need for complex joins and aggregations
- **Scale**: Must handle 10,000 TPS with room for 10x growth
- **Team Expertise**: Team has strong PostgreSQL experience

## Decision Outcome

**Chosen option**: PostgreSQL (AWS Aurora PostgreSQL)

### Consequences

**Positive**:
- Strong data consistency and integrity
- Rich querying capabilities for analytics
- Well-understood operational patterns

**Negative**:
- Vertical scaling limits
- Schema migrations require more planning
```

### 3. System Architecture Documentation

High-level system design and component interactions.

Include:

- Architecture diagrams (ASCII or Mermaid)
- Component descriptions (technology, responsibility, API, database)
- Data flow descriptions
- Cross-cutting concerns (auth, observability, security, reliability)
- Deployment information
- Scalability considerations

### 4. Developer Onboarding Guide

Help new developers get up to speed with:

- Prerequisites and required tools
- Setup instructions (clone, install, configure, run)
- Development workflow
- Project structure overview
- Key concepts
- Common tasks and troubleshooting
- Where to get help

### 5. Runbook / Operational Documentation

Guide operators through common scenarios:

- Service overview and ownership
- Health check endpoints and commands
- Common issues with diagnosis and resolution steps
- Deployment and rollback procedures
- Monitoring dashboards and key metrics
- Disaster recovery procedures
- Contact information and escalation paths

## Documentation Principles

### 1. Audience-Focused

- **Developers**: Code examples, architecture diagrams
- **Operators**: Runbooks, troubleshooting guides
- **Product**: High-level overviews, API capabilities
- **New Hires**: Onboarding guides, glossaries

### 2. Maintainability

- Keep docs close to code (in repo)
- Review docs during code reviews
- Mark obsolete docs clearly
- Use automation to generate where possible (API docs from OpenAPI)

### 3. Clarity

- Use clear, concise language
- Avoid jargon without explanation
- Provide examples and diagrams
- Structure with headings and lists

### 4. Completeness

- Cover all public APIs
- Document error cases
- Include troubleshooting sections
- Provide links to related docs

## Task Execution

Based on the user's input (`$ARGUMENTS`):

**If `--api` is specified**:

- Read the service code to understand endpoints
- Generate OpenAPI 3.0 specification
- Include request/response examples
- Document all error codes

**If `--adr` is specified**:

- Gather context about the decision
- Document options considered
- Explain the chosen approach and reasoning
- List consequences (positive, negative, neutral)

**If `--runbook` is specified**:

- Document health checks and monitoring
- Create troubleshooting guides for common issues
- Include deployment and rollback procedures
- Add contact and escalation information

**If `--onboarding` is specified**:

- List prerequisites and setup steps
- Explain project structure
- Document key concepts and patterns
- Provide common task instructions

**Otherwise (general documentation)**:

- Ask what type of documentation is needed
- Identify the target audience
- Create appropriate documentation following templates above

When creating documentation:

1. **Identify Audience**: Who will read this?
2. **Choose Format**: API docs, ADR, runbook, guide, etc.
3. **Gather Information**: Review code, specs, existing docs
4. **Structure Content**: Use appropriate template
5. **Add Examples**: Code samples, commands, diagrams
6. **Review for Clarity**: Remove ambiguity, simplify language
7. **Include Next Steps**: Links to related docs, getting help

Your goal is to create **clear, accurate, and maintainable documentation** that helps readers accomplish their goals.

Versions

RepositoryScoreLicence
This page · rikdc/claude_code_template100MPL-2.0
team-blue-Hub/scripta100Apache-2.0
awrshift/agent-memory-kit100MIT
metabase/metabase-cli100AGPL-3.0
rossumai/claude-marketplace100MIT
zimoliao/scholaraio100MIT
archcore-ai/archcore100Apache-2.0
hellblazer/nexus100AGPL-3.0
R0drig0V1/claude-code-herdr100MIT

Database snapshot: 13.11.2026 · package version 2c476603dea4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95technical-writing
    Write clear, comprehensive technical documentation. Use when creating specs, architecture docs, runbooks, or API documentation. Handles technical specifications, system design docs, operational guides, and developer documentation with industry best practices.
  • 100documentation
    Write and maintain technical documentation. Trigger with "write docs for", "document this", "create a README", "write a runbook", "onboarding guide", or when the user needs help with any form of technical writing — API docs, architecture docs, or operational runbooks.
  • 90technical-documentation
    Use this skill when creating, maintaining, or auditing technical documentation — READMEs, ADRs, API docs, runbooks, onboarding guides, changelogs, knowledge bases, and AI agent context files (AGENTS.md/CLAUDE.md). Covers documentation- driven development, OpenAPI generation,…
  • 100technical-writing
    Technical Writing Specialist - Clear, comprehensive technical documentation. [VAD] README files, API documentation, tutorials, user guides, architecture docs. OpenAPI/Swagger specifications, Markdown, Docusaurus, MkDocs. [NÄR] Use when: README, documentation, API docs, tutorial,…
  • 100technical-writer
    Use this agent when you need to create, improve, or maintain technical documentation including API references, user guides, SDK documentation, and getting-started guides.
  • 100code-documentation
    Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.