documentation-structure

Original：🇺🇸 English

Translated

Documentation architecture for this repository. Use when creating, updating, or reviewing README.md, CONTRIBUTING.md, or docs/ files. Covers separation of concerns, vendor documentation standards, cross-references, and validation.

2installs

Sourcemiroapp/miro-ai

Added on2026-02-09

NPX Install

npx skill4agent add miroapp/miro-ai documentation-structure

SKILL.md Content

View Translation Comparison →

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

markdown

## 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: