# project-map-skill

**Repository Path**: maoyinhang/project-map-skill

## Basic Information

- **Project Name**: project-map-skill
- **Description**: project-map-skill
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-13
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# project-map-skill

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

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

English version: [README.en.md](README.en.md)

## 适用场景

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

## 核心能力

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

## 目录结构

```text
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 目录下即可。常见方式是复制或创建软链接。

复制安装：

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

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

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

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

## 使用方式

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

```text
Use $project-map to analyze this repository.
```

中文示例：

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

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

```text
用 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](LICENSE)。