doc-manager

name	doc-manager
description	Creates and updates markdown documentation with clear explanations and code examples for complex concepts. Use when the user needs to generate technical documentation, update existing docs, or explain concepts with practical examples.
license	MIT
metadata	{"author":"agent-skills-poc","version":"1.0","category":"documentation"}

Documentation Manager Skill

This skill creates and maintains markdown documentation with clear explanations and code examples.

When to Use

Use this skill when:

• The user needs to create new documentation files
• Existing documentation needs to be updated
• Complex concepts require explanation with code examples
• Technical documentation needs to be written or maintained
• The user mentions terms like "document", "create docs", "update documentation", "add examples", "explain with code"

Instructions

Step 1: Identify the Documentation Goal

Determine what needs to be documented:

• New documentation: Creating a new markdown file from scratch
• Update existing: Modifying or extending existing documentation
• Add examples: Inserting code examples for complex concepts
• Clarify concepts: Improving explanations of difficult topics

Step 2: Structure the Document

Organize the documentation with clear sections:

1. Title: Clear, descriptive heading
2. Overview: Brief introduction explaining what is being documented
3. Main Content: Detailed explanations organized by topic
4. Code Examples: Practical examples for complex concepts
5. Additional Resources: Links or references if applicable

Step 3: Write Clear Explanations

For each concept:

1. Start with a simple definition
2. Explain why it's important or when to use it
3. Break down complex ideas into smaller parts
4. Use analogies or comparisons when helpful
5. Highlight key points or gotchas

Step 4: Add Code Examples for Complex Concepts

When a concept is complex:

1. Identify complexity indicators:

   • Abstract or theoretical concepts
   • Multi-step processes
   • Technical implementations
   • Configuration or setup procedures

2. Create relevant code examples:

   • Use realistic, practical scenarios
   • Include comments explaining key parts
   • Show both basic and advanced usage
   • Demonstrate common patterns and best practices

3. Format code properly:

   • Use appropriate language syntax highlighting
   • Keep examples concise but complete
   • Include expected output when relevant

Step 5: Review and Validate

Before finalizing:

1. Check that all sections are present
2. Verify code examples are correct and runnable
3. Ensure explanations are clear and concise
4. Confirm markdown formatting is proper
5. Add table of contents for longer documents

Examples

Example 1: Creating New API Documentation

Input: "Document our user authentication API endpoint"

Steps:

1. Goal: Create new documentation
2. Structure sections: Overview, Endpoint Details, Request/Response, Examples
3. Write explanations for authentication flow
4. Add code examples (complex concept)

Output:

# User Authentication API

## Overview
This endpoint handles user authentication and returns a JWT token for authorized access.

## Endpoint
`POST /api/auth/login`

## Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User's email address |
| password | string | Yes | User's password |

## Response
Returns a JSON object with authentication token and user details.

## Example Usage

### JavaScript (Fetch API)
```javascript
// Login request
const response = await fetch('https://api.example.com/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: '[e-mail]',
    password: 'securePassword123'
  })
});

const data = await response.json();
console.log(data.token); // JWT token for subsequent requests

Python (Requests)

import requests

# Login request
response = requests.post(
    'https://api.example.com/api/auth/login',
    json={
        'email': '[e-mail]',
        'password': 'securePassword123'
    }
)

data = response.json()
print(data['token'])  # JWT token for subsequent requests

Success Response (200 OK)

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "12345",
    "email": "[e-mail]",
    "name": "John Doe"
  }
}

Error Response (401 Unauthorized)

{
  "success": false,
  "error": "Invalid credentials"
}

### Example 2: Updating Existing Documentation

**Input:** "Update the React hooks documentation to include useCallback example"

**Steps:**
1. Goal: Update existing documentation
2. Locate the hooks section
3. Identify useCallback as complex (requires understanding of memoization)
4. Add detailed explanation with code example

**Output:** (Addition to existing doc)
```markdown
### useCallback Hook

The `useCallback` hook returns a memoized callback function. This is useful for optimizing performance by preventing unnecessary re-renders of child components that depend on callback functions.

**When to use:**
- Passing callbacks to optimized child components
- Preventing function recreation on every render
- Maintaining referential equality for dependencies

**Syntax:**
```javascript
const memoizedCallback = useCallback(
  () => {
    // callback logic
  },
  [dependencies]
);

Example: Optimizing Child Component Renders

import React, { useState, useCallback } from 'react';

function ParentComponent() {
  const [count, setCount] = useState(0);
  const [otherState, setOtherState] = useState('');

  // Without useCallback: function recreated on every render
  // const handleClick = () => {
  //   console.log('Button clicked');
  // };

  // With useCallback: function only recreated when dependencies change
  const handleClick = useCallback(() => {
    console.log('Button clicked, count is:', count);
  }, [count]); // Only recreate when count changes

  return (
    <div>
      <ChildButton onClick={handleClick} />
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
      <input 
        value={otherState} 
        onChange={(e) => setOtherState(e.target.value)} 
      />
    </div>
  );
}

// Memoized child component only re-renders when props change
const ChildButton = React.memo(({ onClick }) => {
  console.log('ChildButton rendered');
  return <button onClick={onClick}>Click me</button>;
});

Key Points:

• Dependencies array works like useEffect
• Empty array [] means callback never changes
• Omitting dependencies array defeats the purpose
• Use with React.memo for maximum benefit

### Example 3: Documenting a Complex Algorithm

**Input:** "Document the binary search algorithm implementation"

**Steps:**
1. Goal: Create new documentation
2. Identify as complex (requires understanding of divide-and-conquer)
3. Structure: Overview, How it Works, Implementation, Complexity
4. Add multiple code examples with explanations

**Output:**
```markdown
# Binary Search Algorithm

## Overview
Binary search is an efficient algorithm for finding a target value within a sorted array. It works by repeatedly dividing the search interval in half.

## How It Works

1. Start with the middle element of the sorted array
2. If the target equals the middle element, return its position
3. If the target is less than the middle element, search the left half
4. If the target is greater than the middle element, search the right half
5. Repeat until the target is found or the search space is empty

**Time Complexity:** O(log n)  
**Space Complexity:** O(1) iterative, O(log n) recursive

## Implementation Examples

### JavaScript (Iterative)
```javascript
/**
 * Binary search implementation (iterative)
 * @param {number[]} arr - Sorted array of numbers
 * @param {number} target - Value to search for
 * @returns {number} Index of target, or -1 if not found
 */
function binarySearch(arr, target) {
  let left = 0;
  let right = arr.length - 1;

  while (left <= right) {
    // Calculate middle index (avoid overflow)
    const mid = Math.floor(left + (right - left) / 2);

    if (arr[mid] === target) {
      return mid; // Found the target
    } else if (arr[mid] < target) {
      left = mid + 1; // Search right half
    } else {
      right = mid - 1; // Search left half
    }
  }

  return -1; // Target not found
}

// Example usage
const numbers = [1, 3, 5, 7, 9, 11, 13, 15, 17, 19];
console.log(binarySearch(numbers, 7));  // Output: 3
console.log(binarySearch(numbers, 10)); // Output: -1

Python (Recursive)

def binary_search_recursive(arr, target, left=0, right=None):
    """
    Binary search implementation (recursive)
    
    Args:
        arr: Sorted list of numbers
        target: Value to search for
        left: Left boundary index
        right: Right boundary index
    
    Returns:
        Index of target, or -1 if not found
    """
    if right is None:
        right = len(arr) - 1
    
    # Base case: search space is empty
    if left > right:
        return -1
    
    # Calculate middle index
    mid = left + (right - left) // 2
    
    if arr[mid] == target:
        return mid
    elif arr[mid] < target:
        # Search right half
        return binary_search_recursive(arr, target, mid + 1, right)
    else:
        # Search left half
        return binary_search_recursive(arr, target, left, mid - 1)

# Example usage
numbers = [1, 3, 5, 7, 9, 11, 13, 15, 17, 19]
print(binary_search_recursive(numbers, 7))   # Output: 3
print(binary_search_recursive(numbers, 10))  # Output: -1

Visualization

Array: [1, 3, 5, 7, 9, 11, 13, 15, 17, 19]
Target: 7

Step 1: [1, 3, 5, 7, 9, 11, 13, 15, 17, 19]
                    ^
        mid = 9, target < 9, search left

Step 2: [1, 3, 5, 7, 9]
             ^
        mid = 5, target > 5, search right

Step 3: [7, 9]
         ^
        mid = 7, target == 7, found at index 3!

When to Use Binary Search

✅ Use when:

• Array is sorted
• Need O(log n) search performance
• Working with large datasets
• Random access is available

❌ Don't use when:

• Array is unsorted (sort first or use linear search)
• Linked lists (no random access)
• Very small arrays (linear search is simpler)

## Common Edge Cases

- **Empty documentation**: Start with a clear template structure
- **Missing context**: Ask clarifying questions before writing
- **Overly complex examples**: Break into smaller, digestible pieces
- **Outdated information**: Verify accuracy before updating
- **Inconsistent formatting**: Follow markdown best practices
- **Missing code language tags**: Always specify language for syntax highlighting
- **Incomplete examples**: Ensure code is runnable and includes necessary imports

## Code Example Guidelines

### When to Add Code Examples

Add code examples when documenting:
- API endpoints or interfaces
- Algorithms or complex logic
- Configuration or setup procedures
- Design patterns or architectural concepts
- Framework-specific features
- Error handling scenarios
- Performance optimization techniques

### Code Example Best Practices

1. **Keep it relevant**: Examples should directly relate to the concept
2. **Make it runnable**: Include all necessary imports and setup
3. **Add comments**: Explain non-obvious parts
4. **Show output**: Include expected results when helpful
5. **Use multiple languages**: Provide examples in common languages when applicable
6. **Progressive complexity**: Start simple, then show advanced usage
7. **Real-world scenarios**: Use practical, relatable examples

## Markdown Formatting Tips

- Use `#` for main title, `##` for sections, `###` for subsections
- Use code fences with language tags: ` ```javascript `, ` ```python `
- Use tables for structured data
- Use blockquotes `>` for important notes or warnings
- Use lists for steps or bullet points
- Use **bold** for emphasis, `inline code` for technical terms
- Add horizontal rules `---` to separate major sections

## Tips

- Always use markdown format for all documentation
- Structure documents with clear hierarchy
- Add table of contents for documents longer than 5 sections
- Include "Last Updated" date for maintenance tracking
- Use consistent terminology throughout
- Link to related documentation when relevant
- Add code examples for any concept that requires more than 2 paragraphs to explain
- Test all code examples before including them
- Consider your audience's technical level
- Use diagrams or ASCII art for visual concepts when helpful