Documentation Structure Skill

Documentation Structure

This skill defines how documentation is organized and maintained in this repository.

Core Principles

| Principle | Description | |-----------|-------------| | Separation of Concerns | README (landing), docs/ (reference), CONTRIBUTING (dev workflow) | | Single Source of Truth | Define once, link everywhere. Never duplicate content. | | Hub-and-Spoke | docs/README.md is the central navigation hub | | Vendor Isolation | Each AI platform gets its own directory in docs/ |

Document Responsibilities

User vs Developer Content Separation

CRITICAL RULE: User documentation must ONLY contain fully automated installation methods. All manual setup belongs in developer documentation.

| Content Type | User Docs | Developer Docs | |--------------|-----------|----------------| | Marketplace install | ✓ | ✓ | | One-command GitHub install | ✓ | ✓ | | git clone | ✗ | ✓ | | --plugin-dir | ✗ | ✓ | | extensions link | ✗ | ✓ | | JSON config editing | ✗ | ✓ | | Local path setup | ✗ | ✓ | | mcp_settings.json | ✗ | ✓ |

User Documentation (README.md, docs/*/overview.md)

Installation must be copy-paste simple
Single command or UI-only steps
Link to dev docs for manual alternatives

Developer Documentation (CONTRIBUTING.md, docs//-development.md)

All manual setup workflows
Local testing procedures
Configuration file editing
Environment setup

README.md (Landing Page)

Purpose: First impression. Get users started quickly.

Must include:

One-line description
Quick Start (4 steps: Choose → Install → Authenticate → Try)
Capability tables (what users can do)
Links to docs/ for details

Must NOT include:

Full API reference (→ docs/mcp/)
Development workflows (→ CONTRIBUTING.md)
Detailed architecture (→ docs/)

docs/ (Reference Documentation)

Purpose: Complete reference for users and developers.

Structure:

docs/
├── README.md              # Navigation hub
├── troubleshooting.md     # Cross-platform issues
├── getting-started/       # Entry points
│   ├── mcp-setup.md       # Generic MCP config
│   └── enterprise.md      # Admin requirements
├── claude-code/           # Vendor: Claude Code
├── kiro/                  # Vendor: Kiro
├── gemini-cli/            # Vendor: Gemini CLI
└── mcp/                   # Protocol reference
    ├── tools-reference.md
    └── tutorials.md

CONTRIBUTING.md (Development Workflow)

Purpose: How to modify THIS repository.

Must include:

Clone and local dev setup
How to test changes locally (--plugin-dir, etc.)
Validation checklists
PR process

Must NOT include:

Full plugin/power architecture (→ docs/)
User-facing tutorials (→ docs/)

Vendor Documentation Standards

Each vendor directory in docs/ follows this pattern:

Required Files

| File | Purpose | |------|---------| | overview.md | What is this integration, why use it, installation | | *-development.md | How to build new plugins/powers/extensions | | Individual component docs | One file per plugin/power |

Standard Sections in overview.md

## What are [Plugins/Powers/Extensions]?
## Why Use [Plugins/Powers] vs Direct MCP?
## Available [Plugins/Powers]
## Installation
## Authentication
## Related

Vendor-Specific Metadata

| Vendor | Config Format | Location | |--------|--------------|----------| | Claude Code | plugin.json | .claude-plugin/plugin.json | | Kiro | POWER.md frontmatter | POWER.md | | Gemini CLI | JSON extension | gemini-extension.json |

Cross-Reference Patterns

Link Format

Within docs/: Use relative paths [text](../mcp/tools-reference.md)
From README to docs/: Use docs/ prefix [text](docs/claude-code/overview.md)
External links: Full URLs [text](https://developers.miro.com)

Required "Related" Section

Every doc file should end with a Related section:

## Related

- [Overview](overview.md) - Introduction to this integration
- [Tools Reference](../mcp/tools-reference.md) - MCP tool documentation

Reciprocal Links

If doc A links to doc B, doc B should link back to doc A in its Related section.

Validation Guidelines

Before committing documentation changes:

Content Checks

[ ] No duplicated content (link instead)
[ ] Correct document owns the content (README vs docs/ vs CONTRIBUTING)
[ ] All sections present per vendor standards

Link Checks

[ ] All internal links resolve
[ ] Related sections have reciprocal links
[ ] External links use HTTPS

Format Checks

[ ] Code blocks have language specified
[ ] Tables have consistent formatting
[ ] Collapsibles have matching tags

Agent Skills: Documentation Structure

Install this agent skill to your local

Skill Files