Plugin documenter

Plugin Documenter

The best plugin documentation answers three questions in this order: what problem does this solve, how do I install it, and what can I do with it. Everything else is reference material that users look up after they've decided to install. This skill enforces that order.

---

When to use this skill

• You found a Claude Code plugin on GitHub and want to understand what it does
• You built a plugin and need to write or rewrite its README
• You're evaluating whether to install a plugin and want a thorough breakdown first
• You want to generate a tutorial for a plugin you or someone else authored
• You need to document a plugin for a team that will be using it

When NOT to use this skill

• Building a new plugin → use plugin-architecture + plugin-composition
• Validating plugin structure → use plugin-validation
• Evaluating activation quality → use plugin-evaluation
• Writing a single SKILL.md → use skill-creator

---

How to invoke

/plugin-dev:plugin-documenter https://github.com/user/repo/tree/main/plugin-name

Or for a local plugin:

/plugin-dev:plugin-documenter ./path/to/plugin

Or natural language:

Document the plugin at https://github.com/user/repo
Write detailed docs for the cloud-finops plugin

---

The documentation process

Step 1 — Fetch and inventory

Inventory all plugin files. For GitHub URLs, use web-fetch or git clone. For local paths, use glob/ls.

Do NOT read every file yet. Step 1 is inventory only — listing paths and sizes. Deep reads happen selectively in later steps to control token usage.

Files to inventory:

File	Required	Read depth
.claude-plugin/plugin.json	Yes	Full (small)
README.md	Yes	Full
CHANGELOG.md	If present	Full (version history)
skills/*/SKILL.md	Yes	Full — frontmatter + body
skills/*/references/*.md	If present	Title + first blockquote only (see token strategy below)
skills/*/evals/trigger-evals.json	If present	Count cases only (jq length)
skills/*/evals/evals.json	If present	Count cases only
skills/*/templates/	If present	List filenames
skills/*/examples/	If present	List filenames
skills/*/scripts/	If present	List filenames
skills/*/fixtures/	If present	List filenames
hooks/hooks.json	If present	Full (small)
hooks/scripts/*.sh	If present	First 5 lines of each
.mcp.json	If present	Full (small)
agents/*.md	If present	Frontmatter only
commands/*.md	If present	First 10 lines
scripts/*.py or scripts/*.sh	If present	First 10 lines + --help if available

Output: a file inventory table with path, type, line count, and read-depth note.

Token efficiency strategy

The rule: read structure first, content on demand.

1. Always read fully: plugin.json, SKILL.md files, hooks.json, .mcp.json, CHANGELOG.md
2. Read selectively: reference files — read only the title and opening blockquote
3. Read on demand: deep-read specific references only when needed for scenarios
4. Never read: test fixtures, example skill bodies, large script implementations
5. Count, don't read: eval files — report counts without reading queries

For a plugin with N reference files:

• N=0-5: read all references fully (small plugin)
• N=6-15: read titles + blockquotes, deep-read 2-3 most important
• N=16+: read titles only, deep-read on demand for scenarios

Step 2 — Analyze architecture

From the inventory, determine:

1. Plugin shape — single-skill, multi-skill, hooks-only, composed (skills + hooks + MCP)?
2. Component count — how many skills, hooks, MCP tools, subagents, commands?
3. Component relationships — which skills reference each other? Do hooks complement specific skills?
4. Progressive disclosure structure — how deep is the reference tree?
5. Scripts and tooling — what runnable tools does the plugin ship?

Output: an architecture summary with a component diagram (text-based).

Step 3 — Extract the problem statement

Read ALL skill descriptions (frontmatter) and the plugin.json description. Synthesize:

• What problem does this plugin solve? — in plain language
• Who is it for? — what kind of user benefits
• What does the world look like WITHOUT this plugin? — the pain
• What does the world look like WITH it? — the outcome

Do NOT copy the frontmatter description verbatim. The frontmatter is written for Claude's activation engine. The problem statement is written for humans deciding whether to install.

Step 4 — Write "How to Use" with prompt templates

For EACH skill in the plugin, produce a practical usage section with:

1. What it does — one paragraph in plain language
2. Prompt templates — 3-5 copy-pasteable prompts showing different angles:

### How to Use: [skill-name]

**What it does:** [plain language explanation]

**Try these prompts:**

Help me design a REST API for a bookstore inventory with CRUD operations

Review my API — I'm not sure about the pagination approach

What's the best error response format for a public API?

Rules for prompt templates:

• Show the user's actual words, not the skill name
• Vary the intent: starting fresh, reviewing, specific sub-topic, troubleshooting
• Include context where it helps
• Never include skill invocation syntax — the skill activates from natural language

Step 5 — Map realistic use-case scenarios

Read the frontmatter trigger phrases, SKILL.md body, references, and evals. Construct 3-5 realistic scenarios per skill:

#### Scenario: Migrating a monolith to microservices

**Context:** You're breaking a Rails monolith into services and need to design
the inter-service API contracts before coding anything.

**You say:** "Help me design the API contracts between our user service and
order service — we need to handle auth tokens and eventual consistency"

**The skill provides:**
- Resource decomposition following REST conventions
- Auth token propagation patterns

**You end up with:** A documented API contract with schemas, error codes, and sequence diagrams.

Scenarios must be specific and grounded — tied to a real situation a developer/PM/designer would recognize.

Step 6 — Write installation instructions

From the plugin.json and the plugin's location:

## Installation

Add the marketplace and install:

/plugin marketplace add OWNER/REPO /plugin install PLUGIN-NAME@MARKETPLACE-ID

### Prerequisites

[List any dependencies]

### Verify installation

After installing, test with:

[A realistic query that should trigger the plugin's primary skill]

Step 7 — Generate the documentation package

The document follows a 4-layer competence model. Every layer is mandatory.

Layer 1: Awareness     → Title Card + Problem + Solution
Layer 2: Mental Model  → System Map + Component Spotlights
Layer 3: Execution     → Walkthrough + Prompt Patterns
Layer 4: Mastery       → Decision Logic + Edge Cases + Integration Patterns

Sections marked (lean) can be shortened for simple single-skill plugins. Sections marked (power) can be omitted for plugins with fewer than 3 components.

---

LAYER 1 — AWARENESS

# [Plugin Name]

> [One-sentence value proposition — what problem, for whom]
> [Visual hint: N skills, N hooks, N scripts]

## The Problem

[2-3 paragraphs. Describe the pain BEFORE this plugin exists. Be specific:
what goes wrong, how much time is wasted, what mistakes are made. Not "X is hard"
but "without this, teams spend 3 hours doing Y manually and still get Z wrong 40% of the time."]

## The Solution

[2-3 paragraphs. What changes WITH this plugin. Concrete outcomes, not
aspirational claims.]

## Before vs After

| Without this plugin | With this plugin |
|---|---|
| [Pain 1] | [Fix 1] |
| [Pain 2] | [Fix 2] |
| [Pain 3] | [Fix 3] |
| [Pain 4] | [Fix 4] |
| [Pain 5] | [Fix 5] |

## Installation

[Copy-pasteable commands from Step 6]

## Quick Start

[The fastest path to seeing value. 3-5 numbered steps]

---

LAYER 2 — MENTAL MODEL

## System Overview

[Text diagram or table showing components and data flow between them]

## What's Inside

[Component inventory table]

### Component Spotlights

[Repeat for EACH component type:]

#### [Skill Name] (skill)

**What it does:** [plain language]
**Input → Output:** [What user provides → what skill produces]
**When to use:** [specific triggers]
**When NOT to use:** [anti-triggers + what to use instead]

**Try these prompts:**

[Prompt 1 — starting fresh]

[Prompt 2 — reviewing existing work]

[Prompt 3 — specific sub-topic]

**Key references:** [summary table]

#### [Hook Name] (hook)

**Trigger:** [event + matcher]
**What it does:** [concrete behavior]
**Side effects:** [what changes]

#### [Script Name] (script)

**CLI:** `command --flags`
**What it produces:** [output format]
**Typical workflow:** [when you'd run this]

---

LAYER 3 — EXECUTION

## Prompt Patterns

### Good Prompts vs Bad Prompts

| Bad (vague) | Good (specific) |
|---|---|
| "[vague query]" | "[specific query with context]" |

### Prompt Anti-Patterns

- [Anti-pattern 1: what people type that doesn't work, and why]
- [Anti-pattern 2]
- [Anti-pattern 3]

## Real-World Walkthrough

[ONE detailed end-to-end example. 500-1000 words. Show the full system in action.
Structure: Starting situation → Steps 1-N → Final outcome → Gotchas discovered]

## Usage Scenarios

### Scenario 1: [Descriptive title]

**Context:** [The user's situation]
**You say:** "[Exact prompt]"
**The skill provides:** [Bullet list of outputs]
**You end up with:** [Concrete deliverable]

---

LAYER 4 — MASTERY

## Decision Logic

[When does component A activate vs B?]

## Failure Modes & Edge Cases

| Failure | Symptom | Recovery |
|---|---|---|
| [Error 1] | [What user sees] | [How to fix] |

## Anti-Patterns

- [Overusing the skill when a simpler approach works]
- [Misplacing logic]
- [Poor orchestration between components]

## Ideal For

- [User type 1 + rationale]
- [User type 2 + rationale]

## Not For

- [Anti-use-case + what to use instead]

## Related Plugins

[Cross-references to complementary plugins]

---

Minimal Viable Set (for lean plugins)

Single skill with few references — use this reduced set:

• Title Card + Problem + Solution (Layer 1)
• 1 Component Spotlight with prompt templates (Layer 2)
• Real-World Walkthrough + Prompt Patterns (Layer 3)
• Ideal For / Not For (Layer 4 minimal)

---

Step 8 — Quality check

Before delivering, verify:

Layer 1: Problem describes real pain, Before vs After >=5 rows, Quick Start <=5 steps, installation is copy-pasteable Layer 2: System overview shows relationships, every component has a spotlight, every skill has >=4 prompt templates Layer 3: Good vs Bad prompt table present, >=3 prompt anti-patterns, Walkthrough 500+ words, >=3 usage scenarios Layer 4: Decision logic documented, failure modes >=3, Ideal For >=4, Not For >=3, no frontmatter copy-pasted as prose

---

Anti-patterns

1. Copy-pasting frontmatter as documentation prose — frontmatter is for Claude's activation engine, not for human readers. Rewrite in plain language.
2. Documenting every reference file's content in the README — reference files exist for progressive disclosure; summarize them in a table, don't reproduce them.
3. Writing scenarios that say "user asks about X and gets an answer" — scenarios must describe a real situation with context, not a generic query-response.
4. Skipping the problem statement — jumping straight to features without establishing why the reader should care.
5. Including skill invocation syntax in prompts — users type natural language, not /plugin:skill-name. Document how people actually talk.
6. Reading all files into context before analyzing — this wastes tokens and degrades output. Follow the token efficiency strategy.

---

Output format

By default, the documentation is written as a replacement for the plugin's README.md. If the user requests a different format (tutorial, wiki page, blog post), adapt the structure but keep the same content order: problem → install → what's inside → scenarios → reference.

---

References

This skill uses the analysis framework from plugin-architecture (component decision matrix) and the structural knowledge from plugin-validation (what a valid plugin looks like) to inform its documentation. It does not duplicate those skills — it applies their frameworks to produce human-readable documentation.

---

Plugin-Dev Authoring Toolkit by Viktor Bezdek — licensed under MIT.