mcpField
D
documentation-structure

documentation-structure

github.com/miroapp开发164222 次安装6 周前更新
代码仓库

关于 documentation-structure

为仓库提供文档组织与维护规范的技能，面向编写用户、开发者及平台集成文档的团队。它划分文档职责，并规定导航、交叉链接和提交前检查方式。

主要功能

  1. 01划分 README、docs 与贡献指南职责
  2. 02以 docs/README.md 作为导航中心
  3. 03区分用户文档与开发者文档
  4. 04规定厂商目录及文件结构
  5. 05提供内容、链接和格式检查项

适用场景

  1. 01为新集成建立统一文档目录
  2. 02决定安装步骤应放入哪类文档
  3. 03检查文档链接与必需章节
  4. 04避免重复内容并维护交叉引用

安装

复制下面的命令，在终端中运行。

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

安装后在 Claude Code 中输入/documentation-structure确认已加载。

附带文件references/patterns.md

详细介绍

文档结构

本规范定义了如何组织和维护此仓库中的文档。

核心原则

原则描述
职责分离README（入口页）、docs/（参考文档）、CONTRIBUTING（开发工作流）
单一事实来源定义一次，链接到各处。绝不重复内容。
中心辐射式结构docs/README.md 是中央导航枢纽
供应商隔离每个 AI 平台在 docs/ 中都有自己的目录

文档职责

用户与开发者内容分离

关键规则： 用户文档只能包含完全自动化的安装方式。所有手动设置都应归入开发者文档。

内容类型用户文档开发者文档
Marketplace 安装✓✓
一键 GitHub 安装✓✓
git clone✗✓
--plugin-dir✗✓
extensions link✗✓
JSON 配置编辑✗✓
本地路径设置✗✓
mcp_settings.json✗✓
用户文档（README.md，docs/*/overview.md）
  • 安装步骤必须简单到可以直接复制粘贴
  • 单条命令或仅通过 UI 操作的步骤
  • 手动替代方案应链接到开发者文档
开发者文档（CONTRIBUTING.md，docs//-development.md）
  • 所有手动设置工作流
  • 本地测试流程
  • 配置文件编辑
  • 环境设置
README.md（入口页）

用途： 留下第一印象。帮助用户快速上手。

必须包含：

  • 一句话描述
  • 快速开始（4 个步骤：选择 → 安装 → 身份验证 → 试用）
  • 功能表格（用户可以做什么）
  • 指向 docs/ 的详细说明链接

不得包含：

  • 完整 API 参考（→ docs/mcp/）
  • 开发工作流（→ CONTRIBUTING.md）
  • 详细架构（→ docs/）
docs/（参考文档）

用途： 为用户和开发者提供完整参考。

结构：

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（开发工作流）

用途： 说明如何修改此仓库。

必须包含：

  • 克隆和本地开发环境设置
  • 如何在本地测试更改（--plugin-dir 等）
  • 验证检查清单
  • PR 流程

不得包含：

  • 完整插件/Power 架构（→ docs/）
  • 面向用户的教程（→ docs/）

供应商文档标准

docs/ 中的每个供应商目录都遵循以下模式：

必需文件
文件用途
overview.md此集成是什么、为何使用以及如何安装
*-development.md如何构建新的插件/Power/扩展
各组件文档每个插件/Power 对应一个文件
overview.md 中的标准章节
## What are [Plugins/Powers/Extensions]?
## Why Use [Plugins/Powers] vs Direct MCP?
## Available [Plugins/Powers]
## Installation
## Authentication
## Related
供应商专属元数据
供应商配置格式位置
Claude Codeplugin.json.claude-plugin/plugin.json
KiroPOWER.md frontmatterPOWER.md
Gemini CLIJSON 扩展gemini-extension.json

交叉引用模式

链接格式
  • docs/ 内部：使用相对路径 [text](../mcp/tools-reference.md)
  • 从 README 链接到 docs/：使用 docs/ 前缀 [text](docs/claude-code/overview.md)
  • 外部链接：完整 URL [text](https://developers.miro.com)
必需的“相关”章节

每个文档文件都应以“相关”章节结尾：

## Related

- [Overview](overview.md) - Introduction to this integration
- [Tools Reference](../mcp/tools-reference.md) - MCP tool documentation
双向链接

如果文档 A 链接到文档 B，文档 B 应在其“相关”章节中反向链接到文档 A。

验证指南

提交文档更改前：

内容检查
  • 没有重复内容（应使用链接）
  • 内容归属正确的文档（README、docs/ 或 CONTRIBUTING）
  • 包含供应商标准要求的所有章节
链接检查
  • 所有内部链接均可访问
  • “相关”章节包含双向链接
  • 外部链接使用 HTTPS
格式检查
  • 代码块指定了语言
  • 表格格式一致
  • 折叠区块的标签匹配

另请参阅

  • references/patterns.md - 格式模式（表格、可折叠内容、代码块）

评论

支持 Markdown