document-writing-skills

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: document-writing-skills
description: Teaches document writing patterns and templates that agents apply when generating documentation, reports, contracts, guides, and technical writing. Use when creating API docs, user guides, reports, changelogs, ADRs, or technical documentation.
license: MIT
---

# Document Writing Skills

**Purpose**: This skill provides comprehensive document writing patterns, templates, and best practices that agents can apply when generating professional documentation, reports, contracts, guides, and technical writing across various domains.

## When to Use Document Writing Skills

Use this skill when:
- Creating API documentation (REST/GraphQL/RPC)
- Writing technical documentation or user guides
- Generating research reports or incident reports
- Drafting architecture decision records (ADRs)
- Creating changelogs and release notes
- Writing legal memoranda or contracts
- Producing test reports or security assessments
- Authoring product requirement documents (PRDs)

## Core Writing Principles

### 1. Clarity and Conciseness

**Guidelines**:
- Use active voice: "The system processes requests" (not "Requests are processed by the system")
- Use present tense: "The function returns" (not "The function will return")
- Be specific: "Response time: 200ms" (not "Response time is fast")
- Avoid jargon unless domain-appropriate
- Use short sentences (15-20 words maximum)
- Break complex ideas into numbered steps

**Example - Before and After**:
```
❌ Before: "It should be noted that the API endpoint might be utilized for the purpose of retrieving user data."
✅ After: "Use this endpoint to retrieve user data."
```

### 2. Progressive Disclosure Structure

Organize documents from high-level to detailed:
1. **Summary/Overview** - What and why (2-3 sentences)
2. **Key Concepts** - Essential understanding
3. **Details** - Deep-dive information
4. **Reference** - Complete specifications

**Template**:
```markdown
# Document Title

## Summary
[2-3 sentences: What this is and why it matters]

## Quick Start
[Minimal steps to get started]

## Concepts
[Essential understanding]

## Detailed Guide
[In-depth information]

## Reference
[Complete specifications, API details, etc.]
```

### 3. Consistency Standards

**Maintain consistency in**:
- Terminology (create glossary for domain terms)
- Code formatting (use syntax highlighting)
- Section structure (follow templates)
- Date formats (ISO 8601: YYYY-MM-DD)
- Version numbers (Semantic Versioning: MAJOR.MINOR.PATCH)

---

## Document Type Templates

### API Documentation

**Structure**:
```markdown
# API Endpoint: [Method] /path/to/endpoint

## Overview
[Brief description of what this endpoint does]

## Authentication
[Required authentication method]

## Request

**Method**: [GET/POST/PUT/DELETE]
**URL**: `/api/v1/endpoint`

**Headers**:
| Header | Value | Required |
|--------|-------|----------|
| Authorization | Bearer {token} | Yes |
| Content-Type | application/json | Yes |

**Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| user_id | integer | Yes | Unique user identifier |
| limit | integer | No | Max results (default: 10) |

**Request Body** (JSON):
```json
{
  "field1": "value",
  "field2": 123
}
```

## Response

**Success Response** (200 OK):
```json
{
  "status": "success",
  "data": {
    "id": 12345,
    "name": "Example"
  }
}
```

**Error Responses**:
| Status Code | Description | Response Body |
|-------------|-------------|---------------|
| 400 | Bad Request | `{"error": "Invalid parameters"}` |
| 401 | Unauthorized | `{"error": "Authentication required"}` |
| 404 | Not Found | `{"error": "Resource not found"}` |
| 500 | Server Error | `{"error": "Internal server error"}` |

## Example Usage

**cURL**:
```bash
curl -X POST https://api.example.com/v1/endpoint \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"field1": "value"}'
```

**Python**:
```py