documentation-structure
12
总安装量
4
周安装量
#26838
全站排名
安装命令
npx skills add https://github.com/miroapp/miro-ai --skill documentation-structure
Agent 安装分布
gemini-cli
4
claude-code
4
opencode
4
github-copilot
3
codex
3
kiro-cli
3
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
See Also
references/patterns.md– Formatting patterns (tables, collapsibles, code blocks)