# skills-constitution

Adopt this skill: https://proskills.md/skills/other/jiabaobei-skills-constitution

Page: https://proskills.md/skills/other/jiabaobei-skills-constitution
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 15449
upstream: https://github.com/jiabaobei/skills-constitution/blob/HEAD/SKILL.md

```text
---
name: skills-constitution
description: "当 Agent 接到专业任务（编码/爬虫/文件操作/API调用/数据分析/文档/部署/推送等）时，强制先查记忆层和技能索引，有匹配必用、无匹配必搜、答复时自动推荐（排除已装）。用于防止 Agent 跳过技能直接硬扛通用能力。跨平台通用（WorkBuddy/Claude/ChatGPT/Cursor/Gemini 等 20+ 框架）。完整版本史见 CHANGELOG.md。"
version: 2.31.1
license: MIT
author: jiabaobei
github: https://github.com/jiabaobei/skills-constitution
display_name: "Skills 宪法"
display_name_en: "Skills Constitution"
description_zh: "Skills 宪法 —— 凌驾于全部技能之上的元规则：先查记忆、再查技能索引（按功能分类）、有匹配必用、无匹配必搜、答复时推荐（排除已装）。防止 Agent 跳过技能硬扛。版本史见 CHANGELOG.md。"
description_en: "Skills Constitution — universal meta-rule: pre-check memory, lookup skill tree by category, mandatory use when matched, search when unmatched, recommend non-installed skills on answer. Cross-platform for 20+ agent frameworks. Changelog: CHANGELOG.md."
visibility: "public"
agent_created: true
---

# Skills 宪法（Skills Constitution）

> **一句话定位**：凌驾于全部技能/工具/插件之上的**元规则**。所有能力调用必须先过这一关。
>
> **v2.31.0（当前）** — **抗崩溃层**（2026-09-21 事故：钩子超时 → 平台 `UserPromptSubmit operation blocked by hook: Hook timed out after 15000ms / 20000ms` → 用户整条消息被拦死，感知为"系统崩溃"）。**实测根因**：热路径每轮跑 **2 个 python 钩子**，而本机 python 解释器启动本身 0.7~2.5s（Defender 首扫），固定成本 3~7s 直逼 15s/20s 上限；再叠加 ① Stop 分支三处早返回把"通过即清除"堵死 → 旧违规永不清除、每轮重播；② 时间窗与警告耦合 → 跨时段把几天前的旧账当新警告弹。**新增五条防灾死规则**：R1 拉闸优先（开关文件/环境变量，任何事件在任何逻辑之前放行）、R2 异常放行（门禁自身任何异常 → 退出码 0）、R3 自修复豁免（门禁不得拦截对门禁自身的修复，破"自锁死"）、R4 写失败可见 + 自动拉闸（连续 3 次写失败自动断电）、R5 耗时预算（超预算记 slow / 自动拉闸）。**新增** `scripts/emergency-off.sh` / `emergency-on.sh`（纯 bash 一键断电/合闸，不依赖 python）、`scripts/constitution-doctor.py`（7 项体检：拉闸状态/状态文件可写/注入缓存/违规卡死/钩子注册与超时值/**耗时实测**/健康日志）、`scripts/tests/gate_failsafe.py`（**26 项抗崩溃验收，发布前置门禁**）。违规语义改为**合规即清零**（写 `cleared_ts`/`cleared_task`，可审计不销毁历史）。**v2.30.0 任务边界设计（同对话+2h、三查一次、有匹配必用每轮、Stop 每任务一次）一行未动**，验收 13→17 项全过。
> **v2.30.0** — 任务边界重定义（用户钦定 2026-09-20："任务开始三查一次，中途不再三查"）：① 门禁 UserPromptSubmit 不再把"每条非追加式消息"当新任务 —— 新边界 = 同一对话（session_id 可用则校验，缺失退化为纯时间窗）+ 距最近活动 2 小时内；窗口内不重置状态、不重复要求三查。② 同对话另起新类型任务（新消息必需分类与当前任务完全不相交）→ 提示 Agent 询问用户是否重新三查，答复前按当前通行证放行。③ 「有匹配必用」不受"三查一次"限制：同任务每条消息凡有必需分类，提醒一行（约 40 字，省 token），相关技能必须调用。④ Stop 收尾校验每任务只做一次（针对首轮回复，保住 v2.27.5 防"零追责"目的），不再逐轮要求复述三查。新增验收脚本 `scripts/tests/gate_task_boundary.py`（13 项全过，可重复运行）；既有回归 142/142 通过。
> **v2.29.1** — `skill_doctor` 白名单修复：`_<name>-references` 是 E2 机制用来标记"该框架已装"的目录（`recommend_skills.py` 靠它判定），它不是技能、本就没有 SKILL.md；旧版 `scan()` 只按"有无 SKILL.md"判目录性质，把它判成 `missing_skill_md/broken` → 本机常年报 1 条假损坏，`--quarantine` 更会把它当损坏技能**移走**、直接破坏 E2 标记。现于 `scan()` 的跳过 guard 增加白名单正则 `^_.*-references$`（与"点开头目录"同等对待）；报告与隔离共用同一份 findings，一处跳过即同时修好两条路径。实测本机损坏 1 → 0，新增回归断言 2 条。
> **v2.29.0** — 技能路由与检索结论可靠性加固（2026-09-19 事故复盘）：三查防线此前只验证"查没查"，不验证"查得对不对、结论下得对不对"，一日连犯三错。新增死规则「第一条补充 C」：① 用户口述的模糊技能指代**必须映射确认**（全量内容级检索 → 列候选请用户确认 → 执行前回显映射），禁止望文生义取"最像的那一个"——实锤：「github改版技能」被错配成 constitution-release，真身是 github-gitee-sync；② "**不存在/未安装**"结论需**双通道检索证据**——单次 Glob/Grep 零命中 ≠ 不存在（实锤：github-gitee-sync 在库内被误报未安装）；③ **类故障必须先查专项技能再动手**——git 仓库损坏时库内现成的 git-repo-recovery 未被想起，徒手硬修。
> **v2.28.0（当前检索架构）** — 技能检索质量重构（借鉴 zg「多路召回 + RRF + 配对评测」方法论）：① 单一加权打分改**双路证据召回 + RRF 融合**（名称路 = 词面命中技能名；描述路 = BM25 词频×IDF×长度归一化），按排名融合、零调参 —— 实测 dev 集 hit@4 45%→100%、未调参的留出集 66.7%→100%；② 分词修噪（纯虚词表 / 弱义字表分离，二元组含纯虚词即丢），修"个转/价和/份汇"这类**跨词边界假词**与冗长描述误撞导致的"万能描述技能霸榜"（overlap_score 既无长度归一化也无停用词，这是根因）；③ 新增**跨语言技术词桥**——技能库是双语的，任务说中文而相当一批技能的 description 是英文（browser-automation / code-review / ponytail / openai-whisper），纯词面检索在这道语言鸿沟前交集恒为空，用确定性词桥作"语义通道"的零依赖替代（只映射英文技术词，不动 Layer C 任务分类）；④ 新增**评测纪律**：`scripts/tests/retrieval_eval.py` 配对 A/B（legacy vs hybrid）+ 12 条**开发期从未调参的留出集** —— 实测 dev 集被调到 100% 时留出集只有 66.7%，过拟合被当场抓出；评测已入回归门禁（run_tests 第 14 节，134→140 条）。
> **v2.27.6** — 修"技能树查了等于没查"：① 分类路由兜底原取字母序前 5 个分类（general/browser/search/file/data，与任务无关），改复用确定性路由，实测"推送到 github 和 gitee"能正确落到 code/meta；② 注入名录两处硬截断 `skills[:8]`/`cat_skills[:10]` 改为按任务相关度排序取前 N（复用现有 loose_retrieve_skills），行尾标注"未列全"——排在 code 类第 38 位的 github-gitee-publish 从此能露面；③ 新增死规则「第一条补充 A」：注入名录是预览不是清单，行尾标"未列全"时判"无匹配"前必须 grep 全量索引。
> **v2.27.5** — Stop 追责拧紧：收尾免检区分强/弱证据（step1 真实 PASS 或真调过技能才免检；仅"注入即签"弱通行证且本任务有必需分类时，收尾回复仍须过三查文本校验），堵"无视注入提示、全程零举证零追责"漏洞；必需分类缓存进门禁状态零开销复用；GBK 输出崩溃根治（stdout/stderr 强制 UTF-8，收编自安装副本实战补丁）。
> **v2.27.4** — 钩子注册补全：UserPromptSubmit 补注册注入保活钩子（pre-hook --hook-mode），修复"注入只在 SessionStart 做一次、长会话过期后 Agent 拿不到记忆+技能树 → 该调技能不调技能"的防线缺口；注册脚本全面直调 python（本机实测 bash 包装层单次 2.5~12.9s 是宿主 20s 超时元凶，pre-hook 本身仅 0.19s，直调后热路径门禁+注入合计 ≈3.5s）；MARKERS 收编 pre-hook.py，幂等替换/卸载可识别手工添加的注入钩子。回归 +3 条（13.6 注册完整性）。
> **v2.27.3** — 门禁状态文件写入健壮性修复（用户钦定"宪法不起作用"真因）：① 并发 tmp 重名 —— 三个钩子进程共用固定名 `state.json.tmp`，互相截断后被 `os.replace` 换回主文件；改为 tmp 名带 pid。② Windows `os.replace` 遇 PermissionError 时 v2.27.0 兜底 open(w) 直写会截断主文件 → 改为只做短重试，仍失败放弃写入保留旧文件。③ 兜底语义纠偏 —— 损坏即静默放行导致门禁**永久失效**；改为降级放行（不阻断、打印提示、不签通行证），下次任务开始自动重置恢复。附陈旧 tmp 清理 + 5 条回归用例（并发压测 0 损坏）。
> **v2.27.2** — 测试修正（零功能变更）：过时断言对齐 v2.27.0 单进程架构——13.0c 改断言单进程委托在位+嵌套自愈已删除、13.3 阈值 10s→18s（慢机器+Defender 首扫实测 6~18s 波动，热路径均值 ~7s）、13.1/13.3 超时捕获记失败不崩套件。
> **v2.27.1** — 技能图谱补全与降噪：① 自愈路径（refresh_injection）接入图谱候选（v2.27.0 曾漏传 []，导致 hook-mode 自愈产出的注入块缺「🕸️ 技能图谱」段）；② cluster 候选降噪——超采样 3 倍后，同簇成员必须与任务有词面交集（名称/描述，overlap_score>0）才收录，结构边（chains_to/co_anchor）与 alternative 保持原样；实测"写爬虫"任务候选 8→1（adobe-* 无关同簇成员全灭），注入块 4199→3458 字符，无关任务宁缺毋滥（0 候选）。
> **v2.27.0** — 钩子单进程化 + 门禁「任务开始拦一次、中途不再拦」真实生效：① 门禁状态文件改原子写入（修复 UserPromptSubmit/PreToolUse/Stop 三钩子并发写截断 → 通行证丢失 → 中途误拦，用户钦定 bug）；② 注入上下文过期(>24h)时门禁进程内自动刷新（修复任务开始拿不到通行证）；③ user-prompt-submit.sh 热路径进程启动 9 次→1 次、session-start.sh 6 次→1 次（解释器缓存 + builtin 读取 + exec 单次 python --hook-mode），慢机器实测 33~39s → 预期 <8s，不再触发宿主 20s 超时；④ bash 兜底注入块禁止引导 Agent 整读技能树文件（可达数十万字符），改为 pre-hook 按任务过滤约 3 千字符（省 token）。
> **v2.26.0** — 一键更新脚本 `scripts/update.sh` / `scripts/update.ps1`：把「更新前先去 GitHub 下载最新版、更新完成后自动在本地安装最新版」固化为脚本——下载最新 main 包（codeload + api 双保险）→ 完整性校验（半残包保持旧版不毁旧装）→ 透传参数跑新版安装器自动安装。
> **v2.25.1** — 钩子挂起修复：两条钩子的解释器检测加 3s 存活探针（修复 Windows 上 Microsoft Store 占位别名启动即挂起、被宿主 20s 强杀的卡死），stdin 读取限时 2s、自愈限时 10s，超时一律降级 fail-open，钩子永不卡任务。
> **v2.25.0** — 第五条「答复推荐」极度省 token 改造：推荐来源从"每次全盘搜 GitHub"改为**读本地排行榜快照**（`data/skill_rankings.json` + `scripts/recommend_skills.py` —— 零网络、约 20KB、纯确定性规则匹配 + 自动排除已装）；新增 `scripts/update_skill_rankings.py` 低频抓取权威排行榜（quemsah/awesome-claude-plugins，索引 3.6 万+ 仓库）重建快照，过期（>30 天）只提示不自动拉取；step5 新增推荐来源标注软校验（标注"本地排行榜快照"=省 token 最佳实践）。
> **v2.24.0** — 隐形技能治理 + 门禁「一次三查全程放行」+ 轻量索引。实测修复五项：
> ① `parse_frontmatter` 支持 YAML 块标量（`>`/`|` 及折叠变体）——旧版把 ponytail 全套等 137 个技能的 description 解析成单个 `>` 字符，检索永远命中不到（典型：用户装了 GitHub 116k★ 的 ponytail 却从未被调用）；
> ② 索引描述上限 200→2000——触发词（如 ponytail 的 lazy mode，位于第 400+ 字符）不再被截断丢弃；
> ③ 门禁任务级通行证——任务开始时三查通过（平台注入或 step1 PASS）即全程放行，拦截前移为任务开始时的一次性提醒（用户明确要求：任务开始已三查，中途不得再拦）；
> ④ 新增 `scripts/skill_doctor.py`：隐形/损坏技能自动诊断（8 类检查）+ `--fix` 自动修复 + `--quarantine` 隔离损坏 + `--emit-min-index` 轻量索引（约完整索引 20% 体积，截断部分保留长尾触发词，冷门技能省 token 仍可命中）；
> ⑤ 图谱锚点抽取固定用前 200 字符 + 停用词三批扩容 + DF 上限 0.05→0.035——描述放宽后锚点暴增曾产生 752 节点巨簇，现恢复 ≤80 纪律（回归测试 106/106）。
> **v2.23.0** — 技能图谱（借鉴 GitNexus 预计算关系智能）：技能树之上叠加确定性关系图（`skill_graph.json`，随技能树重建自动产出）。三种边全部零依赖确定性抽取——`chains_to`（registry 的输出→输入 schema 交集）/ `co_anchor`（共享实体锚点，含停用词与文档频率过滤）/ `alternative`（同分类高重叠替代方案）；确定性标签传播聚成功能簇。三处落地：① 注入块从“整分类清单”收窄到“锚点技能的任务线图谱”（带“为什么相关”溯源，更省 token）；② 门禁 step3 新增 Layer F 图证据校验——引用的技能必须与任务锚点图谱连通，零连通带簇证据判 FAIL；③ 替代边不做放行凭证、不参与聚簇（纪律同 GitNexus 只对结构边做社区检测）。图缺失时全部链路行为与旧版一致（只加不删）。
>
> 完整版本史见 `CHANGELOG.md`。

---

## 🚨 门禁防灾条款（v2.31.0 起 · 最高优先级）

> **事故背景**：2026-09-21 钩子超时 → 平台直接 block 用户整条消息
> （`UserPromptSubmit operation blocked by hook: Hook timed out after 15000ms / 20000ms`）。
> 用户发什么都进不来，只能靠改 `hooks.json` 文件名逃生。同类事故此前已多次发生
> （v2.25.1 挂起被杀 / v2.27.0 / v2.27.2 慢机器 6~18s 波动 / v2.27.4 bash 包装层 2.5~12.9s）。
> 结论：**门禁宁可放行，绝不阻塞用户；且必须随时能被一键断电。**

**五条死规则（任何改动不得违反）：**

| 规则 | 内容 | 落地位置 |
|---|---|---|
| **R1 拉闸优先** | 拉闸开关存在（文件 `.constitution-off` 或环境变量 `CONSTITUTION_OFF`）→ **任何事件在任何逻辑之前直接放行** | `constitution-gate.py` → `main()` 首行 |
| **R2 异常放行** | 门禁自身任何异常（异常 payload、状态不可读、JSON 损坏）→ **退出码 0**，永不因自身故障拦人 | `main()` 外层捕获 + `state_broken` 分支 |
| **R3 自修复豁免** | 目标落在门禁项目内（`scripts/`、`hooks/`、`tests/` 及 SKILL/README/CHANGELOG）→ 
```

## File: README.md
upstream: https://github.com/jiabaobei/skills-constitution/blob/HEAD/README.md

`````text
# Skills Constitution

> **Skills 宪法** —— 凌驾于全部技能/工具之上的元规则，强制 Agent 先查后用、有匹配必用、无匹配必搜。跨平台通用（WorkBuddy / Claude / ChatGPT / Cursor / Gemini / ...）

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-2.33.0-blue.svg)](SKILL.md)
[![Skills Indexed](https://img.shields.io/badge/skills__indexed-author__snapshot-green.svg)](SKILL_TREE.md)

**English**: [README_EN.md](README_EN.md)

## 🚀 快速开始

### 一键安装（推荐，v2.21.0 全平台分流）

```bash
git clone https://github.com/jiabaobei/skills-constitution.git
bash skills-constitution/install.sh                 # 自动探测平台，装完自动重建技能树
```

脚本按平台机制自动分流（v2.21.0）：

| 平台形态 | 命令 | 效果 |
|---------|------|------|
| 技能目录型（WorkBuddy / Claude Code / ZCode） | `bash install.sh` | 复制 + **自动重建技能树（含插件技能）** + 自检 |
| 同上 + 强制拦截 | `bash install.sh --register-hooks` | 装完自动注册四个宿主钩子（带备份/回滚/幂等） |
| 规则文件型（Cursor / Windsurf / Cline） | `bash install.sh --platform cursor --target-dir <项目>` | 宪法写入规则文件（建议级） |
| 纯注入型（ChatGPT / Gemini / 扣子等） | `bash install.sh --platform prompt` | 自动提取注入模板供粘贴 |
| Windows | `powershell -File install.ps1` | 同技能目录型流程（需真机首验） |

**双机制平台覆盖（v2.21.0）**：ZCode / Claude Code / DeepSeek Harness(dsh) 等平台的能力同时来自「独立技能 + 插件」两条平行通道。技能树重建会自动把**插件缓存里的插件技能**编入索引（ZCode / Claude Code 已知路径自动发现，停用插件自动排除；其他平台用 `PLUGIN_CACHE_DIRS` 环境变量或仓库根 `plugin_roots.json` 接入），插件技能在树中标注完整调用名（如 `document-skills:docx`），宪法条款同步覆盖：**命中插件技能与命中独立技能同权重，必须按完整调用名调用**。

钩子注册也可以单独跑：`python skills-constitution/scripts/register_hooks.py`（`--dry-run` 预览 / `--uninstall` 移除）。

### 一键注入（任何平台）

把下面这段复制到你的 Agent 的规则/指令/记忆层中：

````markdown
## Skills 宪法（Skills Constitution）v2.33.0

本规则优先级高于全部技能/工具/插件。任何能力调用必须先过这一关。

执行路径：
1. 先查记忆：查阅平台记忆层（MEMORY.md/CLAUDE.md 等）确认相关规则
2. 先查技能：查看技能索引，按任务类型定位功能分支，**输出必须列出命中的技能名清单**
   （技能索引含独立技能与插件技能（v2.21.0）：命中插件技能按其完整调用名 `插件名:技能名` 调用）
3. 匹配必用：有匹配则无条件优先使用该能力
4. 无匹配必搜：先搜索可获取的能力，再考虑通用能力
5. 能力边界：说"做不到"前必须先搜索确认无能力可用
6. 答复推荐（v2.25.0 快照优先，极度省 token）：本地技能未能完美解决任务时，**优先读本地排行榜快照** `python scripts/recommend_skills.py --task "<任务>"`（零网络、自动排除已装、出 3 条含链接+star+获取方式）；快照无匹配时才去 GitHub 搜索；快照过期（>30 天）跑 `python scripts/update_skill_rankings.py` 刷新

双通道（v2.10.0）：简单任务（翻译/润色/解释）→ 零号条款豁免直接通用能力；
专业任务（编码/爬虫/API）→ pre-hook 强制注入记忆+技能树，未汇报【宪法三查】即被拦截。

任务相关硬校验（v2.11.0）：任务含"代码/git/部署"等关键词时，输出必须引用 skill_tree.json
对应分类的实际技能名（如 `git-workflow-and-versioning`），只写"已查宪法/已读技能树"而无技能名 → FAIL。

违规判定：跳过查记忆/技能清单直接干 / 有匹配但不用 / 未搜索就拒绝 / 查技能树未列出命中技能名（空头汇报）/ 本地技能不足却不去推荐（v2.25.0 快照优先） / **命中插件技能却以"它是插件"为由绕过（v2.21.0）**
````

### WorkBuddy / CodeBuddy

```bash
# 克隆仓库
git clone https://github.com/jiabaobei/skills-constitution.git

# 安装技能
cp -r skills-constitution ~/.workbuddy/skills/skills-constitution/

# 重建技能树（必做：生成你自己的索引，替换作者快照；完整命令/平台差异见 reference/skill-tree-guide.md）
SKILLS_DIR="$HOME/.workbuddy/skills" python scripts/build_skill_tree.py
```

### Claude Code

```bash
# 用户级
cp -r skills-constitution ~/.claude/skills/skills-constitution/
```

### Cursor / Windsurf / Cline

```bash
# 将宪法写入规则目录
cp SKILL.md .cursor/rules/skills-constitution.md
# 或
cp SKILL.md .windsurfrules
# 或
cp SKILL.md .clinerules
```

### ChatGPT / Gemini / 其他

将【快速注入模板】中的内容复制到：
- ChatGPT → Custom Instructions 或 GPT 的 System Prompt
- Gemini → Gem 的 Instructions
- 其他 → 系统提示词 / 记忆层

---

## 📋 宪法条款（v2.18.0）

### 第零条：任务分类（零号条款）
前置过滤：简单问答（翻译/润色/解释）→ 跳过查技能；专业任务（编码/爬虫/API）→ 必须查；模糊任务 → 查一下（宁可不放过）。v2.10.0 由 `pre-hook.py --classify` 确定性分类器执行，不依赖 Agent 自觉。

### 第一条：先查（Pre-Check）
每次执行专业任务前，查看能力注册表，判断有没有匹配的能力。v2.10.0 由 `pre-hook.py` 任务开始前强制注入记忆+技能树；v2.11.0 强制输出**命中技能名清单**（名称+依据），且任务含代码/git/部署等关键词时硬校验必须命中对应分类技能（Layer C）。

### 第二条：匹配必用（Mandatory Use）
有匹配则无条件优先加载该能力，禁止绕开直接用通用能力。v2.11.0：匹配判定必须引用实际技能名（step3 Layer C 校验）。

### 第三条：无匹配必搜（Search First）
无匹配时先通过技能发现机制搜索，再考虑通用能力。

### 第四条：能力边界（Honest Boundary）
说"做不到"前必须通过技能发现机制确认无能力可用。

### 第五条：答复推荐（Auto-Discovery）
本地技能未能完美解决任务时，**优先读本地排行榜快照**（`data/skill_rankings.json`，`python scripts/recommend_skills.py --task "<任务>"` —— 零网络、自动排除已装、出 3 条含 GitHub 链接+star+获取方式）；快照与任务零相关时才去 GitHub 搜索并标注来源；本地不足却不去推荐 → 违规（v2.11.0 修正定位；v2.25.0 快照优先省 token）。快照刷新（低频）：`python scripts/update_skill_rankings.py`。

---

## 🌲 技能树（Skill Tree）

按功能类型分类全部技能，Agent 执行时**按分支定位**，减少 80% 扫描量：

| 分类 | 说明 | 示例技能 |
|------|------|---------|
| 📜 元规则类 | 宪法、规则定义、安全审计 | `skills-constitution`, `skills-security-check` |
| 🧠 记忆管理类 | 个人记忆、项目知识、会话持久化 | `aiweko-memory-reports`, `agent-memory` |
| 🌐 网络/搜索类 | 网页自动化、数据抓取、API 调用 | `browser-skill`, `agent-browser`, `anysearch` |
| 💻 开发/编码类 | 代码生成、审查、测试、构建 | `code-review`, `pr-review`, `git-ops` |
| 📄 文档处理类 | PDF、Word、Excel、PowerPoint | `pdf`, `docx`, `xlsx`, `pptx` |
| 🖼️ 内容生成类 | 图像、视频、UI 设计 | `agnes-video-generator`, `image-to-ui` |
| 💰 业务专用类 | 金融、法律、电商、营销 | `配网规划评审器`, `wind-finance` |
| 🔧 通用工具类 | 文件操作、进程管理、环境配置 | `file-ops`, `process-manager` |

**完整索引**：仓库内 [SKILL_TREE.md](SKILL_TREE.md) / [skill_tree.json](skill_tree.json) 为**作者快照（示例）**；使用者在自己的环境运行 `scripts/build_skill_tree.py` 生成**自己的**技能树（或用平台自身能力清单）。**安装后必须重建**——完整命令（含 SKILLS_DIR）/平台差异/自检/FAQ 见 `reference/skill-tree-guide.md`

---

## 📦 技能注册表（registry.json）

精选开源技能/工具索引（作者整理），解决"装什么、从哪装"的问题。**按需安装，不打包全量**：

```bash
# 方式 1：直接 clone 来源仓库，复制技能目录到你的平台技能目录
git clone https://github.com/anthropics/skills.git
cp -r skills/skills/docx ~/.claude/skills/

# 方式 2：用包管理器（gh skill / sk 等）
gh skill install anthropics/skills docx
```

| 字段 | 说明 |
|------|------|
| `name` | 技能名 |
| `repo` | 来源仓库（`owner/repo`） |
| `path` | 技能在仓库内的目录（可选，以仓库 README 为准） |
| `description` | 一句话功能 |
| `category` | 分类（framework/documents/development/testing/security/discovery/ai-tools） |

条目均来自真实开源仓库，见 [registry.json](registry.json)。

---

## 🎯 解决的痛点

| 痛点 | 表现 | 宪法解决 |
|------|------|---------|
| **不调用** | 装了 100 个技能只用了 3 个 | 强制先查能力清单 |
| **调用幻觉** | 凭印象选技能，不看描述 | 必须匹配 description |
| **调用混乱** | 多个技能都能做，随机挑 | 按相关度排序选最优 |
| **能力误判** | 感觉"做不到"就直接拒绝 | 先搜索确认无能力 |
| **无复盘** | 做完就走，不看有没有更好技能 | 答复时自动推荐 |
| **扫描全量** | 每次任务扫全部技能 | 按技能树分支定位 |

---

## 📊 优先级规则

```
优先级从高到低：

1. 🔴 系统安全规则（不可违反）
2. 📜 Skills 宪法（本规则）—— 凌驾于全部技能/工具/插件之上
3. 🔧 具体能力的执行指令
4. 🤖 Agent 通用能力
```

---

## 🔍 执行流程

```
任务来了
    │
    ▼
┌─────────────────────┐
│ ① 查记忆层          │── 读取平台规则/历史上下文
│ (Pre-Check Memory)  │
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│ ② 查技能索引        │── 按任务类型定位分支
│ (Skill Tree Lookup) │
└─────────────────────┘
    │
    ├── 命中分类 → ③ 加载该分支技能描述
    │
    └── 未命中 → ④ 全量扫描 description 匹配
```

---

## 📝 违规判定

以下行为属于**严重违规**，用户有权要求重做并说明理由：

| 违规行为 | 判定标准 |
|----------|----------|
| 跳过查记忆直接干 | 任务完成但未查阅平台记忆层 |
| 跳过查技能清单直接干 | 任务完成但未加载任何相关能力 |
| 有匹配但不用 | 能力注册表中有匹配能力但未加载 |
| 未搜索就拒绝 | 说"做不到"但未通过技能发现机制确认 |
| 无复盘 | 答复时未搜索全网能力库（当任务与能力库明显相关时） |

---

## 🔒 门禁自检（v2.6.0 新增；v2.9.0 两层校验；v2.10.0 输入拦截+双通道；v2.11.0 任务相关硬校验；v2.22.0 三查证据链）

把「靠 Agent 自觉」变成「可校验、可拦截」。5 个 step 独立校验，状态文件链式依赖，默认软校验 + `--strict` 可选阻断。

> ⚠️ **仅适用专业任务**：简单问答（翻译/润色/解释概念）按零号条款跳过，用 `--simple` 声明，不跑门禁。

### 双通道分流（v2.10.0）+ 任务相关硬校验（v2.11.0）

```
任务进入
  ├─ pre-hook.py --classify（零号条款确定性分类器）
  │    ├─ 简单关键词（翻译/润色/解释/概念）→ 【通道A】跳过门禁，直接通用能力
  │    └─ 专业关键词（编码/爬虫/API/文件/部署）→ 【通道B】强制注入校验
  │         ├─ v2.11.0: --task 提取任务必需分类（代码/git/部署→code 分类）
  │         ├─ 未输出【宪法三查】→ BLOCKED（任务开始前被拦截，exit 1）
  │         ├─ 未引用任务对应分类技能名（如 git-workflow-and-versioning）→ BLOCKED
  │         └─ 已输出三查 + 已命中任务分类技能 → 继续 step1-5 全量校验
  └─ 模糊任务 → 宁可不放过，按通道B处理（零号条款：模糊任务查一下）
```

### 用法

```bash
# 双通道分流（推荐入口）：自动判定任务类型
python scripts/constitution-check --classify --input task.txt

# 双通道 + 任务相关硬校验（v2.11.0：专业任务必须引用对应分类技能名）
python scripts/constitution-check --classify --task "推送github代码" --input output.txt --strict

# 输入拦截：先校验开场是否已注入三查，未注入即阻断
python scripts/constitution-check --pre-hook --input output.txt --strict

# 生成注入块（任务开始前喂给 Agent；v2.11.0 含任务必需技能清单）
python scripts/pre-hook.py --task "推送github代码"

# 全量软校验（FAIL 只警告）
python scripts/constitution-check --input output.txt

# 严格模式（FAIL 即阻断，exit 1）
python scripts/constitution-check --input output.txt --strict

# 简单任务豁免（零号条款）
python scripts/constitution-check --simple

# Post-hook 重试循环（v2.9.0：失败自动注入提示重试，最多3次）
python scripts/retry-wrapper.py --input output.txt --max-retr
`````
