mcpField
D
documentation-structure

documentation-structure

github.com/miroappDevelopment164222 installsUpdated 6w ago
Repository

About documentation-structure

A skill for organizing and maintaining repository documentation, intended for teams writing user, developer, and platform-integration guides. It assigns content to distinct document types and specifies navigation, cross-linking, and review checks.

Key features

  1. 01Defines roles for README, docs, and contribution guides
  2. 02Uses docs/README.md as the navigation hub
  3. 03Separates user and developer documentation
  4. 04Specifies vendor directory and file layouts
  5. 05Lists content, link, and format checks

Use cases

  1. 01Set a consistent structure for a new integration
  2. 02Decide where installation instructions belong
  3. 03Review required sections and document links
  4. 04Prevent duplication and maintain cross-references

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/miroapp/miro-ai --skill documentation-structure

After installing, type/documentation-structurein Claude Code to confirm it loaded.

Bundled filesreferences/patterns.md

Details

From the project README

Documentation Structure

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

Core Principles

PrincipleDescription
Separation of ConcernsREADME (landing), docs/ (reference), CONTRIBUTING (dev workflow)
Single Source of TruthDefine once, link everywhere. Never duplicate content.
Hub-and-Spokedocs/README.md is the central navigation hub
Vendor IsolationEach 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 TypeUser DocsDeveloper 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
FilePurpose
overview.mdWhat is this integration, why use it, installation
*-development.mdHow to build new plugins/powers/extensions
Individual component docsOne 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
VendorConfig FormatLocation
Claude Codeplugin.json.claude-plugin/plugin.json
KiroPOWER.md frontmatterPOWER.md
Gemini CLIJSON extensiongemini-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

See Also

  • references/patterns.md - Formatting patterns (tables, collapsibles, code blocks)

Comments

Markdown supported