Stats
Actions
Tags
From documenter
**Purpose**: Extract and document how system components work, their design rationale, and practical applications. Creates comprehensive, architecturally-focused documentation similar to technical design documents.
How this skill is triggered — by the user, by Claude, or both
Slash command
/documenter:system-documentation-skillThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Purpose**: Extract and document how system components work, their design rationale, and practical applications. Creates comprehensive, architecturally-focused documentation similar to technical design documents.
Purpose: Extract and document how system components work, their design rationale, and practical applications. Creates comprehensive, architecturally-focused documentation similar to technical design documents.
When documenting a system component, follow this structure:
Goal: Understand the component thoroughly before writing.
Steps:
Tools: Use Glob, Grep, Read extensively. Don't guess—read the actual implementation.
Goal: Identify the "why" behind the "what".
Key Questions:
Goal: Write comprehensive, structured documentation.
Required Sections:
Characteristics:
Example Phrases:
Anti-patterns:
Example Phrases to Avoid:
Start Broad:
Glob (e.g., **/*orchestration*.{rb,md,json})Go Deep:
4. Read implementation files completely (don't skim)
5. Search for usage examples with Grep (e.g., how is this called?)
6. Check tests to understand expected behavior
7. Review git history for context on major decisions
Connect the Dots: 8. Map dependencies (what does this import/require?) 9. Map dependents (what imports/requires this?) 10. Identify patterns (are there multiple similar components?)
If you can't find key information:
If implementation is unclear:
# [Component Name]
**Purpose**: [1-2 sentence explanation]
**Version**: [Schema version if applicable]
**Last Updated**: [Date]
---
## Table of Contents
1. [Overview](#overview)
2. [The Core Problem This Solves](#the-core-problem-this-solves)
3. [Architecture of [Component]](#architecture-of-component)
4. [Design Principles](#design-principles)
5. [Practical Applications](#practical-applications)
6. [Implementation Details](#implementation-details)
7. [Future Enhancements](#future-enhancements)
---
## Overview
[High-level explanation of what this component is and what it enables]
**Key capabilities**:
- Capability 1
- Capability 2
- Capability 3
**Value proposition**: [Why this matters]
---
## The Core Problem This Solves
[Describe traditional/alternative approaches and their limitations]
### Problem 1: [Name]
- **What exists**: "Current state..."
- **What we need**: "Desired state..."
- **Pain point**: [Specific consequence of not having this]
### Problem 2: [Name]
- **What exists**: "Current state..."
- **What we need**: "Desired state..."
- **Pain point**: [Specific consequence of not having this]
[Continue for 3-6 problems]
**The Solution**: [1-2 sentence summary of how this component solves these problems]
---
## Architecture of [Component]
[Describe the overall structure]
### [Sub-component 1]
[Details, code examples, schema definitions]
### [Sub-component 2]
[Details, code examples, schema definitions]
---
## Design Principles
### Principle 1: [Name]
**Why**: [Rationale]
**Example**: [Code or scenario showing this principle]
**Benefit**: [What this enables]
### Principle 2: [Name]
[Continue for 5-8 principles]
---
## Practical Applications
### 1. [Use Case Name]
**Problem**: "[User question or scenario]"
**Solution**: [How to use component for this]
```ruby
# Code example
Value: [What this enables]
[Continue for 6-7 use cases]
[Deep dive into how it actually works]
[Technical details, algorithms, data structures]
[Technical details, algorithms, data structures]
Goal: [What this will enable]
Implementation:
# Code sketch
Value: [Why this matters]
[Continue for 5-7 enhancements]
[Summarize the component's role in the system]
This component enables:
[Final statement about its value and role]
path/to/doc.md - [Brief description]path/to/doc.md - [Brief description]
---
## Usage
### For Simple Components (Single File or Concept)
**Use this skill directly:**
1. Read the component's implementation
2. Follow the methodology above
3. Write documentation following the template
### For Complex Systems (Multiple Files, Components)
**Use the `/document-system` command** (if available):
/document-system
Or **use Task tool with general-purpose agent**:
Task with subagent_type: general-purpose Prompt: "Document the [component-name] system following the system-documentation-skill methodology"
---
## Examples of Good Documentation
### ✅ Example: orchestration.json Documentation
**What makes it good**:
- Starts with "The Core Problem This Solves" (6 specific problems with pain points)
- Explains design principles with rationale and examples (8 principles)
- Provides practical applications with real code (7 use cases)
- Shows implementation details with actual schemas and code
- Discusses future enhancements with implementation sketches
- Uses consistent structure throughout
**Structure used**:
1. Overview (what + why)
2. Problems (what pain does this eliminate?)
3. Architecture (how is it structured?)
4. Design Principles (why these decisions?)
5. Practical Applications (how to use it?)
6. Implementation Details (how does it work?)
7. Future Enhancements (what's next?)
---
## Anti-patterns to Avoid
### ❌ Writing Code Comments as Documentation
**Bad**:
```markdown
## OrchestrationHelpers Module
This module contains helper methods for orchestration.
### Methods
**read_agent_metadata(agent_type, artifact_path)**
- Reads metadata from agent artifacts
- Parameters: agent_type (string), artifact_path (string)
- Returns: Hash
Why it's bad: Just repeats what the code says, no insight into WHY or WHEN to use it.
Good:
## Agent Metadata System
**Purpose**: Track agent confidence, quality scores, and execution metrics to enable cost prediction and quality assessment.
**Problem**: Without this, we can't tell if low-quality outputs are due to bad specs, poor agent performance, or complexity. We also can't predict costs for similar features.
**How it works**: Each agent reports confidence (0-1) and quality_score (0-1) in their output. The orchestrator reads this metadata and aggregates it into learning signals.
### read_agent_metadata
**When to use**: After any agent completes work, call this to extract their insights.
**Example**:
```ruby
metadata = OrchestrationHelpers.read_agent_metadata('architect', plan_path)
architect_confidence = metadata.dig('agent_insights', 'confidence')
if architect_confidence < 0.7
puts "⚠️ Warning: Low architect confidence suggests unclear spec"
end
Value: Enables early intervention when quality signals are low.
### ❌ Missing "Why" and "Problem"
**Bad**:
```markdown
## Task System
The task system allows creating and updating tasks.
### Usage
```ruby
TaskCreate(...) # Creates a task
TaskUpdate(...) # Updates a task
**Why it's bad**: Doesn't explain what problem this solves or when to use it.
**Good**:
```markdown
## Task System
**Problem**: Complex multi-step work is hard to track. Users can't see progress, and we can't tell what's blocking.
**Solution**: The task system provides structured TODO tracking for orchestrations.
**When to use**:
- Features with 3+ distinct steps
- Long-running work (>30 minutes)
- When users ask "what's the status?"
**Value**:
- Users see real-time progress
- We can identify blocking issues
- Provides audit trail of what was done
### Usage
[Examples showing real scenarios]
Good system documentation:
Use this skill when:
npx claudepluginhub revans/buster-marketplace --plugin documenterCreates long-form technical documentation from existing codebases by analyzing architecture, patterns, and implementation details.
Documents a module, component, or system by automatically selecting the right document type (ADR, spec, doc, or guide) based on user intent.