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）：

双机制平台覆盖（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.31.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% 扫描量：

完整索引：仓库内 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

条目均来自真实开源仓库，见 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 任务相关硬校验；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-retr