# https://github.com/Basic-XYZ/baku-skills 项目说明书

生成时间：2026-07-20 05:04:06 UTC

## 目录

- [仓库概览、安装与目录结构](#page-1)
- [baku-coding-discipline 编码纪律（推荐首选安装）](#page-2)
- [baku-design-system 与 baku-illustrations（视觉类技能）](#page-3)
- [baku-mind-cleaner 与 codex-history-recovery（流程与运维类技能）](#page-4)

<a id='page-1'></a>

## 仓库概览、安装与目录结构

### 相关页面

相关主题：[baku-coding-discipline 编码纪律（推荐首选安装）](#page-2), [baku-design-system 与 baku-illustrations（视觉类技能）](#page-3), [baku-mind-cleaner 与 codex-history-recovery（流程与运维类技能）](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Basic-XYZ/baku-skills/blob/main/README.md)
- [README.en.md](https://github.com/Basic-XYZ/baku-skills/blob/main/README.en.md)
- [package.json](https://github.com/Basic-XYZ/baku-skills/blob/main/package.json)
- [bin/skills.js](https://github.com/Basic-XYZ/baku-skills/blob/main/bin/skills.js)
- [PROMOTION.md](https://github.com/Basic-XYZ/baku-skills/blob/main/PROMOTION.md)
- [LICENSE](https://github.com/Basic-XYZ/baku-skills/blob/main/LICENSE)
</details>

# 仓库概览、安装与目录结构

## 1. 项目定位与目标

Baku Skills 是一个**以中文为主（Chinese-first）的 Agent Skills 仓库**，专注于沉淀来自 Codex 与 Claude Code 真实工作流中的实践型 Skill 资源，并通过 `skills` 命令行工具进行分发与管理。项目核心理念可以概括为三点：

- **真实工作流驱动**：每个 Skill 都来自日常编码辅助场景，而非凭空设计 资料来源：[README.md:1-15]()
- **中文优先**：默认 README 为中文版（`README.md`），同时提供英文版（`README.en.md`）以服务国际用户 资料来源：[README.en.md:1-10]()
- **代理可控、可验证**：首个推荐安装的 `coding-discipline` Skill 强调让 Coding Agent 保持范围聚焦、证据驱动与可验证 资料来源：[README.md:17-25]()

首个公开版本 v0.1.0 中包含三个核心 Skill：`coding-discipline`、`boss-job-hunter` 以及 `resume-analyzer`，分别对应编码规范、招聘评估与简历分析场景 资料来源：[README.md:27-40]()。

## 2. 安装方式

仓库提供两种安装方式：**手动克隆安装**与 **NPM 全局安装**。

### 2.1 手动克隆安装

通过 `git clone` 拉取仓库后，直接运行 `bin/skills.js` 即可，无需任何额外依赖 资料来源：[README.md:42-55]()。这种方式适合希望快速试用或参与本地开发的用户。

### 2.2 NPM 全局安装

通过 `npm install -g baku-skills` 安装后，可在任意位置使用 `skills` 命令 资料来源：[package.json:1-20]()。CLI 入口文件声明于 `package.json` 的 `bin` 字段：

```json
"bin": {
  "skills": "bin/skills.js"
}
```
资料来源：[package.json:8-12]()

`bin/skills.js` 是一个独立的 Node.js 脚本，作为 `skills` 命令的入口分发器，体积轻量，不依赖第三方包 资料来源：[bin/skills.js:1-20]()。

## 3. 目录结构

仓库采用**扁平化 + Skill 目录**的混合结构，便于扩展与版本管理。

| 路径 | 作用 |
|------|------|
| `README.md` / `README.en.md` | 中英文项目说明文档 资料来源：[README.md:1-10]() |
| `LICENSE` | 开源许可证文件 资料来源：[LICENSE:1-5]() |
| `PROMOTION.md` | 项目宣传与发布说明 资料来源：[PROMOTION.md:1-10]() |
| `package.json` | NPM 包元数据与 CLI 入口声明 资料来源：[package.json:1-20]() |
| `bin/skills.js` | `skills` 命令入口脚本 资料来源：[bin/skills.js:1-20]() |
| `skills/<skill-name>/` | 各 Skill 的定义目录（包含 SKILL.md、规则、模板等） 资料来源：[README.md:55-70]() |

每个 Skill 目录内部遵循统一的 **SKILL 规范**：包含一个 `SKILL.md` 描述文件，以及若干配套资源文件，使 CLI 工具能够按统一接口发现与加载 资料来源：[README.md:60-75]()。

## 4. 工作流与架构示意

下图展示了从用户输入 `skills` 命令到 Skill 加载执行的完整流程：

```mermaid
flowchart LR
    A[用户执行 skills 命令] --> B[bin/skills.js 入口]
    B --> C{解析子命令}
    C -->|list| D[扫描 skills/ 目录]
    C -->|install| E[注册 Skill 到目标平台]
    C -->|run| F[加载 SKILL.md 并执行]
    D --> G[输出可用 Skill 列表]
    E --> H[Codex / Claude Code]
    F --> H
    H --> I[代理执行任务]
```

CLI 入口在 `bin/skills.js` 中负责命令解析，Skill 注册与执行则由下游代理（Codex / Claude Code）完成 资料来源：[bin/skills.js:1-40]()[README.md:42-55]()。

## 5. 推荐起点与最佳实践

根据项目自身的推荐策略，首次使用者应优先安装 `coding-discipline`，以确保后续所有 Skill 调用都遵循**范围聚焦、证据驱动、可验证**的基本原则 资料来源：[README.md:17-25]()[PROMOTION.md:10-25]()。

> **使用建议**：建议在每次开启新的编码会话前确认 `coding-discipline` 已加载，作为"前置守门人"使用，避免 Agent 越权或缺乏证据地进行修改 资料来源：[README.md:30-40]()

通过 `skills list` 可随时查看本地已安装的 Skill 列表，结合 CLI 的统一分发机制，用户能够在不同项目之间无缝复用同一套 Agent 工作流规范 资料来源：[README.md:55-65]()[bin/skills.js:15-30]()。

---

<a id='page-2'></a>

## baku-coding-discipline 编码纪律（推荐首选安装）

### 相关页面

相关主题：[仓库概览、安装与目录结构](#page-1), [baku-design-system 与 baku-illustrations（视觉类技能）](#page-3), [baku-mind-cleaner 与 codex-history-recovery（流程与运维类技能）](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [baku-coding-discipline/SKILL.md](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-coding-discipline/SKILL.md)
- [baku-coding-discipline/README.md](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-coding-discipline/README.md)
- [baku-coding-discipline/CHANGELOG.md](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-coding-discipline/CHANGELOG.md)
- [baku-coding-discipline/CONTRIBUTING.md](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-coding-discipline/CONTRIBUTING.md)
- [baku-coding-discipline/references/mode-routing.md](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-coding-discipline/references/mode-routing.md)
- [baku-coding-discipline/references/module-boundary-design.md](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-coding-discipline/references/module-boundary-design.md)
</details>

# baku-coding-discipline 编码纪律（推荐首选安装）

## 概述与定位

`baku-coding-discipline` 是 Baku Skills v0.1.0 发布的三个核心技能之一，作为"推荐首选安装"项存在，其目标是把 Codex / Claude Code 这类编码 Agent 约束为"范围受控、证据驱动、验证导向"的工作形态，避免模型在缺乏上下文时盲目扩散修改或编造结果。资料来源：[baku-coding-discipline/README.md:1-20]()

作为面向中文工作流的技能包，它与同仓库的 `boss-job-hunter` 等业务向技能保持解耦，专注于编码过程本身的方法论约束，因而可以先行安装并作为后续业务技能的前置基座。资料来源：[baku-coding-discipline/SKILL.md:1-15]()

## 核心约束原则

技能围绕三条主线对 Agent 行为施加纪律：

- **范围受控（Scoped）**：要求 Agent 在接到任务时先界定影响面，禁止跨模块无授权改动。资料来源：[baku-coding-discipline/SKILL.md:10-30]()
- **证据驱动（Evidence-Driven）**：所有结论与代码修改必须可追溯到仓库中的具体文件、符号或运行输出，禁止凭空推断。资料来源：[baku-coding-discipline/README.md:25-45]()
- **验证导向（Verification-Oriented）**：修改必须配套可执行的验证步骤，例如编译、测试或命令复现，否则视为未完成。资料来源：[baku-coding-discipline/SKILL.md:30-55]()

这三条原则共同构成了技能在 README 与 SKILL.md 中反复强调的"先证后改"工作流。资料来源：[baku-coding-discipline/README.md:50-70]()

## 模式路由（Mode Routing）

技能通过 `references/mode-routing.md` 引入模式路由机制，将用户输入分配到不同的处理模式，使 Agent 在面对编码、问答、复审等场景时不会使用同一种行为模板。资料来源：[baku-coding-discipline/references/mode-routing.md:1-25]()

典型的路由节点包含：

| 触发条件 | 进入模式 | 主要约束 |
| --- | --- | --- |
| 明确要求修改代码 | `coding` | 必须输出 diff + 验证命令 |
| 仅询问实现思路 | `explain` | 仅给方案，不写代码 |
| 要求审查既有改动 | `review` | 引用行号并给出结论 |
| 信息不足时 | `clarify` | 反问澄清，禁止猜测 |

资料来源：[baku-coding-discipline/references/mode-routing.md:30-80]()

这一机制直接服务于"范围受控"原则——通过显式分流，避免 Agent 把解释场景误当作编码任务，从而产出多余的修改。资料来源：[baku-coding-discipline/references/mode-routing.md:85-110]()

## 模块边界设计（Module Boundary Design）

`references/module-boundary-design.md` 给出在多文件、多模块仓库中如何划定 Agent 可触碰的边界，确保修改被限制在用户授权的目录与文件类型之内。资料来源：[baku-coding-discipline/references/module-boundary-design.md:1-20]()

关键约定包括：

- 在任务开始时建立"白名单目录 + 允许的文件后缀"集合，所有改动必须落在集合内。资料来源：[baku-coding-discipline/references/module-boundary-design.md:25-50]()
- 跨边界访问（例如从 `src/` 引用 `tests/`）需要明确理由并写入回复。资料来源：[baku-coding-discipline/references/module-boundary-design.md:55-80]()
- 一旦检测到越界改动，应回滚到最近一次校验点，而非继续累积错误。资料来源：[baku-coding-discipline/references/module-boundary-design.md:85-110]()

该文件与模式路由配合使用：路由决定"做什么"，模块边界决定"在哪里做"。资料来源：[baku-coding-discipline/references/module-boundary-design.md:115-130]()

## 协作与变更流程

技能以独立子目录形式发布，遵循仓库统一的协作约定。`CONTRIBUTING.md` 规定新增规则需在 `references/` 下提供独立文档，避免主 SKILL.md 膨胀。资料来源：[baku-coding-discipline/CONTRIBUTING.md:1-25]()

版本演进通过 `CHANGELOG.md` 记录，按语义化版本管理：新增模式路由或边界规则视为 minor 升级，破坏既有约束的调整视为 major 升级。资料来源：[baku-coding-discipline/CHANGELOG.md:1-20]()

## 安装与使用建议

由于该技能被官方标注为"推荐首选安装"，建议在引入其它 Baku Skills 之前完成部署，以便后续技能继承其行为约束范式。资料来源：[baku-coding-discipline/README.md:75-95]()

最小使用流程：

1. 将 `baku-coding-discipline/` 整体放入 Codex / Claude Code 的 skills 加载路径。资料来源：[baku-coding-discipline/README.md:95-110]()
2. 在 Agent 提示词中显式声明启用本技能，确保 SKILL.md 的约束被优先加载。资料来源：[baku-coding-discipline/SKILL.md:60-75]()
3. 首次任务以一个小型修改进行演练，验证模式路由与模块边界是否生效。资料来源：[baku-coding-discipline/README.md:115-130]()

完成上述步骤后，`coding-discipline` 即作为后续 Agent 行为的基线，所有任务的回复都将以"范围受控、证据驱动、验证导向"为默认形态。资料来源：[baku-coding-discipline/SKILL.md:80-95]()

---

<a id='page-3'></a>

## baku-design-system 与 baku-illustrations（视觉类技能）

### 相关页面

相关主题：[仓库概览、安装与目录结构](#page-1), [baku-coding-discipline 编码纪律（推荐首选安装）](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [baku-design-system/SKILL.md](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-design-system/SKILL.md)
- [baku-design-system/README.md](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-design-system/README.md)
- [baku-design-system/brand-dna.md](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-design-system/brand-dna.md)
- [baku-design-system/agents/openai.yaml](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-design-system/agents/openai.yaml)
- [baku-design-system/references/checklist.md](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-design-system/references/checklist.md)
- [baku-design-system/references/components.md](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-design-system/references/components.md)
- [baku-illustrations/SKILL.md](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-illustrations/SKILL.md)
- [baku-illustrations/README.md](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-illustrations/README.md)
</details>

# baku-design-system 与 baku-illustrations（视觉类技能）

`baku-design-system` 与 `baku-illustrations` 是 Baku Skills v0.1.0 中并列存在的两个视觉类 Agent Skills，分别承担"设计系统规则"与"插画素材生产"两类职责。它们被设计为可被 Codex / Claude Code 等编码代理直接调用的独立 Skill 单元。

## 1. 角色定位与边界

两个技能在视觉生产链路中分工明确：

- `baku-design-system`：定义品牌的"视觉宪法"，包括色板、字体、间距、组件规范与品牌 DNA，作为其它视觉产出（页面、组件、插画）的约束源。
- `baku-illustrations`：在 `baku-design-system` 的视觉约束下，提供插画素材生成、风格统一与可复用图样输出的能力。

二者通过 `brand-dna.md` 这一共享约束文件解耦：`baku-design-system` 维护权威定义，`baku-illustrations` 在引用时只读取而不修改，确保品牌一致性。

资料来源：[baku-design-system/SKILL.md:1-30](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-design-system/SKILL.md)、[baku-illustrations/SKILL.md:1-30](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-illustrations/SKILL.md)

## 2. baku-design-system 的内部结构

该 Skill 的目录遵循 Baku Skills 的统一约定：

| 路径 | 作用 |
|---|---|
| `SKILL.md` | 技能入口声明、激活条件、面向代理的指令摘要 |
| `README.md` | 安装、调用方式与适用场景的人类可读说明 |
| `brand-dna.md` | 品牌核心：色板、字体、语气、Logo 使用规则 |
| `agents/openai.yaml` | 在 OpenAI 兼容代理下的技能描述与模型行为配置 |
| `references/checklist.md` | 交付前自检清单，用于验证设计是否符合规范 |
| `references/components.md` | 组件级规范，覆盖按钮、卡片、表单等通用 UI 元素 |

代理在加载该 Skill 后，会优先读取 `SKILL.md` 触发自身行为，并将 `references/` 下的清单与组件规范作为生成新页面/组件时的对照基准。

资料来源：[baku-design-system/README.md:1-40](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-design-system/README.md)、[baku-design-system/references/components.md:1-60](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-design-system/references/components.md)

## 3. baku-illustrations 的协作模式

`baku-illustrations` 并不独立"创造"品牌语言，而是消费 `baku-design-system` 的输出。其典型调用流程如下：

```mermaid
flowchart LR
    A[baku-design-system<br/>brand-dna.md] --> B[baku-illustrations<br/>SKILL.md]
    B --> C[读取色板与字体约束]
    C --> D[生成插画/SVG/示意图]
    D --> E{是否符合 checklist?}
    E -- 否 --> F[回写修正]
    E -- 是 --> G[交付最终素材]
```

代理在响应"生成插画"类请求时，会先加载 `baku-illustrations/SKILL.md`，再按需引用 `baku-design-system` 中的品牌约束。这种"约束源 + 消费者"模式与 v0.1.0 发布说明中提到的"基于真实 Codex / Claude Code 工作流沉淀"的设计理念一致。

资料来源：[baku-illustrations/SKILL.md:1-50](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-illustrations/SKILL.md)、[baku-illustrations/README.md:1-40](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-illustrations/README.md)、[baku-design-system/brand-dna.md:1-50](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-design-system/brand-dna.md)

## 4. 共同协作约束

两个视觉类技能共享以下约定：

- **中文优先**：所有说明文件以中文撰写，文件名与字段名仍保持英文以兼容工具链。
- **清单驱动**：`baku-design-system/references/checklist.md` 同时被两个技能引用，作为交付前最后一道闸口。
- **代理可读**：`agents/openai.yaml` 显式声明技能描述，使 OpenAI 兼容代理能在多 Skill 场景下正确路由。
- **可组合性**：与 `coding-discipline`、`boss-job-hunter` 等其它 Skill 并列安装时不会产生命名或路由冲突。

资料来源：[baku-design-system/references/checklist.md:1-50](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-design-system/references/checklist.md)、[baku-design-system/agents/openai.yaml:1-30](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-design-system/agents/openai.yaml)、[baku-illustrations/README.md:1-40](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-illustrations/README.md)

---

<a id='page-4'></a>

## baku-mind-cleaner 与 codex-history-recovery（流程与运维类技能）

### 相关页面

相关主题：[仓库概览、安装与目录结构](#page-1), [baku-coding-discipline 编码纪律（推荐首选安装）](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [baku-mind-cleaner/SKILL.md](https://github.com/Basic-XYZ/baku-skills/blob/main/baku-mind-cleaner/SKILL.md)
- [codex-history-recovery/SKILL.md](https://github.com/Basic-XYZ/baku-skills/blob/main/codex-history-recovery/SKILL.md)
- [codex-history-recovery/README.md](https://github.com/Basic-XYZ/baku-skills/blob/main/codex-history-recovery/README.md)
- [codex-history-recovery/agents/openai.yaml](https://github.com/Basic-XYZ/baku-skills/blob/main/codex-history-recovery/agents/openai.yaml)
- [codex-history-recovery/scripts/codex_history_repair.py](https://github.com/Basic-XYZ/baku-skills/blob/main/codex-history-recovery/scripts/codex_history_repair.py)
</details>

# baku-mind-cleaner 与 codex-history-recovery（流程与运维类技能）

## 概述与定位

Baku Skills 是一个面向 Codex / Claude Code 工作流的中文优先 Agent Skills 仓库，v0.1.0 首发版本除包含 `coding-discipline`、`boss-job-hunter` 之外，还纳入了两个"流程与运维"类技能：`baku-mind-cleaner` 与 `codex-history-recovery`。前者负责清理 Agent 在本地的"心智"残留状态，后者用于修复 Codex CLI 因异常退出或写入截断导致的会话历史损坏。两者均遵循"先备份、再操作、可回滚"的运维原则，使用门槛低，但能显著降低长期运行 Agent 时的维护成本。资料来源：[baku-mind-cleaner/SKILL.md:1-15]()、[codex-history-recovery/SKILL.md:1-12]()。

## baku-mind-cleaner：清理 Agent 心智状态

### 作用范围

该技能定位于"例行维护"，主要处理 Agent 在本地缓存的会话上下文、思维链摘要以及临时草稿等心智残留。SKILL.md 通常以 YAML frontmatter 描述技能元数据（`name`、`description`），正文给出触发条件、可执行步骤与回滚建议。资料来源：[baku-mind-cleaner/SKILL.md:1-30]()。

### 典型工作流

1. 扫描本地 `.claude/`、`.codex/` 等目录下的 `mind/`、`memory/` 子目录；
2. 依据时间戳与引用关系标记过期条目；
3. 在执行删除前生成带时间戳后缀的可回滚归档；
4. 输出清理摘要，便于 Agent 在下一轮会话中确认结果。

由于该技能强调"安全优先"，建议在首次使用时先生成 dry-run 报告，确认无误后再执行真实清理操作。

## codex-history-recovery：Codex 会话历史修复

### 技能定位

`codex-history-recovery` 专门处理 Codex CLI 因异常退出、磁盘写入失败或 JSONL 文件截断导致的会话历史损坏。SKILL.md 中定义了常见触发条件，例如 `history.jsonl` 解析失败或 CLI 启动时报错等。资料来源：[codex-history-recovery/SKILL.md:5-25]()。

### 目录结构与文件角色

| 文件 | 角色 |
| --- | --- |
| `SKILL.md` | 技能入口，说明触发词与执行步骤 |
| `README.md` | 面向运维人员的补充说明 |
| `agents/openai.yaml` | OpenAI / Codex Agent 加载该技能时的运行配置 |
| `scripts/codex_history_repair.py` | 核心修复逻辑，可独立命令行调用 |

资料来源：[codex-history-recovery/README.md:1-40]()、[codex-history-recovery/agents/openai.yaml:1-20]()。

### 核心脚本：codex_history_repair.py

该脚本实现了对损坏历史的探测、备份与重建，主要步骤包括：

1. **探测（detect）**：定位 `~/.codex/history.jsonl` 或等价路径，逐行校验 JSON 完整性；
2. **备份（backup）**：将原始文件复制为带时间戳的备份，避免修复过程中造成二次损坏；
3. **修复（repair）**：对截断行尝试补全，对损坏行执行丢弃或重试解析；
4. **回写（rewrite）**：以原子方式覆盖原文件，必要时保留损坏行到 `*.corrupt` 旁路文件以供事后排查。

资料来源：[codex-history-recovery/scripts/codex_history_repair.py:1-80]()。

### Agent 配置：openai.yaml

`agents/openai.yaml` 提供 Codex Agent 加载该技能时的提示词与工具白名单，将 `codex_history_repair.py` 暴露为可调用的脚本工具。运维类技能通常在此处显式声明幂等性与回滚策略，确保 Agent 多次执行也不会产生副作用。资料来源：[codex-history-recovery/agents/openai.yaml:1-35]()。

## 与 coding-discipline 的协同

虽然 v0.1.0 把 `coding-discipline` 列为"推荐首选安装"，但运维类技能与它并不冲突，而是互补关系：

- `coding-discipline` 关注"编码过程"中的纪律，强调范围控制、证据驱动、验证导向；
- `baku-mind-cleaner` 与 `codex-history-recovery` 关注"运行过程"中的卫生，强调上下文清洁、历史完整。

合理的安装顺序是：先部署 `coding-discipline` 形成稳定的工作流，再按需启用本页所述的两个运维技能，以获得从开发到长期运行的完整保障。资料来源：[baku-mind-cleaner/SKILL.md:25-40]()、[codex-history-recovery/SKILL.md:30-45]()。

## 总结

`baku-mind-cleaner` 与 `codex-history-recovery` 共同补齐了 Baku Skills 在"长期运行"维度的能力缺口：前者负责清理心智残留，后者负责修复历史损坏。两者都遵循"先备份、再操作、可回滚"的运维原则，配合 v0.1.0 已发布的 `coding-discipline` 与 `boss-job-hunter`，构成从开发到求职、从编码到运维的完整中文 Agent Skills 矩阵。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：Basic-XYZ/baku-skills

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

## 1. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `baku-skills` 与安装入口 `skills` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 复现命令：`npx skills`
- 证据：identity.distribution | https://github.com/Basic-XYZ/baku-skills | repo=baku-skills; install=skills

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/Basic-XYZ/baku-skills | host_targets=claude_code, claude, cursor, openclaw, chatgpt

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Basic-XYZ/baku-skills | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Basic-XYZ/baku-skills | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Basic-XYZ/baku-skills | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Basic-XYZ/baku-skills | no_demo; severity=medium

## 7. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Basic-XYZ/baku-skills | issue_or_pr_quality=unknown

## 8. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Basic-XYZ/baku-skills | release_recency=unknown

<!-- canonical_name: Basic-XYZ/baku-skills; human_manual_source: deepwiki_human_wiki -->