From 3f873c4c5f81e31a32e963e219f2a61266b4f426 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Sat, 16 May 2026 06:45:55 +0800
Subject: [PATCH 1/6] =?UTF-8?q?docs:=20redesign=20README=20=E2=80=94=20hig?=
 =?UTF-8?q?hlights,=20AI=20onboarding,=20contributor=20guide?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rewrite tagline: emphasize pure C++23 modules + self-hosted
- Add core features section (5 bullets)
- Add "why mcpp" section focused on module-first experience
- Add AI-assisted install (方式三) and AI learning prompt
- Add contributor section with AI Agent workflow guidance
- Reorganize feature overview into collapsible sections
- Update platform matrix (Clang/LLVM now supported)
- Move WIP notice to end of file
- Add Release + Self-hosted badges
---
 README.md | 247 +++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 200 insertions(+), 47 deletions(-)

diff --git a/README.md b/README.md
index 5f83289..02241e3 100644
--- a/README.md
+++ b/README.md
@@ -1,58 +1,70 @@
 # mcpp
 
-> 一个 **现代C++** 构建工具 - *`模块化 + 依赖/工具链管理 + 包索引 + 打包发布`*
+> 一个 现代C++ 模块化构建工具 — 纯 C++23 模块编写，已实现自举
 
+[![Release](https://img.shields.io/github/v/release/mcpp-community/mcpp)](https://github.com/mcpp-community/mcpp/releases)
 [![C++23](https://img.shields.io/badge/C%2B%2B-23-blue.svg)](https://en.cppreference.com/w/cpp/23)
+[![Self-hosted](https://img.shields.io/badge/build-self--hosted-brightgreen)]()
 [![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
 
-`mcpp` 使用 C++23 完全模块化的工程结构进行开发, 且已经初步完成自举 (使用工具本身从源码构建出自己). 具备 项目构建、依赖自动处理、工具链管理、构建产物打包导出、模块化包索引等基础功能.
+## 核心特性
 
-> [!CAUTION]
-> **初步开发中（WIP）** — 工具任然处于探索阶段。
-> 接口、命令、行为可能在后续版本调整。问题 / 反馈 / 想法欢迎在
-> [issues](https://github.com/mcpp-community/mcpp/issues) 留言。
+- **C++23 模块原生支持** — `import std` 自动处理，文件级增量构建，模块依赖自动分析，零手动配置
+- **纯模块化自举** — mcpp 自身由 43+ 个 C++23 模块组成，用自己构建自己，模块系统经实战验证
+- **开箱即用** — 一条命令安装，内置 GCC 16 / LLVM 20 工具链，自动下载到隔离沙盒，不污染系统
+- **集成依赖管理** — SemVer 约束解析、锁文件、跨项目 BMI 缓存、自定义包索引
+- **多包工作空间** — Workspace 统一锁文件与版本管理，适合大型项目
+
+## 为什么选择 mcpp
+
+mcpp 专门为 **C++23 模块化开发** 打造。如果你想在项目中使用 `import std`、模块接口单元（`.cppm`）、模块分区等现代 C++ 特性，mcpp 可能是目前 Linux 上体验最好的选择：
+
+- **默认模块化** — `mcpp new` 创建的项目模板直接使用 C++23 模块，`import std` 开箱即用
+- **文件级增量构建** — 基于 P1689 dyndep 的三层优化（前端脏检查 + 逐文件扫描 + BMI restat），只重编真正变化的模块
+- **一键创建 & 构建** — `mcpp new hello && cd hello && mcpp build`，工具链自动安装，无需手动配置编译器和构建系统
+- **模块化生态** — [mcpplibs](https://github.com/mcpplibs) 提供一系列可直接 `import` 的 C++ 模块化库，支持自定义包索引
 
 ## 快速开始
 
 ### 安装
 
-<details>
-  <summary>点击获取xlings安装命令</summary>
+**方式一：使用 xlings 安装（推荐）**
 
----
+```bash
+xlings install mcpp -y
+```
 
-#### Linux/MacOS
+<details>
+<summary>还没有 xlings？点击查看安装命令</summary>
 
+**Linux / macOS**
 ```bash
 curl -fsSL https://d2learn.org/xlings-install.sh | bash
 ```
 
-#### Windows - PowerShell
-
-```bash
+**Windows — PowerShell**
+```powershell
 irm https://d2learn.org/xlings-install.ps1.txt | iex
 ```
 
-> tips: xlings -> [details](https://xlings.d2learn.org)
-
----
+> xlings 详情 → [xlings.d2learn.org](https://xlings.d2learn.org)
 
 </details>
 
-**`方法一: 使用xlings包管理器进行安装(推荐)`**
+**方式二：一键安装脚本**
 
 ```bash
-xlings install mcpp -y
+curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash
 ```
 
-**`方法二: 使用一键安装命令`**
+安装到 `~/.mcpp/`，自动加进 shell PATH。删除 `~/.mcpp` 即可干净卸载。
 
-```bash
-curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash
-```
+**方式三：让 AI 助手帮你安装**
+
+将以下内容发给你的 AI 编码助手（Claude Code / Cursor / Copilot 等）：
 
-注: 会装到 `~/.mcpp/`，自动加进 shell PATH。删除 `~/.mcpp` 即可卸载。
+> 帮我安装 mcpp C++ 构建工具：`curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash`，然后用 `mcpp new hello` 创建一个 C++23 模块项目，`mcpp build` 构建，`mcpp run` 运行。
 
 ### 创建项目 & 构建运行
 
@@ -63,46 +75,187 @@ mcpp build
 mcpp run
 ```
 
-注: 初次构建需要初始化环境并获取工具链, 可能需要一些时间
+> 注：首次构建会初始化环境并获取工具链，可能需要一些时间。
+
+### 项目结构
+
+```
+hello/
+├── mcpp.toml             ← 工程描述
+└── src/
+    └── main.cpp          ← import std; 直接可用
+```
+
+```toml
+# mcpp.toml
+[package]
+name = "hello"
+
+[targets.hello]
+kind = "bin"
+main = "src/main.cpp"
+```
+
+## 功能概览
+
+<details>
+<summary><b>构建系统</b></summary>
+
+- C++20/23 模块原生支持（接口单元、实现单元、模块分区）
+- `import std` / `import std.compat` 全自动预编译与缓存
+- 三层增量优化：前端脏检查 + 逐文件 P1689 dyndep + BMI copy-if-different restat
+- 指纹化 BMI 缓存：按编译器/标志/标准库哈希，跨项目共享
+- Ninja 后端：自动生成 build.ninja，并行编译
+- compile_commands.json 自动生成（clangd / ccls 即用）
+- C 语言一等支持：`.c` 文件自动检测，混合 C/C++ 项目
+- 用户自定义 cflags / cxxflags / c_standard
+
+</details>
+
+<details>
+<summary><b>工具链管理</b></summary>
+
+- 内置 GCC 16.1.0 + LLVM/Clang 20.1.7，一键安装
+- musl-gcc 全静态工具链（默认）
+- 多版本共存：`mcpp toolchain install gcc 16` / `mcpp toolchain install llvm 20`
+- 隔离沙盒：所有工具链在 `~/.mcpp/registry/`，不影响系统
+- 按平台指定：`linux = "gcc@16"`, `macos = "llvm@20"`
+- GCC + Clang 编译管线平权（`BmiTraits` 抽象层驱动）
+
+</details>
+
+<details>
+<summary><b>包管理与依赖</b></summary>
+
+- SemVer 约束解析：`^`、`~`、范围、精确版本
+- 三级解析：约束合并 → 多版本 mangling 回退 → 精确匹配
+- 锁文件 mcpp.lock（v2 格式：索引快照 + 命名空间）
+- 命名空间系统：`[dependencies.myteam] foo = "1.0"`
+- 自定义包索引：`[indices] acme = "git@..."` / `{ path = "..." }`
+- 项目级索引隔离（`.mcpp/` 目录，不污染全局）
+- 依赖来源：索引 / Git / 本地路径
+
+</details>
+
+<details>
+<summary><b>工作空间</b></summary>
+
+- `[workspace] members = ["libs/*", "apps/*"]`
+- 统一锁文件 + 统一 target 目录
+- 版本集中管理：`[workspace.dependencies]` + `.workspace = true`
+- 选择性构建：`mcpp build -p member-name`
+- 配置继承：工具链、构建标志、索引从根级联到成员
+
+</details>
+
+<details>
+<summary><b>打包与发布</b></summary>
+
+- `mcpp pack`：三种模式 — static（musl全静态）/ bundle-project / bundle-all
+- musl 全静态二进制：单文件可分发，无 glibc 依赖
+- `mcpp publish`：生成 xpkg.lua + 发布到包索引
+- 自动 patchelf 修正 RPATH
+
+</details>
+
+<details>
+<summary><b>开发体验</b></summary>
+
+- `mcpp new` — 创建模块化项目模板
+- `mcpp run [-- args]` — 构建并运行
+- `mcpp test [-- args]` — 自动发现并运行测试
+- `mcpp search` — 搜索包索引
+- `mcpp add / remove / update` — 依赖管理
+- `mcpp explain E0001` — 错误码详细解释
+- `mcpp self doctor` — 环境自诊断
+
+</details>
+
+## 平台支持
+
+| OS / arch        | GCC (glibc) | GCC (musl) | Clang / LLVM | MSVC |
+|------------------|:-----------:|:----------:|:------------:|:----:|
+| Linux x86_64     | ✅ | ✅ *默认* | ✅ | — |
+| Linux aarch64    | 🔄 | 🔄 | 🔄 | — |
+| macOS            | — | — | 🔄 | — |
+| Windows          | — | — | 🔄 | 🔄 |
+
+✅ 已支持 ｜ 🔄 计划中
+
+> *默认*：release 二进制走 musl 全静态，Linux x86_64 可直接运行，无 glibc 依赖。
 
 ## 文档
 
-- [快速开始](docs/00-getting-started.md)
+- [快速开始](docs/00-getting-started.md) — 5 分钟完成 install → new → build → run
 - [示例项目](docs/01-examples.md)
 - [发布打包](docs/02-pack-and-release.md)
 - [工具链管理](docs/03-toolchains.md)
-- [从源码构建 & 参与贡献](docs/04-build-from-source.md)
-- [mcpp.toml 工程文件指南](docs/05-mcpp-toml.md)
-- [工作空间 (Workspace)](docs/06-workspace.md)
+- [从源码构建](docs/04-build-from-source.md)
+- [mcpp.toml 指南](docs/05-mcpp-toml.md)
+- [工作空间](docs/06-workspace.md)
 
 任意命令的完整选项可通过 `mcpp <cmd> --help` 查阅。
 
-## 平台支持
+**AI 辅助学习**：你可以将本仓库地址或上述文档链接发给 AI 编码助手，让它帮你快速了解 mcpp 的使用方式：
 
-OS × 工具链矩阵：
+> 阅读 https://github.com/mcpp-community/mcpp 的文档，告诉我如何用 mcpp 创建一个带依赖的 C++23 模块项目。
 
-| OS / arch        | gcc (glibc) | gcc (musl) | clang / llvm | msvc |
-|------------------|:-----------:|:----------:|:------------:|:----:|
-| Linux x86_64     | ✅ | ✅ *默认* | 🔄 | — |
-| Linux aarch64    | 🔄 | 🔄 | 🔄 | — |
-| macOS x86_64     | — | — | 🔄 | — |
-| macOS aarch64    | — | — | 🔄 | — |
-| Windows x86_64   | — | — | 🔄 | 🔄 |
+## 参与贡献
+
+欢迎通过 issue 和 PR 参与项目开发。
+
+### 使用 AI Agent 参与贡献
+
+mcpp 项目支持并鼓励开发者使用 AI 编码助手（Claude Code、Cursor、Copilot 等）参与开发。推荐流程：
+
+**报告 Bug / 提出需求**
+
+1. 让 AI 助手阅读相关代码和文档，梳理问题上下文
+2. 使用 `gh issue create` 或在 [issues](https://github.com/mcpp-community/mcpp/issues) 页面提交
+3. 描述清楚：复现步骤、期望行为、实际行为
 
-图例：✅ 已支持 ｜ 🔄 计划中 
+**提交修复 / 功能 PR**
 
-> *默认*：v0.0.1 release 二进制走 musl 全静态路径，Linux x86_64 可以直接运行。
+1. Fork 仓库，创建功能分支
+2. 让 AI 助手阅读项目文档和相关源码，理解现有架构
+3. 实现改动并通过 `mcpp build` 验证编译
+4. 运行 E2E 测试：`bash tests/e2e/01_help_and_version.sh`
+5. 使用 `gh pr create` 提交 PR
+
+**给 AI 助手的上下文**
+
+将以下信息提供给你的 AI 助手，帮助它快速理解项目：
+
+> 这是 mcpp 项目（https://github.com/mcpp-community/mcpp），一个纯 C++23 模块化的构建工具。
+> 项目文档在 docs/ 目录，设计文档在 .agents/docs/ 目录。
+> 用 `mcpp build` 编译，E2E 测试在 tests/e2e/ 下。
+
+后续我们也会在 `.agents/` 目录下提供更多 Skill 和文档，方便 AI Agent 更高效地理解和使用 mcpp 生态。
+
+### 贡献指南
+
+- 代码风格：遵循现有代码模式
+- 提交信息：`feat:` / `fix:` / `test:` / `docs:` 前缀
+- PR 要求：编译通过 + 相关 E2E 测试通过
 
 ## 社区 & 生态
 
-- [社区论坛](https://forum.d2learn.org/category/20) - 交流群(Q: 1067245099)
+- [社区论坛](https://forum.d2learn.org/category/20) — 交流群 (Q: 1067245099)
 - [mcpp-index](https://github.com/mcpp-community/mcpp-index) — 默认包索引
-- [mcpplibs](https://github.com/mcpplibs) - 一个"模块化"的现代C++库集合
+- [mcpplibs](https://github.com/mcpplibs) — 模块化 C++ 库集合
+
+### 致谢
+
+项目依赖和灵感来源：
 
-项目依赖的和部分有灵感启发来源的工具和库
+- [xlings](https://github.com/d2learn/xlings) — 工具链 / 包管理底座
+- [mcpplibs.cmdline](https://github.com/mcpplibs/cmdline) — CLI 框架
+- [ninja](https://github.com/ninja-build/ninja) — 底层构建引擎
+- [xmake](https://github.com/xmake-io/xmake) — 跨平台构建工具
+- [cargo](https://github.com/rust-lang/cargo) — Rust 包管理器
+
+---
 
-  - [xlings](https://github.com/d2learn/xlings) — 工具链 / 包管理底座
-  - [mcpplibs.cmdline](https://github.com/mcpplibs/cmdline) — mcpp 自身用的 CLI 框架
-  - [ninja](https://github.com/ninja-build/ninja) — a small build system with a focus on speed
-  - [xmake](https://github.com/xmake-io/xmake) — A cross-platform build utility based on Lua
-  - [cargo](https://github.com/rust-lang/cargo) — The Rust package manager
\ No newline at end of file
+> [!NOTE]
+> **早期版本** — mcpp 仍在积极开发中，接口和行为可能在后续版本调整。
+> 问题 / 反馈 / 想法欢迎在 [issues](https://github.com/mcpp-community/mcpp/issues) 留言。

From 96ebb19d7c2e52c4f08a527c34241712d9626eca Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Sat, 16 May 2026 07:15:37 +0800
Subject: [PATCH 2/6] docs: update README + add agent skills (contributing,
 usage)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Move WIP notice from bottom to after "why mcpp" section
- Soften "Linux上体验最好的选择" wording
- Change AI prompts to copyable code blocks with repo URL
- Simplify contributing section, reference .agents/skills/
- Add .agents/skills/contributing.md (agent contribution guide)
- Add .agents/skills/mcpp-usage.md (agent usage guide)
---
 .agents/skills/contributing.md | 211 +++++++++++++++++++++++++++++++++
 .agents/skills/mcpp-usage.md   | 170 ++++++++++++++++++++++++++
 README.md                      |  70 +++++------
 3 files changed, 410 insertions(+), 41 deletions(-)
 create mode 100644 .agents/skills/contributing.md
 create mode 100644 .agents/skills/mcpp-usage.md

diff --git a/.agents/skills/contributing.md b/.agents/skills/contributing.md
new file mode 100644
index 0000000..9715130
--- /dev/null
+++ b/.agents/skills/contributing.md
@@ -0,0 +1,211 @@
+# mcpp 项目开发贡献指南
+
+本文档面向 AI Agent，说明如何参与 mcpp 项目的开发贡献，包括 Bug 修复、新功能、代码优化、文档改进等。
+
+## 项目概况
+
+- 仓库：https://github.com/mcpp-community/mcpp
+- 语言：C++23（纯模块化，43+ 个模块，零 .h 头文件）
+- 构建：`mcpp build`（mcpp 用自己构建自己）
+- 测试：E2E 测试在 `tests/e2e/` 目录下
+- 设计文档：`.agents/docs/` 目录
+- CI：GitHub Actions，基于 `main` 分支的 PR 自动触发
+
+## 贡献流程
+
+### 1. 先创建 Issue
+
+**所有贡献都应该先创建 Issue**，特别是新功能。这是为了：
+- 与维护者对齐需求和设计方向
+- 避免重复工作
+- 留下讨论记录
+
+**Bug 修复**
+
+```bash
+gh issue create \
+  --title "fix: 简短描述问题" \
+  --body "## 复现步骤
+1. ...
+2. ...
+
+## 期望行为
+...
+
+## 实际行为
+...
+
+## 环境
+- mcpp 版本：
+- 操作系统：
+- 编译器："
+```
+
+**新功能请求**
+
+```bash
+gh issue create \
+  --title "feat: 简短描述功能" \
+  --body "## 动机
+为什么需要这个功能？
+
+## 设计思路
+大致方案描述。
+
+## 涉及的文件/模块
+预估改动范围。"
+```
+
+**代码优化 / 重构**
+
+```bash
+gh issue create \
+  --title "refactor: 简短描述优化" \
+  --body "## 当前问题
+...
+
+## 优化方案
+...
+
+## 风险评估
+是否影响现有功能？"
+```
+
+### 2. 实现改动
+
+**分支规范**
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b <type>/<short-description>
+# type: feat / fix / refactor / test / docs
+```
+
+**开发要求**
+
+- 代码风格：遵循现有代码模式（查看相邻代码的格式、命名、错误处理方式）
+- 模块导入：使用 `import std;` 和 `import mcpp.xxx;`
+- 不要引入不必要的改动：只改需要改的，不顺手重构不相关代码
+
+**构建验证**
+
+```bash
+# 找到 mcpp 二进制
+ls target/x86_64-linux-gnu/*/bin/mcpp
+
+# 构建
+<mcpp-binary> build
+
+# 如果修改了构建相关代码，确认自举仍能通过
+```
+
+**测试**
+
+```bash
+# 运行基础测试
+bash tests/e2e/01_help_and_version.sh
+
+# 运行与改动相关的 E2E 测试
+bash tests/e2e/<relevant-test>.sh
+
+# 如果添加新功能，应创建对应的 E2E 测试
+# 测试脚本放在 tests/e2e/ 下，命名格式：<序号>_<描述>.sh
+```
+
+### 3. 提交 PR
+
+**提交信息规范**
+
+```
+<type>: <简短描述>
+
+type 取值：
+  feat:     新功能
+  fix:      Bug 修复
+  refactor: 代码重构（不改变功能）
+  test:     添加/修改测试
+  docs:     文档改动
+  ci:       CI/CD 相关
+```
+
+**创建 PR**
+
+```bash
+git push -u origin <branch-name>
+
+gh pr create \
+  --title "<type>: 简短描述" \
+  --body "## Summary
+- 改动点 1
+- 改动点 2
+
+Closes #<issue-number>
+
+## Test plan
+- [ ] mcpp build 编译通过
+- [ ] 相关 E2E 测试通过
+- [ ] 新增 E2E 测试（如适用）"
+```
+
+### 4. CI 必须通过
+
+**PR 的 CI 检查是硬性要求**。CI 不通过的 PR 不会被合入。
+
+- CI workflow 在 `.github/workflows/ci.yml`
+- 只有 base 为 `main` 的 PR 会触发 CI
+- CI 内容：mcpp 自举构建 + E2E 测试套件
+- 如果 CI 失败，检查 `gh run view <run-id> --log-failed` 定位问题
+
+```bash
+# 查看 PR 的 CI 状态
+gh pr checks <pr-number>
+
+# 查看失败日志
+gh run view <run-id> --log-failed
+```
+
+### 5. Review & 合入
+
+- 维护者会 review PR 并给出反馈
+- 根据反馈修改后再次 push（CI 会重新运行）
+- 合入方式：Squash merge
+
+## 常用工具
+
+| 工具 | 用途 |
+|---|---|
+| `gh` | GitHub CLI — 创建 issue/PR、查看 CI、管理仓库 |
+| `git` | 版本控制 |
+| `mcpp build` | 编译项目 |
+| `mcpp run` | 构建并运行 |
+| `mcpp test` | 运行测试 |
+| `bash tests/e2e/*.sh` | 运行 E2E 测试 |
+
+## 项目目录结构
+
+```
+src/
+├── cli.cppm                 ← 命令行入口（最大文件）
+├── config.cppm              ← 全局配置
+├── manifest.cppm            ← mcpp.toml 解析
+├── build/                   ← 构建系统（ninja 后端、编译标志）
+├── pm/                      ← 包管理子系统
+├── toolchain/               ← 编译器检测与管理
+├── modgraph/                ← 模块图扫描与验证
+├── pack/                    ← 打包发布
+├── xlings.cppm              ← xlings 抽象层
+└── ui.cppm                  ← 输出样式
+
+tests/e2e/                   ← E2E 测试脚本
+docs/                        ← 用户文档
+.agents/docs/                ← 设计文档
+.agents/skills/              ← Agent 技能文档
+```
+
+## 注意事项
+
+- mcpp 是 C++23 模块项目，修改模块时注意 import 依赖顺序
+- 不要修改 `.agents/docs/` 下的设计文档（除非是专门的文档 PR）
+- E2E 测试应该能独立运行，不依赖网络（使用本地 path index 等方式）
+- 如果不确定设计方向，先在 Issue 里讨论再动手
diff --git a/.agents/skills/mcpp-usage.md b/.agents/skills/mcpp-usage.md
new file mode 100644
index 0000000..218b092
--- /dev/null
+++ b/.agents/skills/mcpp-usage.md
@@ -0,0 +1,170 @@
+# mcpp 基础用法指南
+
+本文档面向 AI Agent，说明 mcpp 的基础使用方法以及如何帮助用户解决问题。
+
+## mcpp 是什么
+
+mcpp 是一个现代 C++ 模块化构建工具，纯 C++23 模块编写，已实现自举。
+
+- 仓库：https://github.com/mcpp-community/mcpp
+- 文档：https://github.com/mcpp-community/mcpp/tree/main/docs
+- 包索引：https://github.com/mcpp-community/mcpp-index
+- 模块化库集合：https://github.com/mcpplibs
+
+## 安装
+
+```bash
+# 方式一：xlings 安装（推荐）
+xlings install mcpp -y
+
+# 方式二：一键安装脚本
+curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash
+```
+
+安装到 `~/.mcpp/`，自动加入 shell PATH。删除 `~/.mcpp` 即可卸载。
+
+首次运行会自动安装 GCC 工具链到隔离沙盒，不影响系统。
+
+## 核心命令
+
+### 项目管理
+
+```bash
+mcpp new <name>          # 创建新项目（默认 C++23 模块模板）
+mcpp build               # 构建
+mcpp run [-- args]       # 构建并运行（args 透传给可执行文件）
+mcpp test [-- args]      # 构建并运行测试
+mcpp clean               # 清理构建产物
+```
+
+### 依赖管理
+
+```bash
+mcpp add <pkg>[@<ver>]     # 添加依赖（如 mcpp add gtest@1.15.2）
+mcpp remove <pkg>          # 移除依赖
+mcpp update [pkg]          # 更新依赖版本
+mcpp search <keyword>      # 搜索包索引
+```
+
+### 工具链管理
+
+```bash
+mcpp toolchain list                    # 查看已安装工具链
+mcpp toolchain install gcc 16          # 安装 GCC 16
+mcpp toolchain install llvm 20         # 安装 LLVM/Clang 20
+mcpp toolchain default gcc@16.1.0     # 设置默认工具链
+```
+
+### 包索引管理
+
+```bash
+mcpp index list               # 查看已配置的包索引
+mcpp index update [<name>]    # 刷新索引
+mcpp index pin <name> [rev]   # 锁定索引到指定 commit
+mcpp index unpin <name>       # 解除锁定
+```
+
+### 打包发布
+
+```bash
+mcpp pack                      # 打包（默认 bundle-project 模式）
+mcpp pack --mode static        # musl 全静态打包
+mcpp publish --dry-run         # 预览发布内容
+```
+
+### 诊断
+
+```bash
+mcpp self doctor               # 环境健康检查
+mcpp self env                  # 打印路径和配置
+mcpp explain E0001             # 查看错误码详细解释
+mcpp self config --mirror CN   # 切换镜像（CN / GLOBAL）
+```
+
+## mcpp.toml 基础配置
+
+```toml
+[package]
+name = "myapp"
+version = "0.1.0"
+
+[targets.myapp]
+kind = "bin"              # bin / lib / shared / test
+main = "src/main.cpp"
+
+[dependencies]
+gtest = "1.15.2"          # 从默认索引安装
+
+[toolchain]
+default = "gcc@16.1.0"    # 指定编译器
+```
+
+更多配置项参见：https://github.com/mcpp-community/mcpp/blob/main/docs/05-mcpp-toml.md
+
+## 工作空间（多包项目）
+
+```toml
+# 根 mcpp.toml
+[workspace]
+members = ["libs/*", "apps/*"]
+
+[workspace.dependencies]
+gtest = "1.15.2"
+```
+
+```bash
+mcpp build                    # 构建整个工作空间
+mcpp build -p member-name     # 只构建指定成员
+```
+
+## 自定义包索引
+
+```toml
+# mcpp.toml
+[indices]
+my-index = "git@gitlab.example.com:team/mcpp-index.git"
+local-dev = { path = "/path/to/local/index" }
+
+[dependencies.my-index]
+internal-lib = "1.0.0"
+```
+
+## 常见问题处理
+
+### 首次构建慢
+
+首次运行需要下载工具链（GCC/Clang），这是正常的。后续构建会使用缓存。
+
+### command not found
+
+`~/.mcpp/bin` 未加入 PATH。重启终端或执行：
+```bash
+source ~/.bashrc    # bash
+source ~/.zshrc     # zsh
+exec fish           # fish
+```
+
+### 编译错误
+
+1. 确认 mcpp 版本：`mcpp --version`
+2. 确认工具链：`mcpp toolchain list`
+3. 尝试清理重建：`mcpp clean && mcpp build`
+
+### 依赖找不到
+
+1. 更新索引：`mcpp index update`
+2. 搜索确认包名：`mcpp search <keyword>`
+3. 确认 mcpp.toml 中的依赖声明格式
+
+## 问题反馈
+
+如果遇到无法解决的问题：
+
+1. **优先在项目 Issue 中反馈**：https://github.com/mcpp-community/mcpp/issues
+   - 使用 `gh issue create` 或在页面上创建
+   - 描述复现步骤、期望行为、实际行为、mcpp 版本和操作系统
+
+2. **社区论坛讨论**：https://forum.d2learn.org/category/20
+   - 适合使用疑问、最佳实践讨论等
+
+如果 AI Agent 无法直接创建 Issue，请提示用户手动创建，并提供整理好的问题描述。
diff --git a/README.md b/README.md
index 02241e3..c31aaf2 100644
--- a/README.md
+++ b/README.md
@@ -18,13 +18,17 @@
 
 ## 为什么选择 mcpp
 
-mcpp 专门为 **C++23 模块化开发** 打造。如果你想在项目中使用 `import std`、模块接口单元（`.cppm`）、模块分区等现代 C++ 特性，mcpp 可能是目前 Linux 上体验最好的选择：
+mcpp 专门为 **C++23 模块化开发** 打造。如果你想在项目中使用 `import std`、模块接口单元（`.cppm`）、模块分区等现代 C++ 特性，mcpp 在 Linux 上能为你提供便捷且友好的开发体验：
 
 - **默认模块化** — `mcpp new` 创建的项目模板直接使用 C++23 模块，`import std` 开箱即用
 - **文件级增量构建** — 基于 P1689 dyndep 的三层优化（前端脏检查 + 逐文件扫描 + BMI restat），只重编真正变化的模块
 - **一键创建 & 构建** — `mcpp new hello && cd hello && mcpp build`，工具链自动安装，无需手动配置编译器和构建系统
 - **模块化生态** — [mcpplibs](https://github.com/mcpplibs) 提供一系列可直接 `import` 的 C++ 模块化库，支持自定义包索引
 
+> [!NOTE]
+> **早期版本** — mcpp 仍在积极开发中，接口和行为可能在后续版本调整。
+> 问题 / 反馈 / 想法欢迎在 [issues](https://github.com/mcpp-community/mcpp/issues) 留言。
+
 ## 快速开始
 
 ### 安装
@@ -62,9 +66,13 @@ curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/insta
 
 **方式三：让 AI 助手帮你安装**
 
-将以下内容发给你的 AI 编码助手（Claude Code / Cursor / Copilot 等）：
+将以下提示词复制给你的 AI 编码助手（Claude Code / Cursor / Copilot 等）：
 
-> 帮我安装 mcpp C++ 构建工具：`curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash`，然后用 `mcpp new hello` 创建一个 C++23 模块项目，`mcpp build` 构建，`mcpp run` 运行。
+```
+阅读 https://github.com/mcpp-community/mcpp 的 README，
+帮我安装 mcpp 并创建一个 C++23 模块项目，构建并运行。
+项目的 .agents/skills/ 目录下有更多使用指南供参考。
+```
 
 ### 创建项目 & 构建运行
 
@@ -196,47 +204,33 @@ main = "src/main.cpp"
 
 任意命令的完整选项可通过 `mcpp <cmd> --help` 查阅。
 
-**AI 辅助学习**：你可以将本仓库地址或上述文档链接发给 AI 编码助手，让它帮你快速了解 mcpp 的使用方式：
+**AI 辅助学习**：你可以将以下提示词发给 AI 编码助手，让它帮你快速了解 mcpp：
 
-> 阅读 https://github.com/mcpp-community/mcpp 的文档，告诉我如何用 mcpp 创建一个带依赖的 C++23 模块项目。
+```
+阅读 https://github.com/mcpp-community/mcpp 的文档（docs/ 目录），
+告诉我如何用 mcpp 创建一个带依赖的 C++23 模块项目。
+项目的 .agents/skills/ 目录下有详细的使用指南和贡献指南。
+```
 
 ## 参与贡献
 
-欢迎通过 issue 和 PR 参与项目开发。
-
-### 使用 AI Agent 参与贡献
-
-mcpp 项目支持并鼓励开发者使用 AI 编码助手（Claude Code、Cursor、Copilot 等）参与开发。推荐流程：
-
-**报告 Bug / 提出需求**
+欢迎通过 Issue 和 PR 参与项目开发。项目接受开发者使用 AI Agent 参与开发与贡献。
 
-1. 让 AI 助手阅读相关代码和文档，梳理问题上下文
-2. 使用 `gh issue create` 或在 [issues](https://github.com/mcpp-community/mcpp/issues) 页面提交
-3. 描述清楚：复现步骤、期望行为、实际行为
+**基本流程**
 
-**提交修复 / 功能 PR**
+1. 创建 Issue — Bug 修复、新功能、优化等，先在 [issues](https://github.com/mcpp-community/mcpp/issues) 创建讨论
+2. 实现改动 — Fork 仓库，创建分支，实现并验证（`mcpp build` + E2E 测试）
+3. 提交 PR — 使用 `gh pr create`，确保 CI 通过
+4. CI 必须通过 — CI 不通过的 PR 不会被合入
 
-1. Fork 仓库，创建功能分支
-2. 让 AI 助手阅读项目文档和相关源码，理解现有架构
-3. 实现改动并通过 `mcpp build` 验证编译
-4. 运行 E2E 测试：`bash tests/e2e/01_help_and_version.sh`
-5. 使用 `gh pr create` 提交 PR
+**提交信息规范**：`feat:` / `fix:` / `test:` / `docs:` / `refactor:` 前缀
 
-**给 AI 助手的上下文**
+**AI Agent 贡献指南**：项目的 [`.agents/skills/contributing.md`](.agents/skills/contributing.md) 提供了完整的 Agent 贡献流程、工具使用和项目结构说明。将以下提示词发给 AI 助手即可：
 
-将以下信息提供给你的 AI 助手，帮助它快速理解项目：
-
-> 这是 mcpp 项目（https://github.com/mcpp-community/mcpp），一个纯 C++23 模块化的构建工具。
-> 项目文档在 docs/ 目录，设计文档在 .agents/docs/ 目录。
-> 用 `mcpp build` 编译，E2E 测试在 tests/e2e/ 下。
-
-后续我们也会在 `.agents/` 目录下提供更多 Skill 和文档，方便 AI Agent 更高效地理解和使用 mcpp 生态。
-
-### 贡献指南
-
-- 代码风格：遵循现有代码模式
-- 提交信息：`feat:` / `fix:` / `test:` / `docs:` 前缀
-- PR 要求：编译通过 + 相关 E2E 测试通过
+```
+阅读 https://github.com/mcpp-community/mcpp 仓库的 .agents/skills/contributing.md，
+按照指南帮我给 mcpp 项目提交一个贡献。
+```
 
 ## 社区 & 生态
 
@@ -253,9 +247,3 @@ mcpp 项目支持并鼓励开发者使用 AI 编码助手（Claude Code、Cursor
 - [ninja](https://github.com/ninja-build/ninja) — 底层构建引擎
 - [xmake](https://github.com/xmake-io/xmake) — 跨平台构建工具
 - [cargo](https://github.com/rust-lang/cargo) — Rust 包管理器
-
----
-
-> [!NOTE]
-> **早期版本** — mcpp 仍在积极开发中，接口和行为可能在后续版本调整。
-> 问题 / 反馈 / 想法欢迎在 [issues](https://github.com/mcpp-community/mcpp/issues) 留言。

From c03c3f87afc782b9ef19b9bec3eb0ffe417c9549 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Sat, 16 May 2026 07:23:31 +0800
Subject: [PATCH 3/6] docs: restructure skills to standard directory format
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- .agents/skills/contributing.md → .agents/skills/mcpp-contributing/SKILL.md
- .agents/skills/mcpp-usage.md → .agents/skills/mcpp-usage/SKILL.md
- Both skills now have YAML frontmatter (name, description)
- Update README references to new skill paths
---
 .agents/skills/contributing.md            | 211 ----------------------
 .agents/skills/mcpp-contributing/SKILL.md | 157 ++++++++++++++++
 .agents/skills/mcpp-usage.md              | 170 -----------------
 .agents/skills/mcpp-usage/SKILL.md        | 138 ++++++++++++++
 README.md                                 |  11 +-
 5 files changed, 301 insertions(+), 386 deletions(-)
 delete mode 100644 .agents/skills/contributing.md
 create mode 100644 .agents/skills/mcpp-contributing/SKILL.md
 delete mode 100644 .agents/skills/mcpp-usage.md
 create mode 100644 .agents/skills/mcpp-usage/SKILL.md

diff --git a/.agents/skills/contributing.md b/.agents/skills/contributing.md
deleted file mode 100644
index 9715130..0000000
--- a/.agents/skills/contributing.md
+++ /dev/null
@@ -1,211 +0,0 @@
-# mcpp 项目开发贡献指南
-
-本文档面向 AI Agent，说明如何参与 mcpp 项目的开发贡献，包括 Bug 修复、新功能、代码优化、文档改进等。
-
-## 项目概况
-
-- 仓库：https://github.com/mcpp-community/mcpp
-- 语言：C++23（纯模块化，43+ 个模块，零 .h 头文件）
-- 构建：`mcpp build`（mcpp 用自己构建自己）
-- 测试：E2E 测试在 `tests/e2e/` 目录下
-- 设计文档：`.agents/docs/` 目录
-- CI：GitHub Actions，基于 `main` 分支的 PR 自动触发
-
-## 贡献流程
-
-### 1. 先创建 Issue
-
-**所有贡献都应该先创建 Issue**，特别是新功能。这是为了：
-- 与维护者对齐需求和设计方向
-- 避免重复工作
-- 留下讨论记录
-
-**Bug 修复**
-
-```bash
-gh issue create \
-  --title "fix: 简短描述问题" \
-  --body "## 复现步骤
-1. ...
-2. ...
-
-## 期望行为
-...
-
-## 实际行为
-...
-
-## 环境
-- mcpp 版本：
-- 操作系统：
-- 编译器："
-```
-
-**新功能请求**
-
-```bash
-gh issue create \
-  --title "feat: 简短描述功能" \
-  --body "## 动机
-为什么需要这个功能？
-
-## 设计思路
-大致方案描述。
-
-## 涉及的文件/模块
-预估改动范围。"
-```
-
-**代码优化 / 重构**
-
-```bash
-gh issue create \
-  --title "refactor: 简短描述优化" \
-  --body "## 当前问题
-...
-
-## 优化方案
-...
-
-## 风险评估
-是否影响现有功能？"
-```
-
-### 2. 实现改动
-
-**分支规范**
-
-```bash
-git checkout main
-git pull origin main
-git checkout -b <type>/<short-description>
-# type: feat / fix / refactor / test / docs
-```
-
-**开发要求**
-
-- 代码风格：遵循现有代码模式（查看相邻代码的格式、命名、错误处理方式）
-- 模块导入：使用 `import std;` 和 `import mcpp.xxx;`
-- 不要引入不必要的改动：只改需要改的，不顺手重构不相关代码
-
-**构建验证**
-
-```bash
-# 找到 mcpp 二进制
-ls target/x86_64-linux-gnu/*/bin/mcpp
-
-# 构建
-<mcpp-binary> build
-
-# 如果修改了构建相关代码，确认自举仍能通过
-```
-
-**测试**
-
-```bash
-# 运行基础测试
-bash tests/e2e/01_help_and_version.sh
-
-# 运行与改动相关的 E2E 测试
-bash tests/e2e/<relevant-test>.sh
-
-# 如果添加新功能，应创建对应的 E2E 测试
-# 测试脚本放在 tests/e2e/ 下，命名格式：<序号>_<描述>.sh
-```
-
-### 3. 提交 PR
-
-**提交信息规范**
-
-```
-<type>: <简短描述>
-
-type 取值：
-  feat:     新功能
-  fix:      Bug 修复
-  refactor: 代码重构（不改变功能）
-  test:     添加/修改测试
-  docs:     文档改动
-  ci:       CI/CD 相关
-```
-
-**创建 PR**
-
-```bash
-git push -u origin <branch-name>
-
-gh pr create \
-  --title "<type>: 简短描述" \
-  --body "## Summary
-- 改动点 1
-- 改动点 2
-
-Closes #<issue-number>
-
-## Test plan
-- [ ] mcpp build 编译通过
-- [ ] 相关 E2E 测试通过
-- [ ] 新增 E2E 测试（如适用）"
-```
-
-### 4. CI 必须通过
-
-**PR 的 CI 检查是硬性要求**。CI 不通过的 PR 不会被合入。
-
-- CI workflow 在 `.github/workflows/ci.yml`
-- 只有 base 为 `main` 的 PR 会触发 CI
-- CI 内容：mcpp 自举构建 + E2E 测试套件
-- 如果 CI 失败，检查 `gh run view <run-id> --log-failed` 定位问题
-
-```bash
-# 查看 PR 的 CI 状态
-gh pr checks <pr-number>
-
-# 查看失败日志
-gh run view <run-id> --log-failed
-```
-
-### 5. Review & 合入
-
-- 维护者会 review PR 并给出反馈
-- 根据反馈修改后再次 push（CI 会重新运行）
-- 合入方式：Squash merge
-
-## 常用工具
-
-| 工具 | 用途 |
-|---|---|
-| `gh` | GitHub CLI — 创建 issue/PR、查看 CI、管理仓库 |
-| `git` | 版本控制 |
-| `mcpp build` | 编译项目 |
-| `mcpp run` | 构建并运行 |
-| `mcpp test` | 运行测试 |
-| `bash tests/e2e/*.sh` | 运行 E2E 测试 |
-
-## 项目目录结构
-
-```
-src/
-├── cli.cppm                 ← 命令行入口（最大文件）
-├── config.cppm              ← 全局配置
-├── manifest.cppm            ← mcpp.toml 解析
-├── build/                   ← 构建系统（ninja 后端、编译标志）
-├── pm/                      ← 包管理子系统
-├── toolchain/               ← 编译器检测与管理
-├── modgraph/                ← 模块图扫描与验证
-├── pack/                    ← 打包发布
-├── xlings.cppm              ← xlings 抽象层
-└── ui.cppm                  ← 输出样式
-
-tests/e2e/                   ← E2E 测试脚本
-docs/                        ← 用户文档
-.agents/docs/                ← 设计文档
-.agents/skills/              ← Agent 技能文档
-```
-
-## 注意事项
-
-- mcpp 是 C++23 模块项目，修改模块时注意 import 依赖顺序
-- 不要修改 `.agents/docs/` 下的设计文档（除非是专门的文档 PR）
-- E2E 测试应该能独立运行，不依赖网络（使用本地 path index 等方式）
-- 如果不确定设计方向，先在 Issue 里讨论再动手
diff --git a/.agents/skills/mcpp-contributing/SKILL.md b/.agents/skills/mcpp-contributing/SKILL.md
new file mode 100644
index 0000000..0880518
--- /dev/null
+++ b/.agents/skills/mcpp-contributing/SKILL.md
@@ -0,0 +1,157 @@
+---
+name: mcpp-contributing
+description: Use when contributing to the mcpp project — submitting bug fixes, new features, code optimizations, documentation improvements, or any PR. Covers issue creation, branch conventions, build verification, CI requirements, and PR workflow using gh and git.
+---
+
+# mcpp 项目开发贡献
+
+## Overview
+
+mcpp 项目的贡献流程：先创建 Issue → 实现改动 → 提交 PR → CI 通过 → Review 合入。
+
+- 仓库：https://github.com/mcpp-community/mcpp
+- 构建：`mcpp build`（C++23 模块自举）
+- 测试：`tests/e2e/` 下的 bash 脚本
+- CI：GitHub Actions，base 为 `main` 的 PR 自动触发
+
+## 贡献流程
+
+### 1. 创建 Issue（必须）
+
+所有贡献先创建 Issue，特别是新功能。避免重复工作，留下讨论记录。
+
+**Bug 修复**
+
+```bash
+gh issue create \
+  --title "fix: 简短描述" \
+  --body "## 复现步骤
+1. ...
+
+## 期望行为
+...
+
+## 实际行为
+...
+
+## 环境
+- mcpp 版本：\`mcpp --version\`
+- OS："
+```
+
+**新功能**
+
+```bash
+gh issue create \
+  --title "feat: 简短描述" \
+  --body "## 动机
+...
+
+## 设计思路
+...
+
+## 涉及模块
+..."
+```
+
+**代码优化**
+
+```bash
+gh issue create \
+  --title "refactor: 简短描述" \
+  --body "## 当前问题
+...
+
+## 优化方案
+..."
+```
+
+### 2. 实现改动
+
+**分支**
+
+```bash
+git checkout main && git pull origin main
+git checkout -b <type>/<short-description>
+# type: feat / fix / refactor / test / docs
+```
+
+**开发要求**
+- 遵循现有代码风格（查看相邻代码）
+- 模块导入用 `import std;` 和 `import mcpp.xxx;`
+- 只改需要改的，不顺手重构不相关代码
+
+**构建验证**
+
+```bash
+# 找到 mcpp 二进制
+ls target/x86_64-linux-gnu/*/bin/mcpp
+# 构建
+<mcpp-binary> build
+```
+
+**测试**
+
+```bash
+bash tests/e2e/01_help_and_version.sh    # 基础测试
+bash tests/e2e/<relevant-test>.sh        # 相关测试
+# 新功能应创建对应 E2E 测试
+```
+
+### 3. 提交 PR
+
+**提交信息**：`feat:` / `fix:` / `refactor:` / `test:` / `docs:` 前缀
+
+```bash
+git push -u origin <branch>
+gh pr create \
+  --title "<type>: 简短描述" \
+  --body "## Summary
+- 改动点
+
+Closes #<issue>
+
+## Test plan
+- [ ] mcpp build 通过
+- [ ] E2E 测试通过"
+```
+
+### 4. CI 必须通过
+
+CI 不通过的 PR 不会被合入。
+
+```bash
+gh pr checks <pr-number>           # 查看状态
+gh run view <run-id> --log-failed  # 查看失败日志
+```
+
+CI 内容：mcpp 自举构建 + E2E 测试。只有 base 为 `main` 的 PR 触发。
+
+### 5. Review & 合入
+
+维护者 review → 反馈修改 → CI 重跑 → Squash merge。
+
+## 项目结构
+
+```
+src/
+├── cli.cppm              ← 命令行入口
+├── config.cppm           ← 全局配置
+├── manifest.cppm         ← mcpp.toml 解析
+├── build/                ← 构建系统（ninja 后端）
+├── pm/                   ← 包管理子系统
+├── toolchain/            ← 编译器检测管理
+├── modgraph/             ← 模块图扫描验证
+├── pack/                 ← 打包发布
+└── xlings.cppm           ← xlings 抽象层
+tests/e2e/                ← E2E 测试脚本
+docs/                     ← 用户文档
+.agents/docs/             ← 设计文档
+.agents/skills/           ← Agent 技能文档
+```
+
+## 注意事项
+
+- C++23 模块项目，修改模块时注意 import 依赖顺序
+- E2E 测试应独立运行，不依赖网络
+- 不确定方向时先在 Issue 讨论再动手
diff --git a/.agents/skills/mcpp-usage.md b/.agents/skills/mcpp-usage.md
deleted file mode 100644
index 218b092..0000000
--- a/.agents/skills/mcpp-usage.md
+++ /dev/null
@@ -1,170 +0,0 @@
-# mcpp 基础用法指南
-
-本文档面向 AI Agent，说明 mcpp 的基础使用方法以及如何帮助用户解决问题。
-
-## mcpp 是什么
-
-mcpp 是一个现代 C++ 模块化构建工具，纯 C++23 模块编写，已实现自举。
-
-- 仓库：https://github.com/mcpp-community/mcpp
-- 文档：https://github.com/mcpp-community/mcpp/tree/main/docs
-- 包索引：https://github.com/mcpp-community/mcpp-index
-- 模块化库集合：https://github.com/mcpplibs
-
-## 安装
-
-```bash
-# 方式一：xlings 安装（推荐）
-xlings install mcpp -y
-
-# 方式二：一键安装脚本
-curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash
-```
-
-安装到 `~/.mcpp/`，自动加入 shell PATH。删除 `~/.mcpp` 即可卸载。
-
-首次运行会自动安装 GCC 工具链到隔离沙盒，不影响系统。
-
-## 核心命令
-
-### 项目管理
-
-```bash
-mcpp new <name>          # 创建新项目（默认 C++23 模块模板）
-mcpp build               # 构建
-mcpp run [-- args]       # 构建并运行（args 透传给可执行文件）
-mcpp test [-- args]      # 构建并运行测试
-mcpp clean               # 清理构建产物
-```
-
-### 依赖管理
-
-```bash
-mcpp add <pkg>[@<ver>]     # 添加依赖（如 mcpp add gtest@1.15.2）
-mcpp remove <pkg>          # 移除依赖
-mcpp update [pkg]          # 更新依赖版本
-mcpp search <keyword>      # 搜索包索引
-```
-
-### 工具链管理
-
-```bash
-mcpp toolchain list                    # 查看已安装工具链
-mcpp toolchain install gcc 16          # 安装 GCC 16
-mcpp toolchain install llvm 20         # 安装 LLVM/Clang 20
-mcpp toolchain default gcc@16.1.0     # 设置默认工具链
-```
-
-### 包索引管理
-
-```bash
-mcpp index list               # 查看已配置的包索引
-mcpp index update [<name>]    # 刷新索引
-mcpp index pin <name> [rev]   # 锁定索引到指定 commit
-mcpp index unpin <name>       # 解除锁定
-```
-
-### 打包发布
-
-```bash
-mcpp pack                      # 打包（默认 bundle-project 模式）
-mcpp pack --mode static        # musl 全静态打包
-mcpp publish --dry-run         # 预览发布内容
-```
-
-### 诊断
-
-```bash
-mcpp self doctor               # 环境健康检查
-mcpp self env                  # 打印路径和配置
-mcpp explain E0001             # 查看错误码详细解释
-mcpp self config --mirror CN   # 切换镜像（CN / GLOBAL）
-```
-
-## mcpp.toml 基础配置
-
-```toml
-[package]
-name = "myapp"
-version = "0.1.0"
-
-[targets.myapp]
-kind = "bin"              # bin / lib / shared / test
-main = "src/main.cpp"
-
-[dependencies]
-gtest = "1.15.2"          # 从默认索引安装
-
-[toolchain]
-default = "gcc@16.1.0"    # 指定编译器
-```
-
-更多配置项参见：https://github.com/mcpp-community/mcpp/blob/main/docs/05-mcpp-toml.md
-
-## 工作空间（多包项目）
-
-```toml
-# 根 mcpp.toml
-[workspace]
-members = ["libs/*", "apps/*"]
-
-[workspace.dependencies]
-gtest = "1.15.2"
-```
-
-```bash
-mcpp build                    # 构建整个工作空间
-mcpp build -p member-name     # 只构建指定成员
-```
-
-## 自定义包索引
-
-```toml
-# mcpp.toml
-[indices]
-my-index = "git@gitlab.example.com:team/mcpp-index.git"
-local-dev = { path = "/path/to/local/index" }
-
-[dependencies.my-index]
-internal-lib = "1.0.0"
-```
-
-## 常见问题处理
-
-### 首次构建慢
-
-首次运行需要下载工具链（GCC/Clang），这是正常的。后续构建会使用缓存。
-
-### command not found
-
-`~/.mcpp/bin` 未加入 PATH。重启终端或执行：
-```bash
-source ~/.bashrc    # bash
-source ~/.zshrc     # zsh
-exec fish           # fish
-```
-
-### 编译错误
-
-1. 确认 mcpp 版本：`mcpp --version`
-2. 确认工具链：`mcpp toolchain list`
-3. 尝试清理重建：`mcpp clean && mcpp build`
-
-### 依赖找不到
-
-1. 更新索引：`mcpp index update`
-2. 搜索确认包名：`mcpp search <keyword>`
-3. 确认 mcpp.toml 中的依赖声明格式
-
-## 问题反馈
-
-如果遇到无法解决的问题：
-
-1. **优先在项目 Issue 中反馈**：https://github.com/mcpp-community/mcpp/issues
-   - 使用 `gh issue create` 或在页面上创建
-   - 描述复现步骤、期望行为、实际行为、mcpp 版本和操作系统
-
-2. **社区论坛讨论**：https://forum.d2learn.org/category/20
-   - 适合使用疑问、最佳实践讨论等
-
-如果 AI Agent 无法直接创建 Issue，请提示用户手动创建，并提供整理好的问题描述。
diff --git a/.agents/skills/mcpp-usage/SKILL.md b/.agents/skills/mcpp-usage/SKILL.md
new file mode 100644
index 0000000..d5472dc
--- /dev/null
+++ b/.agents/skills/mcpp-usage/SKILL.md
@@ -0,0 +1,138 @@
+---
+name: mcpp-usage
+description: Use when helping users install, configure, or use mcpp — the C++23 modular build tool. Covers installation, project creation, building, dependency management, toolchain management, workspace setup, packaging, diagnostics, and troubleshooting.
+---
+
+# mcpp 基础用法
+
+## Overview
+
+mcpp 是一个现代 C++ 模块化构建工具，纯 C++23 模块编写，已实现自举。一条命令安装，`import std` 开箱即用。
+
+- 仓库：https://github.com/mcpp-community/mcpp
+- 文档：https://github.com/mcpp-community/mcpp/tree/main/docs
+- 包索引：https://github.com/mcpp-community/mcpp-index
+- 模块化库：https://github.com/mcpplibs
+
+## Quick Reference
+
+| 命令 | 用途 |
+|---|---|
+| `mcpp new <name>` | 创建项目 |
+| `mcpp build` | 构建 |
+| `mcpp run [-- args]` | 构建并运行 |
+| `mcpp test [-- args]` | 运行测试 |
+| `mcpp add <pkg>[@ver]` | 添加依赖 |
+| `mcpp remove <pkg>` | 移除依赖 |
+| `mcpp update [pkg]` | 更新依赖 |
+| `mcpp search <keyword>` | 搜索包 |
+| `mcpp toolchain list` | 查看工具链 |
+| `mcpp toolchain install gcc 16` | 安装工具链 |
+| `mcpp pack` | 打包 |
+| `mcpp self doctor` | 环境诊断 |
+| `mcpp explain <CODE>` | 错误码解释 |
+
+## 安装
+
+```bash
+# 推荐
+xlings install mcpp -y
+
+# 或一键脚本
+curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/install.sh | bash
+```
+
+安装到 `~/.mcpp/`，自动加入 PATH。首次运行自动安装 GCC 工具链到隔离沙盒。
+
+## 创建项目
+
+```bash
+mcpp new hello && cd hello
+mcpp build
+mcpp run
+```
+
+生成的 `mcpp.toml`：
+
+```toml
+[package]
+name = "hello"
+
+[targets.hello]
+kind = "bin"
+main = "src/main.cpp"
+```
+
+## mcpp.toml 配置
+
+```toml
+[package]
+name = "myapp"
+version = "0.1.0"
+
+[targets.myapp]
+kind = "bin"                # bin / lib / shared / test
+main = "src/main.cpp"
+
+[dependencies]
+gtest = "1.15.2"            # SemVer: ^, ~, 范围, 精确
+
+[toolchain]
+default = "gcc@16.1.0"
+```
+
+更多配置：https://github.com/mcpp-community/mcpp/blob/main/docs/05-mcpp-toml.md
+
+## 工具链
+
+```bash
+mcpp toolchain list                   # 查看已装
+mcpp toolchain install gcc 16         # 装 GCC 16
+mcpp toolchain install llvm 20        # 装 LLVM 20
+mcpp toolchain default gcc@16.1.0    # 设默认
+```
+
+## 工作空间
+
+```toml
+[workspace]
+members = ["libs/*", "apps/*"]
+
+[workspace.dependencies]
+gtest = "1.15.2"
+```
+
+```bash
+mcpp build -p member-name    # 构建指定成员
+```
+
+## 自定义索引
+
+```toml
+[indices]
+my-index = "git@gitlab.example.com:team/index.git"
+local = { path = "/path/to/index" }
+
+[dependencies.my-index]
+internal-lib = "1.0.0"
+```
+
+## 常见问题
+
+| 问题 | 解决 |
+|---|---|
+| 首次构建慢 | 正常，需下载工具链。后续使用缓存 |
+| command not found | 重启终端或 `source ~/.bashrc` |
+| 编译错误 | `mcpp clean && mcpp build`，确认 `mcpp toolchain list` |
+| 依赖找不到 | `mcpp index update`，确认 `mcpp search <name>` |
+
+## 问题反馈
+
+1. **项目 Issue**：https://github.com/mcpp-community/mcpp/issues
+   - 描述复现步骤、期望/实际行为、mcpp 版本和 OS
+   - 可用 `gh issue create` 提交
+
+2. **社区论坛**：https://forum.d2learn.org/category/20
+   - 使用疑问和讨论
+
+如果 AI Agent 无法直接创建 Issue，请提示用户手动创建并提供整理好的问题描述。
diff --git a/README.md b/README.md
index c31aaf2..bb806ee 100644
--- a/README.md
+++ b/README.md
@@ -71,7 +71,7 @@ curl -fsSL https://github.com/mcpp-community/mcpp/releases/latest/download/insta
 ```
 阅读 https://github.com/mcpp-community/mcpp 的 README，
 帮我安装 mcpp 并创建一个 C++23 模块项目，构建并运行。
-项目的 .agents/skills/ 目录下有更多使用指南供参考。
+项目的 .agents/skills/mcpp-usage/SKILL.md 有详细的使用指南。
 ```
 
 ### 创建项目 & 构建运行
@@ -207,9 +207,9 @@ main = "src/main.cpp"
 **AI 辅助学习**：你可以将以下提示词发给 AI 编码助手，让它帮你快速了解 mcpp：
 
 ```
-阅读 https://github.com/mcpp-community/mcpp 的文档（docs/ 目录），
+阅读 https://github.com/mcpp-community/mcpp 仓库的
+.agents/skills/mcpp-usage/SKILL.md 和 docs/ 目录下的文档，
 告诉我如何用 mcpp 创建一个带依赖的 C++23 模块项目。
-项目的 .agents/skills/ 目录下有详细的使用指南和贡献指南。
 ```
 
 ## 参与贡献
@@ -225,10 +225,11 @@ main = "src/main.cpp"
 
 **提交信息规范**：`feat:` / `fix:` / `test:` / `docs:` / `refactor:` 前缀
 
-**AI Agent 贡献指南**：项目的 [`.agents/skills/contributing.md`](.agents/skills/contributing.md) 提供了完整的 Agent 贡献流程、工具使用和项目结构说明。将以下提示词发给 AI 助手即可：
+**AI Agent 贡献**：项目的 [`.agents/skills/mcpp-contributing/SKILL.md`](.agents/skills/mcpp-contributing/SKILL.md) 提供了完整的 Agent 贡献流程和项目结构说明。将以下提示词发给 AI 助手即可：
 
 ```
-阅读 https://github.com/mcpp-community/mcpp 仓库的 .agents/skills/contributing.md，
+阅读 https://github.com/mcpp-community/mcpp 仓库的
+.agents/skills/mcpp-contributing/SKILL.md，
 按照指南帮我给 mcpp 项目提交一个贡献。
 ```
 

From c5f9cb68bd64d59b7a504e523598298f2ec15748 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Sat, 16 May 2026 07:34:23 +0800
Subject: [PATCH 4/6] docs: add modular library usage example to README

---
 README.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/README.md b/README.md
index bb806ee..31bbff8 100644
--- a/README.md
+++ b/README.md
@@ -104,6 +104,23 @@ kind = "bin"
 main = "src/main.cpp"
 ```
 
+### 使用模块化库
+
+在 `mcpp.toml` 中添加两行依赖，即可引用 [mcpplibs](https://github.com/mcpplibs) 社区模块化库：
+
+```toml
+[dependencies]
+cmdline = "0.0.2"
+```
+
+然后在代码中直接 `import`：
+
+```cpp
+import mcpplibs.cmdline;
+```
+
+> 更多依赖配置方式（版本约束、命名空间、Git 引用、本地路径等）参见 [mcpp.toml 指南 — 依赖管理](docs/05-mcpp-toml.md)。
+
 ## 功能概览
 
 <details>

From 25f7a205328c0ed08c44bc5a14250bccbf63b41c Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Sat, 16 May 2026 07:36:13 +0800
Subject: [PATCH 5/6] docs: add contribution invitation to early-version notice

---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index 31bbff8..e1c6b2a 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,7 @@ mcpp 专门为 **C++23 模块化开发** 打造。如果你想在项目中使用
 
 > [!NOTE]
 > **早期版本** — mcpp 仍在积极开发中，接口和行为可能在后续版本调整。
+> 欢迎对现代 C++ 模块化构建工具感兴趣的开发者[参与贡献](#参与贡献)。
 > 问题 / 反馈 / 想法欢迎在 [issues](https://github.com/mcpp-community/mcpp/issues) 留言。
 
 ## 快速开始

From b940caf796a88ca784d0ca1e0058cd3e9bb4810f Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Sat, 16 May 2026 08:40:25 +0800
Subject: [PATCH 6/6] docs: add demo GIF to README

---
 README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/README.md b/README.md
index e1c6b2a..017c38d 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,10 @@
 [![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules)
 [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)
 
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/6c85896e-9a37-4f62-acfb-d37a4eae2363" alt="mcpp demo" width="720">
+</p>
+
 ## 核心特性
 
 - **C++23 模块原生支持** — `import std` 自动处理，文件级增量构建，模块依赖自动分析，零手动配置