mcpField
P
project-documentation

project-documentation

github.com/jiffies开发0139 次安装39 周前更新
代码仓库

关于 project-documentation

用于编写项目 README 和系统文档的 Skill，面向需要完善入门、配置与架构说明的项目维护者。它结合 Mermaid 图表、分步指南和配置检查清单。

主要功能

  1. 01Mermaid 系统流程图
  2. 02分步安装与使用指南
  3. 03配置文档组织规范
  4. 04README 模板与质量清单

适用场景

  1. 01为新软件项目编写文档
  2. 02改进现有 README
  3. 03说明环境变量和配置文件

安装

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

$npx skills add https://github.com/jiffies/project-documentation-skill --skill project-documentation

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

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

examples/
complete-example.md
references/
mermaid-patterns.md
step-by-step-guide.md
config-organization.md

详细介绍

项目文档

为软件项目编写清晰、完整且用户友好的 README 和系统文档。

核心功能

此技能可帮助你创建高质量的项目文档，内容包括：

  1. Mermaid 流程图 - 可视化系统运行原理
  2. 分步说明 - 面向初学者的详细指南
  3. 配置文档 - 清晰整理环境变量和配置文件

工作流程

1. 了解项目

编写文档前，先收集必要信息：

  • 项目的核心功能和用途
  • 技术栈（前端、后端、数据库、外部服务）
  • 用户工作流（启动流程、核心操作）
  • 外部依赖（API Key、账户、工具）
  • 配置项（必填与可选）

信息来源：README、package.json、.env.example、主要代码文件（main.ts、app.ts、routes/）

2. 创建 Mermaid 流程图

根据项目需求选择合适的图表：

  • 核心流程图（必需）- 从启动到任务完成的用户操作流程
  • 数据流图（推荐）- 系统组件交互和 API 调用
  • 技术架构图（推荐）- 技术栈和分层结构

完整模板和模式：参见 references/mermaid-patterns.md

3. 编写分步说明

按以下顺序组织使用步骤：

  1. 前置条件（软件、账户、工具）
  2. 克隆项目并安装依赖
  3. 获取外部服务凭据（如需要）
  4. 配置环境变量
  5. 初始化系统（如需要）
  6. 启动服务
  7. 使用功能
  8. 验证系统运行情况

每个步骤应包含：目的、命令、预期输出、提示和警告。

完整编写指南：参见 references/step-by-step-guide.md

4. 整理配置文档

使用清晰的分隔符来组织 .env.example：

# ========================================
# Main Category Title
# ========================================
CONFIG_ITEM=example_value

# ----------------------------------------
# Subcategory Title
# ----------------------------------------
CONFIG_ITEM=example_value

为每个配置项编写说明，包含：

  • 必填或可选状态
  • 用途和用法
  • 获取方式（适用于外部服务）
  • 默认值
  • 完整示例

完整整理指南：参见 references/config-organization.md

5. 推荐的 README 结构
# Project Name - Brief Description
## Features
## System Operation Principles (Mermaid diagrams)
## Quick Start (Step by Step)
## Common Commands
## API Examples
## Tech Stack
## Project Structure
## Documentation
## Important Notes
## License

质量检查清单

完成文档前，请检查：

流程图：

  • 核心流程清楚展示用户操作
  • 数据流准确反映系统交互
  • 架构图展示完整技术栈
  • 颜色恰当，复杂度适中（<20 个节点）

使用步骤：

  • 前置条件列表完整
  • 每个步骤都有清晰的标题和目的
  • 命令可直接复制粘贴
  • 说明预期输出
  • 包含常见问题提示

配置：

  • 清楚标注必填项和可选项
  • 说明每个配置项的用途
  • 提供获取方式
  • 分隔和分组清晰
  • 适用时提供多种选项对比

用户友好性：

  • 使用清晰的图标（✅ ⚠️ 💡）
  • 适用时提供多种选项
  • 包含故障排查提示
  • 语言简洁清晰
  • 所有链接均可访问

参考资源

最佳实践

  1. 以用户视角为先 —— 假设用户没有任何背景知识
  2. 可执行性 —— 所有命令都应可直接复制并粘贴
  3. 完整性 —— 包含所有必要信息
  4. 清晰明了 —— 使用图表、表格和代码块
  5. 可验证性 —— 提供验证步骤

常见场景

新建项目：了解项目结构 → 绘制图表 → 编写步骤 → 整理配置 → 验证质量

更新现有项目：阅读当前 README → 找出缺漏 → 添加或优化内容 → 验证质量

优化配置：按功能分组 → 添加分隔符 → 标明必填项和可选项 → 链接获取方式

评论

支持 Markdown