# Skill Rule > 修改 Skill / Rule / Agent 文件的操作规范。当 AI 或用户需要新增、修改、删除 .cursor/skills/ 或 .cursor/rules/ 或 .cursor/agents/ 中的任何文件时触发。修改前必须遵循本规范，未经本规范允许不可直接改写 Skill/Rule/Agent。 Use when this capability is needed. - Skill: `tomevault-io/skill-rule` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/skill-rule` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/skill-rule/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/skill-rule --- # Skill / Rule / Agent 修改规范 > Skill、Rule、Agent 是 AI 行为的「操作系统」。修改它们比修改功能代码风险更高——一行错误的规则会影响所有未来任务的执行，而且问题难以溯源。 > > **修改 Skill/Rule/Agent 和修改生产代码一样，需要相同严格的流程。** > > **三型作用域**： > - `.cursor/skills/`：Skill 文件（步骤化流程，按场景触发） > - `.cursor/rules/`：Rule 文件（全局约束，alwaysApply 或条件触发） > - `.cursor/agents/`：Agent 文件（独立上下文执行单元，如 verifier / user-simulator） > > 三型文件均受本规范约束，无例外。判断应建哪型，参照 `Skill体系设计原则_v1.0.md §2.5 统一决策树`。 --- ## 知识导航表（执行前必须理解的概念根） > 本 Skill 的步骤设计基于以下文档的核心概念。若不理解这些概念，步骤无法正确执行。 | 层级 | 文档 | 需要理解的概念 | |---|---|---| | **D0 认知根（必读）** | `_内部总控/认知结构/L1_系统性文档/系统架构思维维度/Skill体系设计原则_v1.0.md` | §2.2 Rule本质（普遍约束<300词）；§2.3 Skill本质（任务流程）；§2.4 Agent本质（隔离执行）；§2.5 三型统一决策树；§4 文档体系与知识层次 | | **D3 规范参考** | `_内部总控/认知结构/L1_系统性文档/系统架构思维维度/系统对象全量分类表_20260320.md` | 类型A（Rule）/ B（Skill）/ C（Agent）的完整定义与存放位置 | | **D4 运行时数据** | 目标 Skill/Rule/Agent 文件（执行时确定）| 待修改对象的当前版本和现有内容 | **核心概念速查**： ① ceremony(B) = 备份→三问→最小化修改→变更记录→更新索引 ② alwaysApply Rule = 每次对话注入，违反即错误（应≤4个，目前过多是已知技术债） ③ Skill趋薄化 = 知识迁移到 K-objects，Skill 只保留导航+触发+守门 --- ## Step 0：复杂度级别判断（所有操作的第一步） **在回答三问之前，先判断本次操作属于哪个级别**： ``` Level 1 补丁型：修改已有组件的局部内容（一个步骤/注意事项/触发词措辞） → 走本规范的「三问 + 备份 + 修改 + 变更记录 + 索引」流程 → 不需要 skill-designer 引导，直接执行 Level 2 新增型：新建独立 Skill/Agent/Rule，与现有系统无显著交互 → 先走 skill-designer 的 Step 1-5（含关卡A + 关卡C） → 完成后回到本规范 Step 4-6（备份 + 写入 + 变更记录 + 索引） Level 3 集成型：新建组件，与多个现有组件有触发词重叠或调用关系 → 先走 skill-designer 的 Step 1-7（含关卡A + 关卡B + 关卡C） → 完成后回到本规范 Step 4-6 Level 4 系统型：重构多个现有组件的交互关系 → 先走 skill-designer 完整八步 → 需要在 Step 3（产品定义）完成后，暂停等待用户二次确认规模 ``` **Level 判断有疑问时**：加载 `skill-designer` Skill，由它引导判断。 --- ## ⚠️ 修改前必须回答的三个问题（Level 1 及所有级别通用） 在动笔之前，必须能清楚回答以下三问。答不出来，不允许开始修改。 ``` 1. 这次修改的根因是什么？ → 是 AI 执行中发现了真实的执行漏洞？ → 还是用户/AI 凭感觉觉得"应该加点什么"？ → 根因必须来自真实事件（某次任务执行的具体问题），不能是假设 2. 修改后，会影响哪些已有的执行路径？ → 哪些任务会因为这个改动而改变行为？ → 有没有可能让之前正常工作的流程变得不正常？ 3. 怎么验证改完之后规则确实生效且没有副作用？ → 能不能构造一个具体的场景来验证新规则？ → 用什么方法检查没有破坏已有约束？ ``` --- ## 激活后立即执行 ``` Step 1 Read: 被修改的 Skill/Rule 文件（了解现状） Step 1.5 Read: _内部总控/认知结构/L1_系统性文档/系统架构思维维度/Skill体系设计原则_v1.0.md → 重点阅读：§4.3.5「认知根原则」，确认本次修改有认知根支撑 → 带着以下问题进入 Step 2：「本次修改是否与该 Skill 的认知根一致？ 是否会让这个 Skill 更难追溯到认知结构？」 Step 2 Read: 相关联的 Skill/Rule（检查是否有冲突风险） → 如果改测试工程师 Skill，要读 role-menu.mdc → 如果改 role-menu.mdc，要读所有被引用的 Skill Step 3 回答「修改前三问」，写在修改记录里 Step 4 执行修改（见操作规范） Step 5 执行闭环验证（见验证规范） Step 6 写修改记录（见留痕规范） ``` --- ## 修改操作规范 ### 1. 最小化原则 **只改需要改的，不顺手改其他**。 ``` ✅ 允许：针对具体问题修改对应章节 ✅ 允许：新增一个新章节/新条目 ✅ 允许：删除一个被验证无效或有害的规则 ❌ 禁止：「顺手」重新整理整个文件的格式 ❌ 禁止：一次修改超过 3 个独立的规则点（拆分成多次修改） ❌ 禁止：在没有根因的情况下「完善」措辞 ``` **为什么**：每次改动范围越小，出问题时越容易定位根因。 ### 2. 版本留痕 **修改任何 Skill/Rule 之前，必须先留痕**。 ``` 操作（Skill）： Copy-Item .cursor/skills/[skill-name]/SKILL.md → .cursor/skills/[skill-name]/history/SKILL_v旧版_YYYYMMDD.md 操作（Rule）： Copy-Item .cursor/rules/[rule-name].mdc → .cursor/rules/history/[rule-name]_YYYYMMDD.mdc 操作（Agent 子智能体）： 新建 agent → 无需备份（文件不存在） 修改 agent → Copy-Item .cursor/agents/[agent-name].md → .cursor/agents/history/[agent-name]_YYYYMMDD.md ``` 没有先留痕就修改 = 无法回滚 = 不允许操作。 **Agent 子智能体的特殊规则**： - `.cursor/agents/` 目录下的 `.md` 文件与 Skill/Rule 同等重要，修改时遵循相同流程 - 新建 agent 无需备份，但需要在 SKILL-INDEX.md 的「子智能体清单」中注册 - 废弃 agent 时：将文件移入 `.cursor/agents/history/deprecated/` 目录，并更新索引 ### 3. 规则冲突检查 **新规则不能与现有规则产生矛盾**。 ``` 检查清单： □ 新规则是否与 role-menu.mdc 中的强制规则冲突？ □ 新规则是否与同一个 Skill 内的其他规则矛盾？ □ 新规则是否假设了其他 Skill 的某个行为，而那个 Skill 没有保证这个行为？ □ **能力独立性检查（2026-03-20 新增）**： - 本次修改是否在流程层/角色层 Skill 里新增了 API 调用、外部工具调用？ 如果是 → 先查 SKILL-INDEX 能力层分类，确认是否已有对应能力层 Skill。 有 → 引用，不嵌入 无 → 先建能力层 Skill，再引用 - 本次修改是否引入了 API Key / 模型名 / Endpoint URL？ 如果是 → 必须引用 `_内部总控/凭证/` 配置文件，不得硬编码 □ 如果两个规则都适用，AI 应该遵守哪个？（模糊 = Bug） ``` 有冲突 → 先解决冲突，再写新规则；不能「新旧并存」。 ### 4. Rule-Skill 配套完整性检查（新增，2026-03-20） **当新建一个 `alwaysApply: true` Rule 时，必须强制回答以下问题**： ``` □ 这条 Rule 是否包含「AI 应该怎么做」的知识内容（不只是「不能做什么」）？ → YES：必须同时创建或指向配套 Skill，将正向知识内容放入 Skill → NO（纯禁止清单）：只创建 Rule 即可 □ 是否已存在覆盖此领域的 Skill？ → 已存在：在 Rule 的 Step 2 中引用该 Skill → 不存在：必须新建 Skill（Level 2 流程），不允许把知识内容堆在 Rule 里 ``` **根因**：Rule = 约束层（防违规），Skill = 知识层（怎么做对）。 把知识内容放进 Rule 会导致： - AI 无法主动查阅（Rule 不是主动调用的对象） - 内容冗余分散，更新时需要同步两处 - 用户无法通过 role-menu 路由找到此领域知识 **典型场景**（触发本检查）： - 新建「前端品牌规范」Rule → 必须配套「frontend-brand」Skill（正反已验证） - 新建「后端 API 规范」Rule → 必须配套「backend-api-conventions」Skill - 新建「代码提交规范」Rule → 纯约束（禁止/强制格式），可不建 Skill **允许例外**（不需要配套 Skill 的 Rule）： - 纯元认知约束：如 `knowledge-integrity-rules`（R1-R15 认知护栏） - 纯流程钩子：如 `auto-experience-hook`（结束时执行固定动作） - 纯安全防护：如 `multi-project-file-guard`（防路径混淆） --- ## 闭环验证规范（修改后必须执行） 修改 Skill/Rule 后，不能只靠「读起来对」来判断是否有效。必须构造验证场景。 ### ⚠️ 认知体系相关 Skill：强制使用 SANDBOX-FORMAT 正式两阶段沙盘 **触发条件**：修改的 Skill 满足以下任一条件： - Skill 名称以 `cognitive-` 开头 - Skill 的执行步骤中读取或写入 `_内部总控/认知结构/` 目录下的文件 - Skill 是「数字大脑」体系的核心组成部分（如 cognitive-ask / cognitive-update-knowledge 等） **强制要求**： 1. **修改前**：必须先创建「当前行为」的正式沙盘（`sandboxes/认知结构/` 或 `sandboxes/Skill体系/`），记录现有行为的 Phase 1 预想 + Phase 2 实际 2. **修改后**：必须更新或新建「修复后行为」的沙盘，重新执行 Phase 2 验证，确认 Gap 已消除 3. 沙盘必须按 `_内部总控/skill-system-design/SANDBOX-FORMAT.md` 标准格式 4. **不允许跳过**：没有正式沙盘就修改认知体系 Skill = 规范违规，修改无效，必须补做沙盘并验证 **沙盘精度要求**（认知体系适用「最精确、最复杂」标准）： - Phase 1 中，预想行为必须基于文档中已明确描述的能力，不允许「理想化」 - Phase 2 中，验证必须覆盖「全局性问题」和「聚焦性问题」两种输入类型 - Gap 描述必须有具体文件路径 + 步骤引用，不允许模糊归因 --- ### 验证方法 A：正向验证（新规则是否生效） 构造一个**如果没有这个规则 AI 会犯错**的场景，验证加了规则后 AI 确实行为不同。 ``` 示例（验证关卡C 的「AI 自测视角切换」规则）： 场景：AI 刚写完一段代码 预期：AI 应该明确宣告「切换为测试工程师视角」再测试 验证：在对话里触发这个场景，检查 AI 是否按新规则行动 ``` ### 验证方法 B：负向验证（没有破坏已有约束） 选 1-2 个依赖被修改 Skill 的常见任务，验证它们仍然正常工作。 ``` 示例（验证测试工程师 Skill 修改后）： 场景：触发一次正常的关卡C 预期：关卡C 的已有行为（Bug 报告格式、产品偏差分类）不变 验证：走一遍关卡C，确认原有行为没有被破坏 ``` ### 验证方法 C：冲突验证（规则之间没有矛盾） 人工读一遍同一 Skill 内所有规则，检查有没有「两条规则都适用但指向不同行为」的情况。 --- ## 留痕规范（修改记录） 每次修改完成后，**必须执行以下两步**，缺一不可： ### Step A：在 Skill 文件底部追加变更记录 每次修改完成后，在对应 Skill 文件底部追加一条变更记录。 **格式**： ```markdown --- ## 变更记录 ### YYYY-MM-DD HH:MM — [变更标题] **根因**：[一句话描述触发本次修改的真实事件] **修改内容**： - 新增：[章节/条目名] → [一句话描述内容] - 修改：[章节/条目名] → [从什么改成了什么] - 删除：[章节/条目名] → [为什么删除] **验证结果**： - 正向验证：[场景] → [结果：通过/未通过] - 负向验证：[场景] → [结果：通过/未通过] **已知风险**：[如有，描述可能的副作用及观察方式] ``` ### Step B：同步更新 Skill 总索引 修改任何 Skill 后，**必须同步更新** `.cursor/skills/skill-index/SKILL-INDEX.md`： ``` 操作清单： □ 找到对应 Skill 在索引中的行 □ 更新版本号（规则见下方） □ 更新「最近更新」日期为今日 □ 如果本次修复了已知问题，状态改为 ✅ 已验证 □ 在索引底部「变更记录」追加一行：[日期] | [Skill目录名] | v旧→v新 | [修改一句话摘要] ``` **版本号规则**： - 核心逻辑/步骤顺序变动 → 版本号第二位 +1（v1.0 → v1.1） - 注意事项/触发词/文字修正 → 版本号第三位 +0.1（v1.0 → v1.0.1） --- ## 什么情况下允许跳过部分步骤 只有一种情况：**紧急修复一个正在造成系统性错误的规则**。 ``` 允许跳过：版本留痕（可事后补）、闭环验证（可事后补） 不允许跳过：修改前三问（必须回答）、留痕记录（必须写） ``` --- ## 与其他 Skill 的关系 本 Skill 是所有其他 Skill 修改的**前置条件**，优先级高于被修改的 Skill 本身。 即：即使某个 Skill 本身说「可以随时更新」，修改它之前也必须先过本 Skill 的流程。 --- ## 变更记录 ### 2026-03-19 00:59 — 初始创建 **根因**：在修改测试工程师 Skill 时，发现没有任何规范约束「如何修改 Skill」本身。这导致本次修改是在没有留痕、没有验证的情况下进行的——恰好违反了本 Skill 要建立的原则。 **修改内容**： - 新增：本 Skill 全部内容（首次创建） **验证结果**： - 本次为初始创建，验证将在第一次实际使用时执行 **已知风险**：`history/` 目录需要手动创建，首次使用时需要先建目录 --- ### 2026-03-19 — v1.0 → v1.1 — 加入索引联动规则 **根因**：建立了 Skill 总索引（SKILL-INDEX.md）和 skill-capture-closure Skill 后，修改规范需要强制要求「每次修改 Skill 必须同步更新索引」，否则索引与实际状态会产生漂移。 **修改内容**： - 修改：「留痕规范」章节 → 从「追加变更记录」单步，改为「Step A：追加变更记录 + Step B：同步更新索引」两步强制操作 - 新增：版本号规则说明（第二位/第三位的使用场景） **验证结果**： - 本次修改即遵循了新规范（已备份 history/SKILL_v1.0_20260319.md，并将同步更新索引） **已知风险**：Step B 的执行依赖 SKILL-INDEX.md 存在。若索引文件被移动，需同步修改本规范中的路径引用 --- ### 2026-03-19 — v1.2 → v1.3 — 加入复杂度分级判断（Step 0） **根因**：产品框架 Human-Readable + Agent-Operable 原则适用于 Skill 开发，Skill 有两类用户（人类设计者 + AI执行者）。建立 skill-designer Skill 后，修改规范需要在三问之前增加「复杂度级别判断」步骤——Level 1 走原有流程，Level 2+ 先经过 skill-designer 的双视角设计验证流程。 **修改内容**： - 新增：「Step 0：复杂度级别判断」章节，置于「修改前三问」之前，包含 L1-L4 的分级标准和对应流程路由 **验证结果**： - 正向验证：新建 Level 2 Skill 时，AI 应先触发 skill-designer 而不是直接开始编写（待真实场景验证） - 负向验证：Level 1 补丁型修改（如给 Skill 加注意事项）仍走原有三问流程，不强制走 skill-designer **验证状态**：🔵 待验证 --- ### 2026-03-19 — v1.1 → v1.2 — 扩展规范覆盖 .cursor/agents/ 目录 **根因**：本次批量新建了 6 个子智能体文件（`.cursor/agents/*.md`），原规范只覆盖 `.cursor/skills/` 和 `.cursor/rules/`，agents 目录处于规范空白区。需要明确 agent 文件的留痕要求（新建无需备份、修改需备份、废弃需归档）。 **修改内容**： - 修改：「版本留痕」章节 → 新增「操作（Agent 子智能体）」分支，说明新建/修改/废弃三种情况的处理方式 **验证结果**： - 正向验证：修改任何 agent 文件时，AI 应先备份到 history/ 目录（待真实场景验证） - 负向验证：Skill 和 Rule 的留痕流程不变 **已知风险**：`.cursor/agents/history/deprecated/` 目录需首次使用时手动创建 --- ### 2026-03-19 — v1.3 → v1.4 — 认知体系相关 Skill 强制 SANDBOX-FORMAT 正式沙盘 **根因**：修改 cognitive-ask Skill 时，只做了非正式验证场景描述，未运行 SANDBOX-FORMAT 两阶段沙盘。用户指出：所有涉及认知体系的 Skill 修改，必须做「最精确、最复杂」的正式沙盘。规范中「闭环验证」一节只要求非正式验证，是结构性漏洞。 **修改内容**： - 新增：「⚠️ 认知体系相关 Skill：强制使用 SANDBOX-FORMAT 正式两阶段沙盘」章节，位于「闭环验证规范」开头 - 明确触发条件：cognitive-* Skill / 读写 认知结构/ 目录 / 数字大脑核心组成部分 - 明确强制要求：修改前沙盘（记录现有行为）+ 修改后沙盘（验证 Gap 消除） - 明确精度要求：不允许理想化 Phase 1 / 覆盖全局+聚焦两类输入 / Gap 必须有具体证据 **验证结果**： - 正向验证：下次修改 cognitive-ask 时，必须先建沙盘，不能直接修改文件 - 负向验证：非认知体系的 Skill 修改（如 role-DevOps）不触发此要求，走原有验证流程 --- ### v1.6 — 2026-03-22 — Step 1.5 新增读取 Skill体系设计原则_v1.0.md **根因**：Skill体系设计原则_v1.0.md §4.3.5（认知根原则）要求所有 Skill 修改需确认与认知根一致，但 skill-rule-修改规范 在执行时从未读取该 L1 文档（CS-016 沙盘确认）。 **修改内容**： - 新增：Step 1.5 Read Skill体系设计原则_v1.0.md，带「本次修改是否与认知根一致」问题进入三问环节 **备份路径**：`history/SKILL_v1.5_20260322.md` --- ### v1.6 → v1.7 — 2026-03-22 — 作用域扩展至 Agent 文件（Fix 3） **根因**：description 和文件标题只声明覆盖 `.cursor/skills/` 和 `.cursor/rules/`，Agent 文件（`.cursor/agents/`）未显式纳入。修改 verifier.md/user-simulator.md 等 Agent 时可能不触发本规范，与「认知根原则」和「三型均需规范修改流程」的意图不符。 **修改内容**： - 修改：frontmatter description → 显式加入 `.cursor/agents/`，「Skill 或 Rule 文件」→「Skill / Rule / Agent 文件」 - 修改：文档标题 → `# Skill / Rule / Agent 修改规范` - 新增：正文「三型作用域」说明（三个目录 + 参考 §2.5 决策树） **备份路径**：`history/SKILL_v1.6_20260322_before_agent-scope.md` **验证状态**：🔵 待验证（修改 .cursor/agents/ 中任一文件时，此规范应被触发） --- ### 2026-03-20 — v1.4 → v1.5 — 新增「Rule-Skill 配套完整性检查」（结构性漏洞修复） **根因**：2026-03-20 真实事件——创建 `frontend-brand-guard.mdc` Rule 时，AI 只生成了约束层（Rule），没有自主判断需要同步创建知识层（Skill）。用户不得不主动指出：「应该把所有可复用的内容写到 Skill 里」。根本原因：`skill-rule-修改规范` 的「修改操作规范」章节只有「最小化原则/版本留痕/规则冲突检查」三条，没有要求检查「新 Rule 是否需要配套 Skill」。 **修改内容**： - 新增：`修改操作规范` 第 4 条「Rule-Skill 配套完整性检查」 - 内容：当新建 `alwaysApply: true` Rule 时，强制判断是否包含正向知识内容 → 有则必须同时创建或引用配套 Skill - 列出：典型需要配套 Skill 的场景 / 允许不配套的例外场景（纯元认知约束/流程钩子/安全防护） **验证结果**： - 正向验证：下次新建领域规范 Rule（如「后端 API 规范」）时，AI 应主动检查是否需要同步建 Skill（待真实场景验证） - 负向验证：新建 `knowledge-integrity-rules` 类纯元认知 Rule 时，不强制要求 Skill（例外条款覆盖） - 冲突验证：本条与「规则冲突检查（第3条）」不冲突，前者检查 Rule 内容，本条检查 Rule 完整性 **已知风险**：「是否包含正向知识内容」的判断仍依赖 AI 的理解，边界模糊时默认建 Skill（成本低，有益无害） **验证状态**：🔵 待验证（下次新建 alwaysApply Rule 时观察） --- ### v1.7.1 — 2026-03-23 — 新增知识导航表（D0/D3/D4 + 核心概念速查） **根因**：Skill 只有机械步骤，没有指向背景概念文档。AI 执行时不理解 Rule/Skill/Agent 三型本质及设计原则来源（连接缺口）。 **修改内容**： - 新增：「知识导航表」章节（D0 → Skill体系设计原则_v1.0.md §2.2/2.3/2.4/2.5；D3 → 系统对象全量分类表；D4 → 目标文件；核心概念速查 3 条） **验证状态**：🔵 待验证 **备份路径**：`history/SKILL_v1.6_20260323_before_nav.md` --- > Source: [TashanGKD/tashan-cursor-skills](https://github.com/TashanGKD/tashan-cursor-skills) — distributed by [TomeVault](https://tomevault.io).