documentation-structure — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited documentation-structure (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
This skill defines how documentation is organized and maintained in this repository.
| 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/ |
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 | ✗ | ✓ |
Purpose: First impression. Get users started quickly.
Must include:
Must NOT include:
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.mdPurpose: How to modify THIS repository.
Must include:
--plugin-dir, etc.)Must NOT include:
Each vendor directory in docs/ follows this pattern:
| 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 |
## What are [Plugins/Powers/Extensions]?
## Why Use [Plugins/Powers] vs Direct MCP?
## Available [Plugins/Powers]
## Installation
## Authentication
## Related| 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 |
[text](../mcp/tools-reference.md)docs/ prefix [text](docs/claude-code/overview.md)[text](https://developers.miro.com)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 documentationIf doc A links to doc B, doc B should link back to doc A in its Related section.
Before committing documentation changes:
references/patterns.md - Formatting patterns (tables, collapsibles, code blocks)~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.