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 字段：

"bin": {
  "skills": "bin/skills.js"
}

资料来源：package.json:8-12

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

3. 目录结构

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

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

4. 工作流与架构示意

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

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-40README.md:42-55。

5. 推荐起点与最佳实践

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

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

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

概述与定位

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

典型的路由节点包含：

资料来源：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

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、baku-illustrations/SKILL.md:1-30

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

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

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

资料来源：baku-design-system/README.md:1-40、baku-design-system/references/components.md:1-60

3. baku-illustrations 的协作模式

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

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、baku-illustrations/README.md:1-40、baku-design-system/brand-dna.md:1-50

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、baku-design-system/agents/openai.yaml:1-30、baku-illustrations/README.md:1-40

概述与定位

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。

目录结构与文件角色

资料来源：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 矩阵。

Pitfall Log / 踩坑日志

项目：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