project-map-skill 是一个用于代码项目分析的 skill，用来把代码仓库整理成“项目地图”：用人能快速理解的方式说明项目做什么、核心模块如何协作、重点流程如何跑、风险边界在哪里，以及新人或 AI 接手时应该先看哪里。

这个 skill 适合做整体认知和接手导览，不适合替代逐行代码解释、API 文档、PRD 或单个 bug 的定位修复。

English version: README.en.md

• 想快速理解一个陌生代码库的业务目的和技术主干。
• 需要梳理模块分工、模块之间的协作关系和核心流程。
• 需要生成可共享的项目接手材料。
• 需要识别高风险区域、外部依赖、数据边界和后续深挖方向。
• 希望输出更像“接手导览”，而不是目录清单或文件索引。

• 先解释项目目的，再解释代码结构。
• 按业务概念和运行链路组织信息，而不是机械罗列目录。
• 支持三种交付方式：
  • 快速对话地图：只在对话中输出，不写文件。
  • 单文件报告：生成一份 Markdown 项目地图。
  • 目录化深度报告：按总览、模块、流程、风险、接手路径拆分多份 Markdown。
• 在结论中标出已确认事实、未确认事项和建议深挖方向。
• 输出语言默认跟随用户当前对话语言。

project-map-skill/
├── project-map/
│   ├── SKILL.md
│   ├── agents/
│   │   └── openai.yaml
│   └── references/
│       ├── analysis-strategy.md
│       └── output-guidelines.md
├── README.md
├── README.en.md
└── LICENSE

关键文件说明：

• project-map/SKILL.md：skill 的主说明和触发规则。
• project-map/agents/openai.yaml：在支持 agent/skill 元数据的环境中展示名称、简介和默认提示词。
• project-map/references/analysis-strategy.md：更细的项目分析策略。
• project-map/references/output-guidelines.md：输出结构、语言风格和报告格式约束。

将 project-map/ 目录放到你的 skills 目录下即可。常见方式是复制或创建软链接。

复制安装：

mkdir -p "<你的 skills 目录>"
cp -R project-map "<你的 skills 目录>/project-map"

软链接安装，适合继续在本仓库中维护：

mkdir -p "<你的 skills 目录>"
ln -s "$(pwd)/project-map" "<你的 skills 目录>/project-map"

如果目标路径已经存在，请先确认它是否是旧版本，避免覆盖本地修改。

在支持 skill 的助手环境中直接点名使用：

Use $project-map to analyze this repository.

中文示例：

用 project-map 分析这个项目，先在对话里给我一个快速项目地图。

用 project-map 为当前仓库生成一份 Markdown 项目地图报告。

用 project-map 生成目录化深度报告，重点覆盖模块、流程、风险和接手顺序。

如果用户只说“分析项目”或“整理项目地图”，skill 会先询问交付方式：

1. 快速对话地图：只在对话里输出，不写文件
2. 单文件报告：生成一份 Markdown 项目地图
3. 目录化深度报告：生成一个目录，拆分模块、流程、风险和接手文档

默认项目地图会围绕以下问题组织：

• 一句话理解：项目主要解决什么问题。
• 主干运行链路：项目如何启动，核心业务闭环如何跑起来。
• 模块地图：各核心模块负责什么、为什么重要、和谁交互。
• 重点流程：最能代表项目价值或风险的跨模块流程。
• 高风险区域：改动时需要谨慎的模块、边界和原因。
• 接手顺序：建议先看哪些概念、文件和流程。

• 修改触发边界、交付方式或主流程时，优先编辑 project-map/SKILL.md。
• 修改分析方法时，编辑 project-map/references/analysis-strategy.md。
• 修改输出格式和措辞规范时，编辑 project-map/references/output-guidelines.md。
• 修改展示名称或默认提示词时，编辑 project-map/agents/openai.yaml。

欢迎提交改进，尤其是以下方向：

• 更清晰的交付模式说明。
• 更适合大型仓库的分阶段分析策略。
• 更稳定的输出模板和质量检查清单。
• 更多真实项目中的使用案例。

建议流程：

1. Fork 本仓库。
2. 新建功能分支。
3. 提交修改并说明适用场景。
4. 发起 Pull Request。

本项目使用 MIT License。