How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/miroapp/miro-ai --skill documentation-structureBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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.mdCONTRIBUTING.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
## RelatedVendor-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:
markdown
## Related
- [Overview](overview.md) - Introduction to this integration
- [Tools Reference](../mcp/tools-reference.md) - MCP tool documentationReciprocal 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)
