docs: README 重设计 — 核心特性、AI 辅助上手、贡献者指南

.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 讨论再动手

.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，请提示用户手动创建并提供整理好的问题描述。