@netpilot/skills 0.3.2

package/scripts/validate.mjs

@@ -0,0 +1,461 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const CHINESE_PATTERN = /[\u3400-\u9fff]/u;
+const NON_SKILL_INLINE_TOKENS = new Set(["name", "description"]);
+const BUILT_IN_AGENT_NAMES = new Set(["default", "worker", "explorer"]);
+const AGENT_REASONING_EFFORTS = new Set([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+  "ultra",
+]);
+const AGENT_SANDBOX_MODES = new Set(["read-only", "workspace-write", "danger-full-access"]);
+const DISPLAY_NAME_ACRONYMS = new Map([
+  ["tdd", "TDD"],
+]);
+
+function unquote(value) {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) return null;
+  const values = {};
+  for (const line of match[1].split(/\r?\n/u)) {
+    const field = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/u);
+    if (field) values[field[1]] = unquote(field[2]);
+  }
+  return values;
+}
+
+function parseOpenAiMetadata(content) {
+  const values = { interface: {}, policy: {} };
+  const structuralErrors = [];
+  const allowedKeys = {
+    interface: new Set(["display_name", "short_description", "default_prompt"]),
+    policy: new Set(["allow_implicit_invocation"]),
+  };
+  const seenSections = new Set();
+  let section = null;
+
+  if (content.includes("\uFFFD")) structuralErrors.push("文件不是合法 UTF-8");
+
+  for (const [index, line] of content.split(/\r?\n/u).entries()) {
+    const lineNumber = index + 1;
+    if (!line.trim() || line.trimStart().startsWith("#")) continue;
+    if (line.includes("\t")) {
+      structuralErrors.push(`第 ${lineNumber} 行包含 tab 缩进`);
+      continue;
+    }
+
+    if (!line.startsWith(" ")) {
+      const sectionMatch = line.match(/^(interface|policy):\s*$/u);
+      if (!sectionMatch) {
+        structuralErrors.push(`第 ${lineNumber} 行不是受支持的顶层 section`);
+        section = null;
+        continue;
+      }
+      section = sectionMatch[1];
+      if (seenSections.has(section)) structuralErrors.push(`重复 section：${section}`);
+      seenSections.add(section);
+      continue;
+    }
+
+    const fieldMatch = line.match(/^  ([a-z_]+):\s*(.+)\s*$/u);
+    if (!section || !fieldMatch) {
+      structuralErrors.push(`第 ${lineNumber} 行缩进或字段格式不合法`);
+      continue;
+    }
+    const [, key, rawValue] = fieldMatch;
+    if (!allowedKeys[section].has(key)) {
+      structuralErrors.push(`字段 ${key} 不应位于 ${section} section`);
+      continue;
+    }
+    if (Object.hasOwn(values[section], key)) {
+      structuralErrors.push(`重复字段：${section}.${key}`);
+      continue;
+    }
+
+    if (section === "interface") {
+      try {
+        const parsedValue = JSON.parse(rawValue);
+        if (typeof parsedValue !== "string") throw new Error("必须是字符串");
+        values[section][key] = parsedValue;
+      } catch {
+        structuralErrors.push(`字段 ${section}.${key} 必须是合法的双引号字符串`);
+      }
+    } else if (rawValue === "true" || rawValue === "false") {
+      values[section][key] = rawValue === "true";
+    } else {
+      structuralErrors.push(`字段 ${section}.${key} 必须是 true 或 false`);
+    }
+  }
+
+  return { values, structuralErrors };
+}
+
+function unicodeLength(value) {
+  return [...value].length;
+}
+
+function expectedDisplayName(skillName) {
+  return skillName
+    .split("-")
+    .map((part) => DISPLAY_NAME_ACRONYMS.get(part) ?? `${part[0].toUpperCase()}${part.slice(1)}`)
+    .join(" ");
+}
+
+function parseCodexAgent(content) {
+  const values = {};
+  const errors = [];
+  const instructionMatches = [
+    ...content.matchAll(/^developer_instructions\s*=\s*"""\r?\n([\s\S]*?)^"""\s*$/gmu),
+  ];
+  if (instructionMatches.length === 1) {
+    values.developer_instructions = instructionMatches[0][1].trim();
+    if (values.developer_instructions.includes("\\")) {
+      errors.push("developer_instructions 不允许反斜杠转义；分发配置使用无转义多行字符串子集");
+    }
+  } else {
+    errors.push("developer_instructions 必须是唯一的三引号多行字符串");
+  }
+
+  const scalarContent = content.replace(
+    /^developer_instructions\s*=\s*"""\r?\n[\s\S]*?^"""\s*$/gmu,
+    "",
+  );
+  const allowedFields = new Set([
+    "name",
+    "description",
+    "model",
+    "model_reasoning_effort",
+    "sandbox_mode",
+  ]);
+
+  for (const [index, line] of scalarContent.split(/\r?\n/u).entries()) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const field = trimmed.match(/^([a-z_]+)\s*=\s*"([^"\\\r\n]*)"\s*$/u);
+    if (!field) {
+      errors.push(`第 ${index + 1} 行不是受支持的字符串字段`);
+      continue;
+    }
+    const [, key, value] = field;
+    if (!allowedFields.has(key)) {
+      errors.push(`不支持的字段：${key}`);
+      continue;
+    }
+    if (Object.hasOwn(values, key)) {
+      errors.push(`重复字段：${key}`);
+      continue;
+    }
+    values[key] = value;
+  }
+
+  return { values, errors };
+}
+
+export async function validateCodexAgentDirectory(agentDir) {
+  const errors = [];
+  const agents = [];
+  let entries = [];
+  try {
+    entries = (await readdir(agentDir, { withFileTypes: true }))
+      .sort((left, right) => left.name.localeCompare(right.name));
+  } catch (error) {
+    return { agentCount: 0, agents, errors: [`无法读取 Codex agents 目录：${error.message}`] };
+  }
+
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".toml")) {
+      errors.push(`只允许普通 .toml 文件：${entry.name}`);
+      continue;
+    }
+    const expectedName = entry.name.slice(0, -".toml".length);
+    const agentPath = path.join(agentDir, entry.name);
+    let content;
+    try {
+      content = await readFile(agentPath, "utf8");
+    } catch (error) {
+      errors.push(`${entry.name}: 无法读取：${error.message}`);
+      continue;
+    }
+    const parsed = parseCodexAgent(content);
+    for (const error of parsed.errors) errors.push(`${entry.name}: ${error}`);
+    const values = parsed.values;
+
+    if (!values.name) errors.push(`${entry.name}: 缺少 name`);
+    if (values.name !== expectedName) {
+      errors.push(`${entry.name}: name 必须与文件名一致：${values.name ?? "<missing>"} != ${expectedName}`);
+    }
+    if (!NAME_PATTERN.test(values.name ?? "")) errors.push(`${entry.name}: name 不是合法 kebab-case`);
+    if (BUILT_IN_AGENT_NAMES.has(values.name)) {
+      errors.push(`${entry.name}: 不得覆盖 Codex 内置 agent：${values.name}`);
+    }
+    if (!values.description || !CHINESE_PATTERN.test(values.description)) {
+      errors.push(`${entry.name}: description 应包含中文使用边界`);
+    }
+    if (!values.developer_instructions || !CHINESE_PATTERN.test(values.developer_instructions)) {
+      errors.push(`${entry.name}: developer_instructions 应包含中文执行规则`);
+    }
+    if (Object.hasOwn(values, "model") && !values.model.trim()) {
+      errors.push(`${entry.name}: model 出现时不得为空`);
+    }
+    if (
+      Object.hasOwn(values, "model_reasoning_effort") &&
+      !AGENT_REASONING_EFFORTS.has(values.model_reasoning_effort)
+    ) {
+      errors.push(`${entry.name}: 不支持的 model_reasoning_effort：${values.model_reasoning_effort}`);
+    }
+    if (
+      Object.hasOwn(values, "sandbox_mode") &&
+      !AGENT_SANDBOX_MODES.has(values.sandbox_mode)
+    ) {
+      errors.push(`${entry.name}: 不支持的 sandbox_mode：${values.sandbox_mode}`);
+    }
+    if (values.sandbox_mode === "danger-full-access") {
+      errors.push(`${entry.name}: 分发 agent 不允许 danger-full-access`);
+    }
+    agents.push({ name: values.name ?? expectedName, path: agentPath, values });
+  }
+
+  if (agents.length === 0) errors.push("至少需要一个 Codex custom agent");
+  return { agentCount: agents.length, agents, errors };
+}
+
+export async function validateSkillDirectory(skillDir, knownNames, knownAgentNames = new Set()) {
+  const errors = [];
+  const directoryName = path.basename(skillDir);
+  const skillPath = path.join(skillDir, "SKILL.md");
+  const metadataPath = path.join(skillDir, "agents", "openai.yaml");
+  let skillContent = "";
+  let metadataContent = "";
+
+  try {
+    skillContent = await readFile(skillPath, "utf8");
+  } catch (error) {
+    errors.push(`缺少或无法读取 SKILL.md：${error.message}`);
+    return { name: directoryName, errors };
+  }
+
+  const frontmatter = parseFrontmatter(skillContent);
+  if (!frontmatter) {
+    errors.push("SKILL.md 缺少合法 YAML frontmatter");
+  } else {
+    if (!frontmatter.name) errors.push("frontmatter 缺少 name");
+    if (frontmatter.name !== directoryName) {
+      errors.push(`frontmatter name 必须与目录名一致：${frontmatter.name ?? "<missing>"} != ${directoryName}`);
+    }
+    if (!NAME_PATTERN.test(frontmatter.name ?? "")) errors.push(`name 不是合法 kebab-case：${frontmatter.name}`);
+    if (!frontmatter.description) errors.push("frontmatter 缺少 description");
+    if ((frontmatter.description?.length ?? 0) > 1024) errors.push("description 超过 1024 字符");
+    if (frontmatter.description && !CHINESE_PATTERN.test(frontmatter.description)) {
+      errors.push("description 应包含中文说明");
+    }
+  }
+
+  if (/\bTODO\b|\[TODO|PLACEHOLDER/iu.test(skillContent)) errors.push("SKILL.md 包含占位文本");
+  for (const heading of ["## 完成标准", "## 反模式"]) {
+    if (!skillContent.includes(heading)) errors.push(`缺少章节：${heading}`);
+  }
+  if (!CHINESE_PATTERN.test(skillContent)) errors.push("SKILL.md 正文应包含中文内容");
+
+  const contentWithoutFences = skillContent.replace(/```[\s\S]*?```/gu, "");
+  const references = new Set(
+    [...contentWithoutFences.matchAll(/\$([a-z0-9]+(?:-[a-z0-9]+)*)/gu)].map((match) => match[1]),
+  );
+  for (const match of contentWithoutFences.matchAll(/`([a-z0-9]+(?:-[a-z0-9]+)*)`/gu)) {
+    if (!NON_SKILL_INLINE_TOKENS.has(match[1])) references.add(match[1]);
+  }
+  for (const reference of references) {
+    if (!knownNames.has(reference)) errors.push(`未知 skill 引用：$${reference}`);
+  }
+  const agentReferences = new Set(
+    [...contentWithoutFences.matchAll(/`agent:([a-z0-9]+(?:-[a-z0-9]+)*)`/gu)]
+      .map((match) => match[1]),
+  );
+  for (const reference of agentReferences) {
+    if (!knownAgentNames.has(reference)) errors.push(`未知 Codex agent 引用：agent:${reference}`);
+  }
+
+  try {
+    metadataContent = await readFile(metadataPath, "utf8");
+  } catch (error) {
+    errors.push(`缺少或无法读取 agents/openai.yaml：${error.message}`);
+    return { name: directoryName, errors };
+  }
+
+  const metadata = parseOpenAiMetadata(metadataContent);
+  for (const structuralError of metadata.structuralErrors) {
+    errors.push(`openai.yaml 结构不合法：${structuralError}`);
+  }
+  const displayName = metadata.values.interface.display_name ?? null;
+  const shortDescription = metadata.values.interface.short_description ?? null;
+  const defaultPrompt = metadata.values.interface.default_prompt ?? null;
+  const invocationPolicy = metadata.values.policy.allow_implicit_invocation;
+
+  if (!displayName) {
+    errors.push("agents/openai.yaml 缺少 display_name");
+  } else {
+    const canonicalDisplayName = expectedDisplayName(directoryName);
+    if (displayName !== canonicalDisplayName) {
+      errors.push(`display_name 必须使用与 canonical name 对应的英文显示名：${canonicalDisplayName}`);
+    }
+  }
+  if (!shortDescription || unicodeLength(shortDescription) < 25 || unicodeLength(shortDescription) > 64) {
+    errors.push("short_description 必须为 25 至 64 个字符");
+  }
+  if (!defaultPrompt || !defaultPrompt.includes(`$${directoryName}`)) {
+    errors.push(`default_prompt 必须显式包含 $${directoryName}`);
+  }
+  if (typeof invocationPolicy !== "boolean") errors.push("allow_implicit_invocation 必须是 true 或 false");
+  if (invocationPolicy === false) {
+    errors.push("跨宿主单源策略要求 allow_implicit_invocation 为 true；动作权限应由正文门禁控制");
+  }
+
+  return { name: directoryName, errors };
+}
+
+async function readJson(filePath, errors) {
+  try {
+    return JSON.parse(await readFile(filePath, "utf8"));
+  } catch (error) {
+    errors.push(`无法读取 JSON：${filePath}（${error.message}）`);
+    return null;
+  }
+}
+
+export async function validateRepository(rootDir) {
+  const resolvedRoot = path.resolve(rootDir);
+  const errors = [];
+  const warnings = [];
+  const requiredFiles = [
+    "README.md",
+    "AGENTS.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "docs/agent-authoring.md",
+    "package.json",
+    ".codex-plugin/plugin.json",
+    ".claude-plugin/plugin.json",
+    ".claude-plugin/marketplace.json",
+  ];
+
+  for (const requiredFile of requiredFiles) {
+    try {
+      await readFile(path.join(resolvedRoot, requiredFile));
+    } catch {
+      errors.push(`缺少仓库文件：${requiredFile}`);
+    }
+  }
+
+  let skillEntries = [];
+  try {
+    skillEntries = (await readdir(path.join(resolvedRoot, "skills"), { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+      .sort((left, right) => left.name.localeCompare(right.name));
+  } catch (error) {
+    errors.push(`无法读取 skills 目录：${error.message}`);
+  }
+
+  const codexAgentResult = await validateCodexAgentDirectory(
+    path.join(resolvedRoot, "agents", "codex"),
+  );
+  for (const error of codexAgentResult.errors) errors.push(`Codex agent: ${error}`);
+  for (const agent of codexAgentResult.agents) {
+    if (Object.hasOwn(agent.values, "model")) {
+      errors.push(
+        `Codex agent: ${agent.name} 的分发配置不应固定 model；请继承当前会话或在用户层覆盖`,
+      );
+    }
+  }
+
+  const knownNames = new Set(skillEntries.map((entry) => entry.name));
+  const knownAgentNames = new Set(codexAgentResult.agents.map((agent) => agent.name));
+  const skillResults = [];
+  for (const entry of skillEntries) {
+    const result = await validateSkillDirectory(
+      path.join(resolvedRoot, "skills", entry.name),
+      knownNames,
+      knownAgentNames,
+    );
+    skillResults.push(result);
+    for (const error of result.errors) errors.push(`${entry.name}: ${error}`);
+  }
+  if (skillEntries.length === 0) errors.push("至少需要一个 skill");
+
+  const packageManifest = await readJson(path.join(resolvedRoot, "package.json"), errors);
+  const expectedVersion = packageManifest?.version ?? null;
+  if (packageManifest && Object.keys(packageManifest.dependencies ?? {}).length > 0) {
+    errors.push("本仓库不应包含生产 dependencies");
+  }
+
+  const codexManifest = await readJson(path.join(resolvedRoot, ".codex-plugin", "plugin.json"), errors);
+  if (codexManifest && codexManifest.name !== "netpilot-skills") {
+    errors.push("Codex plugin name 必须是 netpilot-skills");
+  }
+  if (codexManifest && codexManifest.skills !== "./skills/") {
+    errors.push('Codex plugin skills 必须指向 "./skills/"');
+  }
+  if (codexManifest && codexManifest.version !== expectedVersion) {
+    errors.push("Codex plugin version 必须与 package.json 一致");
+  }
+
+  const claudeManifest = await readJson(path.join(resolvedRoot, ".claude-plugin", "plugin.json"), errors);
+  if (claudeManifest && claudeManifest.name !== "netpilot-skills") {
+    errors.push("Claude plugin name 必须是 netpilot-skills");
+  }
+  if (claudeManifest && claudeManifest.version !== expectedVersion) {
+    errors.push("Claude plugin version 必须与 package.json 一致");
+  }
+
+  const marketplace = await readJson(path.join(resolvedRoot, ".claude-plugin", "marketplace.json"), errors);
+  const marketplacePlugin = marketplace?.plugins?.find((plugin) => plugin.name === "netpilot-skills");
+  if (marketplace && (!marketplacePlugin || marketplacePlugin.source !== "./")) {
+    errors.push("Claude marketplace 必须包含 source 为 ./ 的 netpilot-skills");
+  }
+  if (marketplacePlugin && marketplacePlugin.version !== expectedVersion) {
+    errors.push("Claude marketplace plugin version 必须与 package.json 一致");
+  }
+
+  return {
+    ok: errors.length === 0,
+    rootDir: resolvedRoot,
+    skillCount: skillEntries.length,
+    agentCount: codexAgentResult.agentCount,
+    errors,
+    warnings,
+    skills: skillResults,
+  };
+}
+
+async function main() {
+  const rootDir = fileURLToPath(new URL("..", import.meta.url));
+  const result = await validateRepository(rootDir);
+  if (result.ok) {
+    console.log(`校验通过：${result.skillCount} 个 skills，${result.agentCount} 个 Codex agents`);
+    return;
+  }
+  console.error(`校验失败：${result.errors.length} 个问题`);
+  for (const error of result.errors) console.error(`- ${error}`);
+  process.exitCode = 1;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}

package/skills/ask/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: ask
+description: 当用户明确要求选择工作流，或任务的目标、范围、约束、风险、成功标准与下一步不清楚时使用。它是唯一的工作流路由入口：先检查上下文，必要时提出最少量的问题，再选择并启动合适的 skill；不要把它当作普通问答或长期讨论角色。
+---
+
+# Ask
+
+`ask` 是工作流路由器，不是某个个人角色，也不是第二套需求澄清流程。目标是用尽可能少的交互找到正确入口，然后推进工作。
+
+## 工作流
+
+1. 先读取当前对话、仓库规则和与任务直接相关的文件。能从上下文或只读检查得到的答案，不询问用户。
+2. 判断任务是否已经具备可执行的目标、范围、约束和完成标准。
+3. 若信息足够，选择一个主 skill，完整读取并按它执行；控制权转交后，`ask` 不再主持后续阶段。只有存在清晰阶段关系时才给出后续 skill 链。
+4. 若缺失信息会实质改变方案、风险或写入范围，一次只问一个高价值问题。优先给出 2 至 3 个互斥选项、推荐项及影响，也允许用户自由回答。问题不阻塞安全、可逆的只读检查或设计时，先继续这些工作；只有答案会改变当前写入范围或造成不可逆影响时才暂停。
+5. 每次回答后重新判断，不机械完成预设问卷。信息足够就停止提问并进入执行。
+
+## 路由规则
+
+| 情形 | 主 skill | 常见后续 |
+| --- | --- | --- |
+| 明确要建立或继续一个跨会话学习工作区 | `teach` | `research` |
+| 需要深入访谈，并明确要求同步维护项目术语、CONTEXT 或 ADR | `grill-with-docs` | `to-spec` |
+| 重大计划、架构或产品决策需要深入访谈 | `grill` | `to-spec` |
+| 想法很大、方向模糊、需要寻找落地路径 | `wayfinder` | `research`、`prototype`、`to-spec` |
+| 陌生技术、事实或方案需要证据 | `research` | `prototype` |
+| 高风险假设需要快速实证 | `prototype` | `to-spec` |
+| 术语、概念边界或业务不变量混乱 | `domain-modeling` | `codebase-design` |
+| 需要决定模块、职责或依赖方向 | `codebase-design` | `to-spec` |
+| 已有讨论，需要形成可验收规格 | `to-spec` | `to-tickets` |
+| 已有规格，需要拆成垂直任务 | `to-tickets` | `implement` |
+| 已有明确任务，需要按边界实施 | `implement` | `code-review` |
+| 行为变更适合测试先行 | `tdd` | `code-review` |
+| bug、测试失败或异常的根因未知 | `diagnosing-bugs` | `tdd` |
+| 需要审查当前变更 | `code-review` | `implement` |
+| 需要跨会话、工具或人员继续 | `handoff` | 无 |
+| 创建或改进 skill | `writing-great-skills` | `code-review` |
+
+同一阶段只指定一个主 skill。不要同时启动多个职责重叠的 skill。
+
+相邻 skill 冲突时按未知项的性质裁决：已有较具体方案、需要挑战决策时选 `grill`；只有用户原始要求明确包含边访谈边更新项目领域文档时才选 `grill-with-docs`，不能因为仓库里存在 `CONTEXT.md` 就自动升级为写入模式；方向与落地路径尚未确定时选 `wayfinder`；主要能由外部证据回答时选 `research`；必须依靠运行结果回答时选 `prototype`。明确任务需要实现且适合测试先行时，以 `tdd` 驱动该实现切片，否则由 `implement` 统筹。
+
+## 输出
+
+信息足够时，用简短说明交代：
+
+- 选择的主 skill 及原因；
+- 已确认的关键边界；
+- 仍需验证但不阻塞开始的假设；
+- 紧接着执行的动作。
+
+如果只是轻量、明确的任务，不要为了使用 skill 而扩大流程，直接执行最短路径。
+
+## 完成标准
+
+- 已选择并开始合适的主 skill，或已提出当前唯一真正阻塞的问题。
+- 用户能看出选择依据、关键边界和下一步。
+- 没有重复询问可从上下文发现的信息。
+
+## 反模式
+
+- 不要把 `ask` 和另一个“澄清”skill 串成重复入口。
+- 不要一次抛出长问卷。
+- 不要把推荐列表当作工作成果而停止推进。
+- 不要在目标已经明确时强迫用户重新描述需求。
+- 不要替用户擅自决定会显著改变范围、成本、风险或外部状态的事项。
+- 不要把“请直接开始”解释为授权写入系统级目录、创建远程资源或一次性扩展全部范围。

package/skills/ask/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Ask"
+  short_description: "根据任务目标、范围与风险选择最合适的 skill 和工作流入口"
+  default_prompt: "请使用 $ask 判断当前任务应进入哪个工作流，并只询问真正阻塞推进的信息。"
+policy:
+  allow_implicit_invocation: true

package/skills/code-review/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: code-review
+description: 当用户要求审查当前 diff、提交、PR 或一组文件，或 AI 完成中大型代码改动需要独立检查正确性、风险、测试和架构边界时使用。它默认只读并优先报告可执行缺陷；用户要求直接修复评论时改用实施流程。
+---
+
+# Code Review
+
+代码审查首先寻找会导致错误、回归、安全问题、数据风险或维护边界破坏的具体缺陷。默认保持只读，不因审查请求直接修改文件。
+
+## 确认范围
+
+1. 明确审查对象：工作树 diff、指定 commit、PR、文件或实现切片。
+2. 读取适用的仓库规则、规格、验收标准和测试说明。
+3. 检查完整变更及必要上下文，不只看单个片段。
+4. 区分本次改动与仓库原有问题；只有变更引入、暴露或必须阻止交付的问题才作为主要 finding。
+
+## 审查顺序
+
+按风险优先检查：
+
+1. **正确性**：行为是否满足规格，边界、失败路径、状态转换和并发是否正确。
+2. **安全与数据**：认证授权、租户隔离、输入验证、密钥、注入、迁移和不可逆影响。
+3. **兼容与集成**：公共 API、schema、配置、版本、调用方和回退路径。
+4. **测试证据**：关键行为是否覆盖，测试是否会在实现错误时失败，验证命令是否真实执行。
+5. **架构边界**：所有权、依赖方向、重复规则和不必要复杂度。
+6. **可运维性**：错误信息、日志、指标、故障隔离和资源释放。
+
+格式或个人偏好只有在违反项目规则、造成真实理解成本或隐藏缺陷时才报告。
+
+## 子代理协作
+
+只有宿主支持子代理、审查范围确实包含可独立检查的表面时才并行委派：
+
+- 前端变更交给 `agent:frontend-reviewer`；
+- 后端、接口或数据变更交给 `agent:backend-reviewer`；
+- 跨模块边界和依赖方向交给 `agent:architecture-designer`；
+- 大量只读定位可先交给 `agent:code-reader`。
+
+主 agent 必须先固定 diff 基点、规格和每个子代理的排他范围，等待结果后回到完整 diff 核验证据、去重并统一优先级。custom agent 不可用时，由主 agent 串行执行同一检查维度；小改动不要为并行而并行。审查子代理默认只读，任何 finding 的修复都返回实施流程，不能在并行审查中直接写代码。
+
+## Finding 标准
+
+每个 finding 必须包含：
+
+- 优先级：`P0` 阻断性事故，`P1` 高风险，`P2` 应修问题，`P3` 低风险改进；
+- 精确文件和尽可能小的行范围；
+- 哪种输入、状态或环境会触发；
+- 实际影响以及为何由本次变更造成；
+- 最小修复方向，不要求作者猜测意图。
+
+如果证据不足，先检查或提问，不把可能性写成确定缺陷。合并同一根因的重复评论。
+
+## 输出格式
+
+先列 findings，按优先级排序；然后给出假设或未决问题；最后给出简短摘要和验证缺口。如果没有可执行 finding，明确写“未发现可执行问题”，但仍说明审查范围和剩余测试风险。
+
+```markdown
+### [P1] 标题
+- 位置：`path/to/file:line`
+- 触发：
+- 影响：
+- 建议：
+```
+
+## 完成标准
+
+- 审查覆盖了完整目标变更与必要上下文。
+- 每个 finding 都可复现、可定位且可执行。
+- 测试充分性和未验证风险被如实说明。
+- 没有用大量风格意见淹没真实风险。
+
+## 反模式
+
+- 不要只总结代码而不判断风险。
+- 不要对未改动的历史问题进行无边界审计。
+- 不要报告静态工具已经可靠处理且没有额外影响的噪音。
+- 不要声称某测试通过，除非有实际运行证据。
+- 不要因作者是 AI 或人类而改变证据标准。
+- 不要无差别启动全部 specialist，造成重复评论和额外成本。

package/skills/code-review/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Code Review"
+  short_description: "基于正确性、风险、测试充分性以及架构边界审查代码变更"
+  default_prompt: "请使用 $code-review 审查当前变更，优先报告可执行的问题、证据和风险。"
+policy:
+  allow_implicit_invocation: true