# 通用技能库仓库

**Repository Path**: map_development/general-skill-library

## Basic Information

- **Project Name**: 通用技能库仓库
- **Description**: 通用技能库仓库，集中管理 Claude Code、codex、qoder 自定义技能和 MCP 服务配置。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# general-skill-library

通用技能库仓库，集中管理 Claude Code、codex、qoder 自定义技能和 MCP 服务配置。

## 快速上手（新机器）

```bash
# 1. 克隆到任意位置
git clone <repo-url> ~/general-skill-library
cd ~/general-skill-library

# 2. 配置凭据
cp .env.example .env
# 编辑 .env，填入你自己的服务地址和凭据
# 没有的服务可以留空或删除对应变量，MCP 启动失败不影响其他功能

# 3. 安装技能（创建符号链接到 ~/.claude/skills/、~/.codex/skills/ 和 ~/.qoder/skills/）
chmod +x setup.sh
./setup.sh

# 4. 同步 MCP 服务配置到 Claude + Codex + Qoder（自动从 .env 读取凭据）
bash scripts/sync-mcp-config.sh

# 5. 校验四端配置一致性（可选）
bash scripts/doctor-sync.sh

# 6. 重启 Claude Code / Codex / Qoder CLI，确认 MCP 服务正常连接
#    （在 Claude Code 中执行 /mcp 查看状态）
```

> **Windows 用户**：使用 **Git Bash** 运行上述脚本，或使用 PowerShell（管理员）运行：
> ```powershell
> .\setup.ps1 -Force
> ```

### MCP 配置说明

MCP 服务配置统一由 `mcp/mcp-servers.json` 管理（含 `${VAR_NAME}` 占位符），通过 `scripts/sync-mcp-config.sh` 同步到以下位置：
- `~/.claude.json`（顶层 `mcpServers`，Claude Code 全局生效）
- `~/.codex/config.toml`（Codex）
- `~/.qoder/mcp.json`（Qoder CLI，全局生效）

**首次使用**：创建 `.env` 文件并填入真实凭据：

```bash
cp .env.example .env
# 编辑 .env，将 your-xxx 替换为实际值
# 没有的服务可跳过，删除对应 mcp-servers.json 中的条目即可
```

同步脚本会自动读取 `.env`，替换 `mcp/mcp-servers.json` 中的 `${VAR_NAME}` 占位符，再写入上述目标配置。

> `mcp/mcp-servers.json` 是模板文件（含 `${VAR}` 占位符），已纳入版本控制。`.env` 存储真实凭据，已被 `.gitignore` 忽略，不会误提交。

**可选服务**：以下 MCP 服务可按需配置，缺失不影响其他功能：
- **dj_server / dqm_server / jz_server / mc_server / local_server**：数据库直连查询（需 ADB MySQL 环境）
- **yunxiao**：阿里云云效 DevOps API
- **archery / yearning**：SQL 查询审核平台
- **context7**：编程文档查询（公开服务，无需配置）
- **pencil**：设计稿编辑（需单独安装客户端）

配置中使用以下内置占位符，同步时自动替换：
- `__PROJECT_DIR__` → 本项目实际路径（如 `/Users/xxx/general-skill-library`）
- `__HOME__` → 当前用户 home 目录

修改 MCP 配置后：
```bash
bash scripts/sync-mcp-config.sh
bash scripts/doctor-sync.sh
```

git commit 时也会通过 pre-commit 钩子自动同步。

### 新增 MCP 服务

以新增一个名为 `example` 的 MCP 服务为例：

1. **在 `mcp/mcp-servers.json` 的 `mcpServers` 中添加条目**：

   ```json
   "example": {
     "command": "uv",
     "args": ["run", "--python", "3.13", "--with", "example-mcp", "example-mcp"],
     "env": {
       "EXAMPLE_API_KEY": "${EXAMPLE_API_KEY}",
       "EXAMPLE_BASE_URL": "${EXAMPLE_BASE_URL}"
     },
     "type": "stdio"
   }
   ```

2. **在 `.env` 中添加对应凭据**（`${VAR_NAME}` 占位符会自动替换）：

   ```bash
   EXAMPLE_API_KEY=sk-xxx
   EXAMPLE_BASE_URL=https://api.example.com
   ```

3. **同步生效**：

   ```bash
   bash scripts/sync-mcp-config.sh
   bash scripts/doctor-sync.sh   # 校验配置一致性
   ```

4. **重启 Claude Code / Codex**，运行 `/mcp` 确认服务状态。

> 如果 MCP 服务不需要凭据（如 context7），可以省略 `.env` 步骤，`env` 留空即可。如果是本地 Python 脚本，参照 archery/yearning 将 `command` 设为 `uv`、`args` 指向 `__PROJECT_DIR__/mcp/your-script.py`。

### 前置依赖

| 工具 | 用途 | 安装方式 |
|------|------|----------|
| [uv](https://docs.astral.sh/uv/) | Python 包管理器，运行 MCP 服务 | **macOS/Linux**：`curl -LsSf https://astral.sh/uv/install.sh \| sh`<br>**Windows PowerShell**：`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"` |
| python3 | 配置同步脚本依赖（安装 uv 后自带） | 随 uv 安装 |
| Node.js / npx | 运行 yunxiao、context7 等 MCP 服务 | macOS: `brew install node` / Windows: [nodejs.org](https://nodejs.org) |
| [Pencil](https://pencil.bgytb.cn) | 设计稿编辑（可选） | 单独安装，二进制位于 `~/.pencil/` |

## 技能分类

### 开发 (development)
| 技能 | 描述 |
|------|------|
| [backend-code-generate](skills/development/backend-code-generate) | 后端代码生成 |
| [backend-db-design-migration](skills/development/backend-db-design-migration) | 数据库设计与迁移 |
| [backend-workflow](skills/development/backend-workflow) | 后端智能开发编排 |
| [db-schema-analyzer](skills/development/db-schema-analyzer) | 数据库表关系分析 |
| [frontend-code-generate](skills/development/frontend-code-generate) | 前端代码生成 |
| [frontend-component-decompose](skills/development/frontend-component-decompose) | 前端组件拆分与复用 |
| [frontend-development-skills](skills/development/frontend-development-skills) | 前端开发技能集 |
| [frontend-integration](skills/development/frontend-integration) | 前端集成 |
| [frontend-style-align](skills/development/frontend-style-align) | 前端风格对齐 |
| [frontend-test](skills/development/frontend-test) | 前端测试 |
| [frontend-workflow](skills/development/frontend-workflow) | 前端智能开发编排 |
| [java-dev](skills/development/java-dev) | Java 开发 |
| [lakehouse-workflow](skills/development/lakehouse-workflow) | 湖仓智能开发编排（DataWorks + DLF 3.0） |
| [plan-mode](skills/development/plan-mode) | 计划模式 |
| [prd-workflow](skills/development/prd-workflow) | PRD 工作流 |

### 文档 (documents)
| 技能 | 描述 |
|------|------|
| [announcement-draft](skills/documents/announcement-draft) | 公告草稿 |
| [business-letter](skills/documents/business-letter) | 商务信函 |
| [contract-review](skills/documents/contract-review) | 合同审查 |
| [customer-proposal](skills/documents/customer-proposal) | 客户方案/标书 |
| [email-draft](skills/documents/email-draft) | 邮件草稿 |
| [meeting-minutes](skills/documents/meeting-minutes) | 会议纪要 |
| [office-reader](skills/documents/office-reader) | Office 文档读取 |
| [ppt-outline](skills/documents/ppt-outline) | PPT 大纲 |
| [sop-writer](skills/documents/sop-writer) | SOP 撰写 |
| [training-material](skills/documents/training-material) | 培训材料 |

### 测试 (qa-test)
| 技能 | 描述 |
|------|------|
| [qa-api-test](skills/qa-test/qa-api-test) | 接口自动化测试 |
| [qa-testcase](skills/qa-test/qa-testcase) | 测试用例生成 |
| [qa-workflow](skills/qa-test/qa-workflow) | QA 工作流 |

### 数据分析 (data-analysis)
| 技能 | 描述 |
|------|------|
| [competitor-analysis](skills/data-analysis/competitor-analysis) | 竞品分析 |
| [data-analysis-report](skills/data-analysis/data-analysis-report) | 数据分析报告 |
| [excel-quotation](skills/data-analysis/excel-quotation) | Excel 报价 |
| [market-research](skills/data-analysis/market-research) | 市场调研 |

### 管理 (management)
| 技能 | 描述 |
|------|------|
| [interview-assistant](skills/management/interview-assistant) | 面试助手 |
| [jd-generator](skills/management/jd-generator) | JD 生成 |
| [okr-kpi](skills/management/okr-kpi) | OKR/KPI 目标管理 |
| [resume-template-mapper](skills/management/resume-template-mapper) | 简历模板映射 |
| [weekly-report](skills/management/weekly-report) | 周报/日报 |

### 工具 (utils)
| 技能 | 描述 |
|------|------|
| [find-skills](skills/utils/find-skills) | 技能发现与安装 |
| [invoice-organizer](skills/utils/invoice-organizer) | 发票整理 |
| [software-copyright](skills/utils/software-copyright) | 软件著作权 |
| [translation-assistant](skills/utils/translation-assistant) | 翻译助手 |

### 运维 (ops)
| 技能 | 描述 |
|------|------|
| [harness-engineering](skills/harness-engineering) | Harness 工程化配置（Claude Code / Codex / Qoder） |
| [loop-engineering](skills/loop-engineering) | Loop 工程化配置（可验证停止/反馈闭环/自主迭代/自修复） |
| [prod-data-fix-archery](skills/ops/prod-data-fix-archery) | 生产数据修复（Archery） |
| [prod-data-fix-yearning](skills/ops/prod-data-fix-yearning) | 生产数据修复（Yearning） |
| [work-order-resume](skills/ops/work-order-resume) | 工单状态检查与恢复 |
| [yearning-query-workflow](skills/yearning-query-workflow) | Yearning 数据查询工作流 |

## 技能协作关系

```
prd-workflow（产品审查 PRD）
     |
     | 输出补全后的 PRD
     |
     +---> backend-workflow（开发读 PRD → 写代码）        ┐
     |       |-- db-schema-analyzer（连库查表）            │
     |       |-- backend-db-design-migration（设计表）     │
     |       |-- backend-code-generate（生成代码）         │
     |       +-- 输出：代码 + SQL + 技术实现文档           │
     |                                                    ├── 并行、独立
     +---> frontend-workflow（开发读 PRD → 写前端）        │
     |       |-- frontend-component-decompose（拆组件）    │
     |       |-- frontend-code-generate（生成代码）        │
     |       |-- frontend-style-align（对齐设计稿）        │
     |       +-- 输出：代码 + 技术实现文档                 │
     |                                                    │
     +---> qa-workflow（QA 读 PRD → 写用例 → 测接口）      ┘
             |-- qa-testcase（设计用例）
             |-- qa-api-test（生成脚本）
             +-- 输出：测试用例 + 脚本 + 测试报告

     +---> lakehouse-workflow（湖仓开发 → 建模 → 调度）
             |-- db-schema-analyzer（连库查表）
             |-- yunxiao（云效工单管理）
             |-- yearning（数据查询验证）
             +-- 输出：DDL + 数据集成 + 调度配置 + 质量检测
```

QA 与开发并行工作：QA 拿到 PRD 就可以开始设计用例，不需要等开发完成。

## 安装

将本仓库的技能安装到 `~/.claude/skills/`、`~/.codex/skills/` 和 `~/.qoder/skills/`：

```bash
chmod +x setup.sh
./setup.sh
```

该脚本会递归查找 `skills/` 下所有含 `SKILL.md` 的目录，为每个技能在 `~/.claude/skills/` 和 `~/.codex/skills/` 下创建独立的符号链接（Windows 下自动降级为复制），并配置 git hooks 实现自动同步。

### 强制重新安装

```bash
./setup.sh -f
```

覆盖所有已有技能（静默模式，用于 git hooks 自动调用）。

### 自动同步

仓库包含 git hooks（`.githooks/`），会在以下场景自动执行：

| 触发时机 | 操作 |
|----------|------|
| **`git commit`** 前 | 同步 MCP 配置到 `~/.claude.json` + `~/.codex/config.toml` + `~/.qoder/mcp.json` + 安装 skills |
| **`git pull` / `git merge`** 后 | 如果 `skills/` 有变更，自动安装 skills 到 Claude/Codex/Qoder |
| **`git checkout`** 切分支后 | 如果 `skills/` 有变更，自动安装 skills 到 Claude/Codex/Qoder |

首次运行 `./setup.sh` 时会自动配置 git hooks。

## 文档

- [Agent 核心工作规则](AGENTS.md)
- [后端技能概览](docs/backend-skills-overview.md)
- [AI Coding 规范](docs/guides/)
  - [后端开发 AI Coding 规范](docs/guides/后端开发%20AI%20Coding%20规范.md)
  - [前端开发 AI Coding 规范](docs/guides/前端开发%20AI%20Coding%20规范.md)
  - [产品 PRD AI Coding 规范](docs/guides/产品PRD%20AI%20Coding%20规范.md)
  - [测试 AI Coding 规范](docs/guides/测试%20AI%20Coding%20规范.md)
  - [技能库使用说明](docs/guides/技能库使用说明.md)
- [前端参考文档](docs/frontend/)
  - [前端开发指南](docs/frontend/FRONTEND-SKILLS-GUIDE.md)
  - [前端技能摘要](docs/frontend/FRONTEND-SKILLS-SUMMARY.md)
  - [前端教程](docs/frontend/FRONTEND-SKILLS-TUTORIAL.md)
  - [前端工作流标准](docs/frontend/FRONTEND-WORKFLOW-STANDARDS.md)
  - [前端文档管理](docs/frontend/FRONTEND-DOC-MANAGEMENT.md)
  - [前端技能契约](docs/frontend/FRONTEND-SKILL-CONTRACT.md)

## 许可证

[MIT](LICENSE)