skills-constitution

Skills Constitution

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

English: README_EN.md

🚀 快速开始

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

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 的规则/指令/记忆层中：

## Skills 宪法（Skills Constitution）v2.32.1

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

执行路径：
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

# 克隆仓库
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

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

Cursor / Windsurf / Cline

# 将宪法写入规则目录
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.json 为作者快照（示例）；使用者在自己的环境运行 scripts/build_skill_tree.py 生成自己的技能树（或用平台自身能力清单）。安装后必须重建——完整命令（含 SKILLS_DIR）/平台差异/自检/FAQ 见 reference/skill-tree-guide.md

---

📦 技能注册表（registry.json）

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

# 方式 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。

---

🎯 解决的痛点

痛点	表现	宪法解决
不调用	装了 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处理（零号条款：模糊任务查一下）

用法

# 双通道分流（推荐入口）：自动判定任务类型
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-retries 3

# 单步校验（如推荐板块）
python scripts/constitution-check --step 5 --input output.txt

Step	校验内容	对应条款	版本
classify	双通道分流：简单/专业/模糊	零号条款	v2.10.0
pre-hook	输入拦截：开场已注入三查？任务必需技能命中？	第零/一条	v2.10.0 / v2.11.0
1	宪法三查已汇报（软+硬+Layer C 任务相关）	第零/一条	v2.9.0 / v2.11.0
2	技能树已读或无匹配声明（软+硬+Layer C）	第一条	v2.9.0 / v2.11.0
3	命中技能已调用（软+硬+Layer C+Layer F 图证据）	第二条	v2.9.0 / v2.11.0 / v2.23.0
4	交付自检（非版本类自动跳过）	全文件核查	v2.6.0
5	推荐板块含 GitHub 链接+star 数（软+硬两层）	第五条	v2.9.0

⚠️ 设计边界：脚本是"增强层"，宪法正文永远是行为规则兜底。禁止把"必须先跑脚本"写进正文——在跑不了脚本的环境会被 Agent 判为"不可满足"而整体跳过宪法。

三查证据链（v2.22.0）

宿主钩子（constitution-gate.py）认两种"三查已完成"证据，满足其一即放行写操作、收尾不重复校验：① 本任务内 constitution-check --step 1 真实校验通过；② 平台已注入记忆+技能树（注入上下文 ready）且本任务内实际调用过命中技能（Skill 调用自动记录）。同任务追加式消息不重置证据；门禁自身状态/豁免/违规文件禁止被 Agent 篡改（篡改即拦截）。

---

📝 改版说明（CHANGELOG 摘要）

v2.29.1（2026-09-20）— skill_doctor 白名单修复：框架标记目录不再被误报为损坏技能

• 问题：_<name>-references 是 E2 机制标记"该框架已装"的目录，本就不是技能、没有 SKILL.md；而 skill_doctor.py 的 scan() 只按"有无 SKILL.md"判目录性质 → 把它判成 missing_skill_md/broken，本机常年带 1 条假损坏，--quarantine 更会把它当损坏技能移走、直接破坏 E2 标记
• 改法：scan() 的跳过 guard 增加白名单正则 ^_.*-references$（与"点开头目录"同等对待）。报告与 --quarantine 共用同一份 findings，故单点修复即同时覆盖「报告误报」与「误隔离」两条路径
• 验证：本机 skill_doctor.py 损坏 1 → 0（该目录仍在原位，未被移走）；run_tests.py 新增 2 条断言（第 11b 节）——一条钉白名单生效，一条钉真损坏仍照常报（防白名单过宽）

v2.29.0（2026-09-19）— 技能路由与检索结论可靠性加固：让 Agent 用对技能、下对结论

• 起因：一次真实任务连犯三错——①「github改版技能」被望文生义错配成 constitution-release（真身是 github-gitee-sync）；② Glob 查 github-gitee-sync 零命中就断言"未安装"（实际在库，换 description 内容级检索一次命中）；③ git 仓库损坏徒手硬修，库内现成的 git-repo-recovery 从未被想起。复盘发现：三查防线只验证"查没查"，不验证"查得对不对、结论下得对不对"
• 新增死规则（SKILL.md 第一条补充 C，四条）： ① 模糊指代三步映射，禁止望文生义——全量索引内容级检索（name+description 都搜）→ 命中多/零个候选列出来请用户确认 → 执行前回显「你说的是「X」→ 我用 Y（依据）」，映射不定宁可问，不许猜； ② "不存在/未安装"结论需双通道证据——任何检索零命中后必须换方式复核（目录名 → description 内容、精确 → 模糊、本级 → 上级），两路皆空才许下结论； ③ 类故障先查专项技能再动手——故障与某技能 description 同域时（git 损坏 → git-repo-recovery）必须先加载该技能，禁止徒手硬修
• 零代码改动，纯规则文本；回归 run_tests.py 本机 139/140（唯一 FAIL 为检索门禁，经干净克隆对照实测证为环境差异：门禁按作者池 1084 技能校准，本机池 625，非本版引入；干净克隆上门禁通过 holdout hit@4 100%）

v2.28.1（2026-09-15）— 安装脚本真机修复：装不上 + 可能装丢数据

• ① install.ps1 无 UTF-8 BOM → Windows PowerShell 5.1 按系统 ANSI 码页（简中 GBK）读含中文/emoji 的脚本，多字节序列被误读成引号与花括号，报「表达式或语句中包含意外的标记"}"」，一行都跑不完。改为带 BOM 存盘；同仓库另两个 .ps1（hooks/session-start.ps1、scripts/update.ps1）同类问题一并补上
• ② 覆盖安装用删除：旧实现 Remove-Item -Recurse -Force（install.sh 里 rm -rf）先删目标目录再复制。删除一旦被宿主环境的安全护栏拦下（回收站保护 / 句柄占用 / 沙箱拦截），就变成「旧版已被移走、新版又没落盘」，用户技能目录被清空——真机实测复现，靠事先手动备份才没出事
• 改法：先原地改名备份 skills-constitution.bak-<时间戳> 再复制新版。改名是原子操作、可回滚，失败只报错退出；末尾打印备份路径，确认新版可用后由用户自行清理
• 固化为脚本硬约束：安装脚本绝不执行删除用户数据的动作（要腾位置就改名）；只搬运技能目录，绝不触碰任何记忆文件；零外部依赖

v2.28.0（2026-09-10）— 技能检索质量重构：双路证据召回 + RRF 融合 + 配对评测纪律

• 起因：借鉴 zg「多路召回 + RRF + 配对评测」方法论回查检索层，拿配对 A/B 一量就露馅 —— 旧打分器在 20 条任务上 hit@4 只有 45%
• 根因：overlap_score 既无长度归一化也无停用词 → 描述"又长又万能"的技能霸榜（撞掉的正是 browser-automation/code-review/ponytail 这类描述简短或纯英文的技能）；分词还会吐出"个转/份汇/价和"这类跨词边界假词
• 改造：① 单一打分 → 双路证据召回 + RRF 融合（名称路 = 词面命中技能名；描述路 = BM25 词频×IDF×长度归一化；按排名融合、零调参）；② 分词修噪（纯虚词表 / 弱义字表分离）；③ 新增跨语言技术词桥（技能库双语，任务中文而大量技能描述是英文，词面交集恒为空 —— 用确定性词桥作"语义通道"的零依赖替代）
• 评测纪律（最关键的一环）：新增 scripts/tests/retrieval_eval.py 配对 A/B + 12 条开发期从未调参的留出集；实测把 dev 集调到 hit@4 100% 后，留出集只剩 66.7% —— 过拟合被当场抓出，据此再补词桥回到 100%。评测已入回归门禁（run_tests 第 14 节），测试 134 → 140 条
• 实测（技能池 1084）：dev hit@4 45% → 100%、hit@1 25% → 50%；holdout hit@4 66.7% → 100%、hit@1 41.7% → 66.7%；同时平均候选数保持 4.00、Top1 注入字符反而减少约 16%（命中率涨、token 不涨）
• 明确未采纳：向量/embedding 语义索引（违背零依赖 + 省 token 基调）；把"分类路由"当一路召回（实测降分 —— 路由是策略不是证据）

v2.26.0（2026-09-02）— 一键更新脚本：下载最新版 → 校验 → 自动安装

• 新增 scripts/update.sh / scripts/update.ps1：把「更新前先去 GitHub 下载最新版、更新完成后自动在本地安装最新版」固化为死规矩脚本