trae-community · Century0327 · Aug 16, 2026 · Aug 16, 2026
diff --git a/README.md b/README.md
@@ -103,6 +103,7 @@ This section will list available skills as they are added.
 | [web-design-teroop](skills/web-design-teroop/SKILL.md) | Comprehensive design guidance for new frontend projects, covering style, logos, icons, and animations. | New Project, Web Design, UI/UX, Branding | Stable |
 | [trae-claw-install](skills/trae-claw-install/SKILL.md) | Repository-driven OpenClaw deployment workflow with platform routing, acceptance checks, and unified troubleshooting steps. | OpenClaw Deployment, DevOps Workflow, Troubleshooting | Stable |
 | [cloudbase](skills/cloudbase/SKILL.md) | Tencent CloudBase development in Trae — MCP-first workflow for Web, WeChat Mini Program, auth, databases, cloud functions, CloudRun, storage, and built-in AI. | CloudBase, 腾讯云开发, Web, Mini Program, Serverless | Stable |
+| [project-governance](skills/project-governance/SKILL.md) | Project governance workspace for AI-assisted development — project protocol (rules, permissions, autonomy levels), directory index, lessons log, session handoff, changelog, version index, and whitelist/blacklist parameter registries, with a scaffold/validate/index/check CLI. | Project Setup, AI Agent Onboarding, Parameter Versioning, Project Governance | Stable |
 
 
 > Tip: To add your skill to this catalog, update this table in your PR.

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -103,6 +103,7 @@ description: 简要描述这个技能的功能和使用场景
 | [video-to-keyframes](skills/video-to-keyframes/SKILL.md) | 抽取视频帧、检测转场与分段、筛选候选关键帧，并生成可复筛的 HTML 画廊。 | 视频分析, 关键帧筛选, 分镜初筛 | Stable |
 | [web-design-teroop](skills/web-design-teroop/SKILL.md) | 为新前端项目提供全面的设计指导，涵盖风格、Logo、图标和动画设计。 | 新项目, Web 设计, UI/UX, 品牌设计 | Stable |
 | [cloudbase](skills/cloudbase/SKILL.md) | 在 Trae 中进行腾讯云开发（CloudBase）开发：优先 MCP 工具，覆盖 Web / 微信小程序、登录鉴权、数据库、云函数、云托管、云存储与内置 AI。 | 云开发, CloudBase, Web, 小程序, Serverless | Stable |
+| [project-governance](skills/project-governance/SKILL.md) | AI 辅助开发的项目治理工作区——项目协议（规则、权限、自主权等级）、目录索引、错误档案、会话交接、变更日志、稳定版本索引，以及 whitelist/blacklist 参数注册表，附带 scaffold/validate/index/check CLI。 | 项目搭建, AI Agent 接入, 参数版本管理, 项目治理 | Stable |
 
 > 提示：要把你的技能加入此目录，请在 PR 中更新此表格。
 

diff --git a/skills/project-governance/README.md b/skills/project-governance/README.md
@@ -0,0 +1,101 @@
+# project-governance
+
+给 AI 长期项目建立「项目记忆 + 文件索引 + 工作规则 + 版本记录」的治理系统。
+让 AI 换会话、换模型、甚至换 Agent 后，仍然能正确接着项目做，而不是重新猜项目。
+
+## 三层结构：治理规范 / CLI / Skill 适配器
+
+```
+project-governance
+│
+├── 治理规范本体（Agent-agnostic，跨平台通用）
+│   ├── templates/AGENTS.md        — 项目协议模板（核心规则 + 项目定制）
+│   ├── templates/index.md         — 目录地图模板（带链接 + 注释）
+│   ├── templates/index_notes.json — index 短注释注册表
+│   ├── templates/VERSIONS.md      — 稳定版本索引模板（权威等级）
+│   ├── templates/LESSONS.md       — 错误档案模板
+│   ├── templates/CHANGELOG.md     — 变更记录模板
+│   ├── templates/whitelist.json   — 通过参数注册表
+│   └── templates/blacklist.json   — 失败参数注册表
+│
+├── CLI / Validator（Agent-agnostic）
+│   └── scripts/governance.py      — init / validate / index / check
+│
+└── Skill 封装（Agent-specific）
+    └── SKILL.md                   — 告诉 Trae 如何发现和使用这套体系
+```
+
+核心原则：
+
+> **治理数据保持 Agent-agnostic；适配层才允许 Agent-specific。**
+
+`VERSIONS.md` / `LESSONS.md` / `whitelist.json` / `blacklist.json` / `index.md`
+是跨 Agent 的公共协议；`SKILL.md` / `CLAUDE.md` / `AGENTS.md` / `.cursor/rules/`
+属于适配器。这样即使某个 AI 平台改变 Skill 机制，治理体系本身不会跟着废掉。
+
+Skill 只是「告诉某个 Agent 如何理解和使用这套治理体系的适配器」，不是治理体系本身。
+
+## Memory & Governance Boundary
+
+平台记忆（如 Trae 的用户档案 / 项目记忆）与治理文件是互补关系，不是重复：
+
+| 层 | 回答什么 |
+|---|---|
+| 平台记忆 | "以前发生过什么 / 这个用户通常怎么做" |
+| 治理文件 | "这个项目现在必须怎么做、文件在哪、哪个版本是权威" |
+
+冲突时的权威优先级：
+
+1. 当前项目文件 / 冻结版本
+2. 项目治理文件（AGENTS.md / index.md / VERSIONS.md / 注册表）
+3. 项目记忆
+4. 用户长期记忆
+5. AI 推测
+
+记忆是**上下文来源，不是权威事实库**。当记忆与治理文件冲突时，以治理文件为准；
+从记忆获得的长期约定，应在人工确认后沉淀进治理文件，记忆本身永远不能成为项目权威。
+
+## 快速开始
+
+```bash
+python scripts/governance.py init --project-dir /path/to/project --project-name "My Project"
+python scripts/governance.py index --project-dir /path/to/project
+python scripts/governance.py check --project-dir /path/to/project
+```
+
+## 子命令
+
+| 子命令 | 作用 |
+|---|---|
+| `init` | 从 templates/ 生成 11 个治理文件（--force 覆盖已有文件） |
+| `validate` | 校验 whitelist/blacklist 是否符合 schema（--relaxed 用于迁移旧注册表） |
+| `index` | 从文件系统重建 index.md 目录地图（带链接 + index_notes.json 注释，可自定义章节名） |
+| `check` | 健康检查：必需文件、注册表、index_notes.json、index 是否最新 |
+
+## 验收：Trae 冷启动实测
+
+安装 Skill 后，用新会话进入一个陌生项目，验证：
+
+1. Trae 是否发现并加载 Skill
+2. AI 是否主动读取 `index.md`
+3. 是否找到正确版本（而不是历史错误文件）
+4. 是否遵守 `AGENTS.md`
+5. 是否读取 `whitelist.json` / `blacklist.json`
+6. 修改文件后是否更新 `index.md` / `CHANGELOG.md` / `session_handoff.md`
+7. 第二次冷启动能否无人工解释继续工作
+
+## Limitations
+
+**Agent compatibility**
+
+This package is currently designed and tested primarily for Trae Skills. Other
+AI coding agents may use the generated governance files, but automatic Skill
+discovery, loading, and instruction behavior are not guaranteed outside Trae.
+
+The governance files and CLI are intentionally kept as agent-neutral as
+practical, allowing future adapters for other AI agents without changing the
+core governance structure.
+
+## 验证
+
+CLI 已通过 76 用例健壮性测试（基础 + 边界 + 对抗性，stdlib-only），覆盖空目录、非 UTF-8 编码、目录型路径、超长路径、特殊字符文件名等破坏式场景。测试套件保留在开发仓库中，未随包发布。
diff --git a/skills/project-governance/SKILL.md b/skills/project-governance/SKILL.md
@@ -0,0 +1,127 @@
+---
+name: project-governance
+description: Set up and maintain a project governance workspace for AI-assisted long-running projects — project protocol (AGENTS.md), directory index (index.md), error log (LESSONS.md), session handoff, changelog, stable version index (VERSIONS.md), whitelist/blacklist parameter registries. 为 AI 长期项目建立「项目记忆 + 文件索引 + 工作规则 + 版本记录」的治理系统，让 AI 在长期项目里「不忘事、不乱改、不重复犯错」，换会话后仍能接着做。Use when the user complains the project is messy, files are scattered or misplaced, the AI repeats mistakes or uses wrong versions, the user expects the AI to find files itself instead of asking for paths, when starting a new AI-assisted project, onboarding an AI agent into an existing project, or when a project lacks structured rules/versioning. 触发场景：项目太乱、文件乱、找不到文件、乱放文件、又用错版本、项目太多怎么管理、上次做到哪、你不是应该记得吗、哪个才是最终版、建立规则、版本索引、黑白名单。
+---
+
+# Project Governance
+
+> 中文：给 AI 长期项目建立一套「项目记忆 + 文件索引 + 工作规则 + 版本记录」的管理系统，让 AI 换会话、换模型后仍能正确接着项目做，而不是重新猜项目。
+
+## 30-second overview
+
+这个 Skill 给项目增加 8 个东西：
+
+1. 项目规则 —— AI 应该怎么做
+2. 文件地图 —— 文件在哪里
+3. 项目状态 —— 现在做到哪里
+4. 错误记录 —— 以前踩过什么坑
+5. 版本索引 —— 哪个版本才是真的
+6. 黑白名单 —— 什么能用、什么不能用
+7. 会话交接 —— 上一个 AI 做到哪里
+8. 变更记录 —— 为什么这么改
+
+核心目标：**让 AI 换会话、换模型、甚至换 Agent 后，仍然能正确接着项目做，而不是重新猜项目。**
+
+## When to Use
+
+Use this skill when:
+
+- The user complains the project is messy, files are scattered, or the AI keeps misplacing files ("你怎么又乱放文件").
+- The user expects the AI to find files itself instead of asking for paths ("你自己找").
+- The AI keeps repeating mistakes or using wrong versions.
+- The user says "你不是应该记得吗？" / "上次不是已经验证过了吗？" / "哪个才是最终版？" / "别重新做，之前已经跑通了" — Memory + Governance boundary scenarios where memory alone is not a reliable authority.
+- Starting a new AI-assisted project and you want the agent to follow a stable protocol from day one.
+- Onboarding an AI agent into an existing project that has no rules, error log, or parameter registry.
+- A project has grown messy: files scattered, parameters changed without record, past mistakes repeated.
+- You want to enforce durable rules such as "index-first file lookup", "plan before execute", "file existence ≠ file validity", or "registry-driven parameter selection".
+
+Do NOT use this skill when:
+
+- The task is a one-off question or small edit that does not need project-wide conventions.
+- The project already has a mature governance system and you only need a small rule tweak — edit the existing files directly instead.
+
+## Memory & Governance Boundary
+
+Platform memory (e.g. Trae user profile / project memory) is a **context source,
+not an authoritative fact store**. Governance files are the **project execution
+protocol**. The two complement each other:
+
+| Layer | What it answers |
+|---|---|
+| Platform memory | "What happened before / how does this user usually work" |
+| Governance files | "How this project must work now, where files are, which version is authoritative" |
+
+Authority priority when they conflict:
+
+1. Current project files / frozen versions
+2. Project governance files (`AGENTS.md`, `index.md`, `VERSIONS.md`, registries)
+3. Project memory
+4. User long-term memory
+5. AI inference
+
+When memory and governance files disagree, **governance wins**. Durable
+conventions learned from memory must be settled into the governance files after
+human confirmation — memory alone never becomes the project's authority.
+
+## Instructions
+
+### Step 1 — Scaffold
+
+```bash
+python scripts/governance.py init --project-dir /path/to/project --project-name "My Project"
+```
+
+Creates 11 governance files from `templates/` (never overwrites existing files unless `--force`).
+
+### Step 2 — Customize
+
+Edit the generated `AGENTS.md`: directory permission zones, autonomy levels, artifact placement rules, and project-specific rules under "Project Customization". Keep the universal Core Governance Rules as-is.
+
+### Step 3 — Maintain (every session)
+
+1. **Session start**: read `index.md` → `session_handoff.md` → `LESSONS.md`; before generating parameters, read `blacklist.json` / `whitelist.json`.
+2. **During work**: find files via the index (never blind search); inherit whitelist entries with `score > 0.85`; never use `permanent_ban: true`; record new mistakes in `LESSONS.md`.
+3. **Session end**: update `session_handoff.md`, `index.md` (file changes), `CHANGELOG.md` (decisions).
+
+### Step 4 — Validate, index, check
+
+```bash
+python scripts/governance.py validate --project-dir /path/to/project   # registries conform to schema
+python scripts/governance.py index --project-dir /path/to/project      # rebuild index.md map (links + notes)
+python scripts/governance.py check --project-dir /path/to/project      # health gate: files + registries + fresh index
+```
+
+### Input / Output
+
+- **Input**: a project directory (with or without existing governance files), a project name, and the user's governance pain points (messy files, wrong versions, repeated mistakes, "你自己找").
+- **Output**: a governance workspace (`AGENTS.md`, `index.md`, `VERSIONS.md`, `LESSONS.md`, `session_handoff.md`, `CHANGELOG.md`, `whitelist.json` / `blacklist.json`) plus a validated, up-to-date index.
+
+### On Failure
+
+- `init` fails (invalid path, permission): report the exact failing command and reason; do not partially scaffold or guess.
+- `validate` reports schema errors: fix the registry entries; never bypass validation.
+- `check` fails (missing files / stale index): run `index`, then re-run `check`; if still failing, report to the human.
+- Never fabricate a "passed" result — report what was verified and what was not.
+
+## What It Produces
+
+| File | Purpose |
+|---|---|
+| `AGENTS.md` | Project protocol: core governance rules, authority levels, first-run protocol, permission zones, trust boundary |
+| `index.md` + `index_notes.json` | Authoritative directory map with clickable links and short notes |
+| `VERSIONS.md` | Stable version index with human judgments |
+| `LESSONS.md` | AI error & correction log |
+| `session_handoff.md` | End-of-session handoff |
+| `CHANGELOG.md` | Decision & version history |
+| `whitelist.json` / `blacklist.json` | Verified / failed parameter registries |
+| `ARCHITECTURE.md` / `PROJECT.md` | Architecture & project card |
+
+## Details
+
+- `README.md` — full package overview: Core / CLI / Skill-adapter structure, subcommands, limitations, Trae cold-start acceptance test
+- `templates/` — governance file templates
+- `scripts/governance.py` — init / validate / index / check CLI
+
+## Limitations
+
+This package is currently designed and tested primarily for Trae Skills. Other agents may use the generated governance files, but automatic Skill discovery/loading is not guaranteed outside Trae. The governance files and CLI are kept agent-neutral for future adapters.