Skills Constitution

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

🚀 快速开始

一键注入（任何平台）

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

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

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

执行路径：
1. 先查记忆：查阅平台记忆层（MEMORY.md/CLAUDE.md 等）确认相关规则
2. 先查技能：查看技能索引，按任务类型定位功能分支，**输出必须列出命中的技能名清单**
3. 匹配必用：有匹配则无条件优先使用该能力
4. 无匹配必搜：先搜索可获取的能力，再考虑通用能力
5. 能力边界：说"做不到"前必须先搜索确认无能力可用
6. 答复推荐：本地技能未能完美解决任务时，必须去 GitHub 搜索高 Star 能力推荐给用户（含链接+star+获取方式），由用户决定是否安装

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

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

违规判定：跳过查记忆/技能清单直接干 / 有匹配但不用 / 未搜索就拒绝 / 查技能树未列出命中技能名（空头汇报）/ 本地技能不足却不去 GitHub 搜索推荐

WorkBuddy / CodeBuddy

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

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

# 生成技能树索引
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.13.3）

第零条：任务分类（零号条款）

前置过滤：简单问答（翻译/润色/解释）→ 跳过查技能；专业任务（编码/爬虫/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）

本地技能未能完美解决任务时，必须去 GitHub / 全网搜索高 Star 相关能力推荐给用户（含链接+star+获取方式），由用户自行决定是否安装。本地不足却不去搜索 → 违规（v2.11.0 修正定位）。

🌲 技能树（Skill Tree）

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

完整索引：仓库内 SKILL_TREE.md / skill_tree.json 为作者快照（示例）；使用者在自己的环境运行 scripts/build_skill_tree.py 生成自己的技能树（或用平台自身能力清单）

📦 技能注册表（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

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

🎯 解决的痛点

📊 优先级规则

优先级从高到低：

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 任务相关硬校验）

把「靠 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

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

📝 改版说明（CHANGELOG 摘要）

v2.13.3（2026-08-21）— 失败可定位 + 兜底文案动态化

• python 分支 stderr 不再被丢弃：捕获进 debug.pre_hook_stderr（injected-context.json），失败原因可定位
• 兜底文案按真实原因动态化：fallback_reason 区分「无 python」vs「python 分支失败」，bash 降级时给用户准确提示
• injected-context.json 新增字段：python_branch_ok / fallback_reason，供 UserPromptSubmit 钩子诊断
• 技能树索引重建：total=402

v2.13.2（2026-08-21）— hooks 执行链路三大根因修复 + 版本号修正

• 解释器检测修复：python3/python/py 逐个尝试，不再硬编码 python3（hook 环境 PATH 无 python3 导致 skill_tree.json 计数归零）
• 注入块输出到 stdout：pre-hook.py 生成的完整注入块改为输出到 stdout，平台才能注入 Agent 上下文（此前只有统计行，无任何可执行内容）
• 版本号修正：SKILL.md frontmatter / description_zh / description_en 三处版本标注统一为 v2.13.2
• 技能树索引重建：total=401

v2.13.0（2026-08-21）— hooks 强制拦截上线

• hooks.json 注册钩子：SessionStart（启动注入）+ UserPromptSubmit（提交校验），WorkBuddy settings.json 一键注册
• Ruler 跨平台分发：一键将宪法安装到 10 个主流平台（Claude Code / Cursor / Windsurf / Cline / ChatGPT / Gemini / WorkBuddy / 扣子 / 文心 / 通义）
• pre-hook --task 参数修复：bash user-prompt-submit.sh "$USER_PROMPT" 支持直接传参（不再依赖 stdin JSON）
• Windows 路径转换：to_win() 函数将 Git Bash /c/... → C:/...，解决 python 在 Windows 下不认 /c/ 路径的问题
• 完整细节见 CHANGELOG.md

v2.12.0（2026-08-19）— SkillWeaver 启发：语义增强 + 防蒙混升级

• 任务同义词扩展（TASK_SYNONYM_MAP）：口语表达不再漏判——"我要把代码传上去"（无 git 关键词）也能命中 code 必需分类，Layer C 恢复生效
• SAD 宽松语义检索：SkillWeaver 反馈循环的确定性实现——pre-hook 按 token 重叠度（零依赖）检索 top-K 候选技能注入，Agent 起草方案时带着候选完成用词对齐，token 再降一档
• Layer D 语义相关性校验（step3）：引用的技能必须与任务语义相关（overlap ≥ 0.10），杜绝"引用真实存在但与任务无关的技能"蒙混过关
• 多技能编排兼容性检查（step4 + registry.json schema）：识别技能链 A → B，校验相邻技能 output→input 兼容
• 可选语义向量索引（scripts/semantic_index.py）：sentence-transformers + FAISS 的完整实现作为可选增强层；缺依赖明确提示，主链路永远零依赖
• 分类子串误杀修复：英文关键词改词边界匹配，code 不再误杀 encode、search 不再误杀 research
• 顺手修复 4 个已核实 Bug（正文版本号残留/CHANGELOG 链接/CI 死代码/badge 失真）
• 完整细节见 CHANGELOG.md

v2.11.0（2026-08-16）— 任务相关硬校验（Layer C）+ 命中清单强制 + 推荐定位修正

• 新增 Layer C 任务相关硬校验：任务含"代码/编码/编程/开发/写一个/实现/git/github/push/commit/deploy/部署/爬虫/抓取/网页/前端/文档/数据/邮件/图片/视频"等关键词时，输出必须引用 skill_tree.json 对应分类下的实际技能名（如 git-workflow-and-versioning）——彻底杜绝"查了 skills-constitution 就算查了技能"的空头汇报
• 三查汇报强制命中清单：②技能树必须列出命中的技能名（名称+依据），禁止只写"已读技能树"
• pre-hook.py 增强：新增 required_categories_for_task() / required_skills_for_task() 确定性映射（任务关键词→必需分类→候选技能），注入块自动附加「任务必需技能」清单
• step1/2/3 增加 Layer C：未引用任务对应分类技能名 → FAIL；constitution-check 新增 --task 参数
• 第五条推荐定位修正：本地技能未能完美解决任务时，必须去 GitHub 搜索高 Star 技能推荐给用户（含链接+star+获取方式），由用户自行决定是否安装；本地不足却不去搜索 → 违规
• 完整细节见 CHANGELOG.md

v2.10.0（2026-08-16）— 输入拦截 + 双通道执行

• 新增 pre-hook.py：任务开始前强制读取 MEMORY.md + skill_tree.json 生成注入块，Agent 上下文"被迫"已有记忆规则和技能树分类
• 双通道分流：--classify 确定性分类器（零号条款协调）——简单任务（翻译/润色/解释）→ 通道A 零号条款豁免直接通用能力；专业任务（编码/爬虫/API）→ 通道B 强制注入校验 + step1-5 全量校验；模糊任务 → 宁可不放过按通道B
• 关键设计：分类器是确定性代码，不依赖 Agent 自觉判断任务类型，杜绝"把专业任务误判为简单任务"逃逸
• 完整细节见 CHANGELOG.md

v2.9.0（2026-08-16）— 三明治架构两层校验

• Pre-hook 层：Step1/2 硬校验，验证回复是否真实引用 MEMORY.md / skill_tree.json 内容（杜绝空头汇报）
• Post-hook 层：retry-wrapper.py 重试循环，失败自动注入错误提示并重试（最多3次），超限转人工
• 两层校验：软校验（文本关键词）+ 硬校验（验证实际文件内容引用）

🏗️ 项目结构

skills-constitution/
├── SKILL.md                    # 宪法文档（主文件）
├── README.md                   # 本文件
├── CHANGELOG.md                # 版本日志
├── SKILL_TREE.md               # 技能树索引（人类可读）
├── skill_tree.json             # 技能树索引（机器可读）
├── scripts/
│   ├── build_skill_tree.py     # 分类脚本（v2.12.0 词边界匹配修复子串误杀）
│   ├── pre-hook.py             # 输入拦截+任务分类器（v2.10.0）；任务必需技能映射（v2.11.0）；同义词扩展+SAD 宽松检索（v2.12.0）
│   ├── semantic_index.py       # 可选语义向量索引（v2.12.0，sentence-transformers 可选依赖）
│   ├── constitution-check      # 门禁校验主入口（v2.6.0；v2.10.0 支持 --classify/--pre-hook；v2.11.0 支持 --task）
│   ├── retry-wrapper.py        # Post-hook 重试循环（v2.9.0）
│   ├── steps/                  # 5 个 step 独立校验脚本
│   │   ├── step1-check.py      # 三查汇报（软+硬+Layer C 任务相关，v2.11.0）
│   │   ├── step2-check.py      # 技能树已读（软+硬+Layer C，v2.11.0）
│   │   ├── step3-check.py      # 技能调用（软+硬+Layer C+Layer D 语义相关，v2.12.0）
│   │   ├── step4-check.py      # 交付自检+多技能编排兼容性（v2.12.0）
│   │   └── step5-check.py      # 推荐板块（软+硬两层）
│   ├── tests/
│   │   └── run_tests.py        # 零依赖回归测试（v2.12.0，CI 可跑）
│   └── lib/                    # 状态文件 + 文本工具（v2.12.0 轻语义工具）
└── .github/
    └── workflows/
        └── build-skill-tree.yml  # 自动更新

📚 平台适配指南

详细适配指南见 SKILL.md 中的【平台映射表】章节。

支持的框架

• 国际：ChatGPT, Claude, Codex, Gemini, Cursor, Windsurf, Cline, GitHub Copilot
• 国内：WorkBuddy, 扣子 (Coze), 文心一言, 通义千问, Kimi, 豆包, 智谱, 月之暗面, Dify

🤝 贡献

欢迎提交 Issue 和 PR：

• 功能增强：扩展分类规则、增加平台映射
• 文档优化：修正表述、增加示例
• Bug 修复：分类逻辑、脚本错误

📄 License

MIT License — 随意使用、修改、分发。

👤 作者

jiabaobei — GitHub

如果这个规则帮你解决了 Agent 不调用能力的问题，欢迎 ⭐ Star 收藏，转发给身边被 Agent 气到的朋友！