Generate structured, digestible documentation summaries organized in markdown format. Creates comprehensive summaries covering key points, special syntax, topics, and how things work. Use when the user asks to summarize, explain, document, digest, or break down complex information about code, libraries, infrastructure, APIs, or technical topics.
Generate well-organized, digestible documentation summaries in markdown format. This skill helps you create structured documentation that makes complex topics easy to understand.
All documentation is stored in a .summary/ directory with this structure:
.summary/
├── README.md # Main table of contents
├── topic-name/ # Topic-specific folder
│ ├── overview.md # High-level summary
│ ├── key-concepts.md # Core concepts explained
│ ├── syntax-reference.md # Special syntax and patterns
│ ├── how-it-works.md # Implementation details
│ └── examples.md # Practical examples
└── another-topic/
└── ...
Before generating documentation:
.summary/ exists at the workspace rootCreate markdown files for each section of the topic. Each file should be focused and digestible (aim for 100-300 lines per file).
overview.md - High-level summary
# [Topic Name] - Overview
## Summary
Brief 2-3 paragraph summary of what this is and why it matters.
## Key Points
- Point 1: Important aspect
- Point 2: Critical feature
- Point 3: Notable characteristic
## Quick Links
- [Key Concepts](key-concepts.md)
- [Syntax Reference](syntax-reference.md)
- [How It Works](how-it-works.md)
key-concepts.md - Core concepts explained
# [Topic Name] - Key Concepts
## Concept 1: [Name]
Brief explanation of the concept.
### Details
- Detailed point 1
- Detailed point 2
### When to Use
Practical guidance on when this concept applies.
---
## Concept 2: [Name]
...
syntax-reference.md - Special syntax and patterns (if applicable)
# [Topic Name] - Syntax Reference
## Basic Syntax
### Pattern 1
\`\`\`language
code example
\`\`\`
**Explanation**: What this does and when to use it.
### Pattern 2
...
## Special Cases
Document any edge cases or special syntax variations.
how-it-works.md - Implementation details and internals
# [Topic Name] - How It Works
## Architecture
Explain the overall architecture or flow.
## Step-by-Step Process
1. **Step 1**: What happens first
2. **Step 2**: What happens next
3. **Step 3**: Final result
## Under the Hood
Technical details about implementation.
## Gotchas and Considerations
- Gotcha 1: What to watch out for
- Gotcha 2: Common mistake to avoid
examples.md - Practical examples
# [Topic Name] - Examples
## Example 1: [Use Case]
**Scenario**: Describe the use case
\`\`\`language
code example
\`\`\`
**Explanation**: What this example demonstrates.
---
## Example 2: [Use Case]
...
Create additional files as needed:
advanced-usage.md - Advanced patterns and techniquestroubleshooting.md - Common issues and solutionscomparison.md - Comparisons with alternativesmigration.md - Migration guidesbest-practices.md - Recommended patternsAfter creating topic documentation, update .summary/README.md:
# Documentation Summary
This directory contains structured, digestible documentation summaries.
## Topics
### [Topic Name 1](topic-name-1/)
Brief one-line description of this topic.
**Contents:**
- [Overview](topic-name-1/overview.md) - High-level summary
- [Key Concepts](topic-name-1/key-concepts.md) - Core concepts
- [Syntax Reference](topic-name-1/syntax-reference.md) - Special syntax
- [How It Works](topic-name-1/how-it-works.md) - Implementation details
- [Examples](topic-name-1/examples.md) - Practical examples
---
### [Topic Name 2](topic-name-2/)
Brief one-line description of this topic.
**Contents:**
...
Split content into multiple files when:
Example: Large library documentation
library-name/
├── overview.md
├── getting-started.md # Split from overview
├── core-concepts.md
├── api-authentication.md # Split from syntax
├── api-endpoints.md # Split from syntax
├── data-models.md # Split from how-it-works
├── error-handling.md # Split from how-it-works
└── examples/ # Subdirectory for many examples
├── basic-usage.md
├── advanced-patterns.md
└── real-world-scenarios.md
terraform-modules, api-gateway)getting-started.md, api-reference.md)Use relative links to connect related documentation:
For more details on authentication, see [API Authentication](api-authentication.md).
Related topics:
- [Error Handling](error-handling.md)
- [Data Models](data-models.md)
Write for human understanding:
Use hierarchical headers for easy scanning:
# Main Topic
## Major Section
### Subsection
#### Detail Point
Always show practical examples with explanations:
### Example: User Authentication
\`\`\`python
@app.route('/login', methods=['POST'])
def login():
username = request.json.get('username')
password = request.json.get('password')
if authenticate_user(username, password):
return jsonify({'token': generate_token(username)})
return jsonify({'error': 'Invalid credentials'}), 401
\`\`\`
**Key Points:**
- The `authenticate_user()` function validates credentials
- Successful login returns a JWT token
- Failed attempts return 401 status code
Use blockquotes for important notes:
> **Important**: Always validate user input before processing to prevent security vulnerabilities.
> **Note**: This feature requires version 2.0 or higher.
Use horizontal rules to separate major sections:
## Section 1
Content...
---
## Section 2
Content...
When updating existing documentation:
When documenting infrastructure:
When documenting APIs:
When documenting libraries:
When documenting codebases:
Here's a complete example for documenting a fictional API:
User Request: "Summarize our payment processing API"
Your Response:
.summary/
└── payment-api/
├── overview.md
├── authentication.md
├── endpoints.md
├── data-models.md
├── error-handling.md
└── examples.md
.summary/README.md with the new topicBefore completing the documentation:
When the user asks you to summarize or document something, follow this workflow to create organized, digestible documentation in the .summary/ directory.