@kodax-ai/kodax 0.7.97-alpha.9 → 0.7.97-beta.2

package/dist/artifacts/skills/artifact-review/SKILL.md

@@ -1,16 +1,53 @@
 ---
 name: artifact-review
-description: Author, import, repair and visually review PPTX with the optional Artifact SDK and require current evidence for other visual tasks.
+description: Use already registered Artifact tools to create/edit PPTX or render and inspect supported PPTX, PDF, DOCX and image artifacts. Apply this adapter when the task uses artifact_* tools; use visual-review for general visual methods, websites, video or unsupported formats.
 ---
 
-Use artifact_capabilities to inspect runtime preparation. If Chromium is missing, artifact_prepare installs the pinned runtime through normal managed permissions. Use artifact_create/open/edit/export for PPTX content and artifact_render for current exported pixels. Geometry is in inches. Editing requires object IDs and the current sourceHash; output is always a new file.
+# Artifact tool adapter
 
-Review actual returned images. `ready` means evidence is prepared, never visual approval. Check every required page in batches of at most four. Look for clipping, overlap, missing images, wrong alignment, unreadable text and rendering differences. After repair, render the new output; old-source evidence cannot approve a new revision. Report path, hash, page coverage and remaining limitations.
+## Available tools and preparation
 
-Lightweight rendering needs compatible Chromium, not PowerPoint or LibreOffice. Missing dependencies, unsupported objects, missing fonts/resources, animations and transitions remain unverified for affected requirements. LibreOffice is optional static conversion; static pixels never verify animation.
+Use the current registered tool catalog and artifact_capabilities. When runtime
+preparation is needed, use artifact_prepare within the task's existing authorization
+and normal managed Host permissions. If preparation is denied or unavailable,
+report the affected scope as unverified and continue useful checks. Installation
+outside that managed mechanism needs separate authorization. Missing tools do not
+authorize registering a new adapter, expanding access or inventing a tool result.
 
-Use artifact_open for actual format/source identity. artifact_render supports PPTX/PDF/DOCX pages and PNG/JPEG/WebP/SVG pixels. DOCX pagination belongs to the render layout; its lightweight candidate always retains unverified Word/WPS fidelity. It does not require LibreOffice. Native PDF records each page's actual dimensions and rotation. artifact_read_evidence checks returned source/dependencies, raster provenance, hash and geometry before delivering the PNG.
+Use visual-review for the general evidence method. This Skill supplies Artifact
+parameters and format limits; avoid repeating a second full review process.
 
-artifact_capture requires kind-matched locators: static region; paginated page; interactive target/state/viewport/sequence; temporal time. Local HTML supports only loaded state and sequence 0 at the requested viewport; native/live surfaces require their existing authorized owner. SVG temporal capture samples actual SMIL seconds, not CSS/script animation. Spreadsheet native display/calculation, video/GIF/audio, EPUB and 3D/CAD remain unsupported by this default runtime. Use existing authorized tools when present and state actual coverage; never fabricate states, continuous coverage or a pass when adapter, vision or evidence is missing.
+## Author and edit
 
-The main agent owns repair. If independent review is required, a static reviewer receives frozen pixels and requirements with read-only tools. Interactive testing needs narrowly authorized interaction tools; keep readOnly policy. Rendering uses normal KodaX managed permissions, sandbox, cancellation and settlement. Do not create a verifier daemon, notifications or configuration.
+Use artifact_create/open/edit/export for supported PPTX work. Geometry is in inches;
+edits require object IDs and the current sourceHash. Output is a new file. Respect
+review-only requests. Use artifact_open to establish actual format and source identity.
+
+## Render and inspect
+
+artifact_render supports PPTX/PDF/DOCX pages and PNG/JPEG/WebP/SVG pixels. Inspect
+actual returned images, at most four pages per batch. `ready` means evidence is
+prepared, never visual approval. Check clipping, overlap, missing resources,
+alignment and legibility. After edits, render the new source; old evidence cannot
+approve a new revision. Report source hash, actual coverage and unverified scope.
+
+artifact_read_evidence validates source/dependencies, raster provenance, hash and
+geometry before returning PNG evidence. artifact_capture uses kind-matched locators:
+static region; paginated page; interactive target/state/viewport/sequence; temporal
+time. A receipt or image path does not establish that pixels were inspected.
+
+## Limits and fallback
+
+Lightweight rendering uses compatible Chromium, not PowerPoint or LibreOffice.
+DOCX lightweight pagination remains unverified for Word/WPS fidelity. Native PDF
+retains each page's dimensions and rotation. Missing fonts/resources and unsupported
+objects remain unverified for affected requirements; optional static conversion
+cannot verify animation or transitions.
+
+Local HTML capture supports loaded state and sequence 0 at the requested viewport.
+Native/live surfaces need their existing authorized owner. SVG temporal capture
+samples actual SMIL seconds, not CSS/script animation. Spreadsheet native display
+and calculation, video/GIF/audio, EPUB and 3D/CAD are unsupported by this default
+adapter. Use existing authorized tools when available; report the exact remaining
+gap without fabricating states or continuous coverage. Keep normal sandbox,
+cancellation and settlement; no verifier daemon or separate completion API.

package/dist/builtin/code-review/SKILL.md

@@ -2,7 +2,7 @@
 name: code-review
 description: 审查代码、diff、提交或当前 git 改动，重点发现 bug、行为回归、边界条件遗漏、安全风险、性能问题和缺失测试。当用户提到 code review、review 这段代码、帮我看看改动有没有问题、审查 PR/提交时使用；不要用于单纯解释代码或直接实现需求。
 user-invocable: true
-allowed-tools: "Read, Grep, Glob, Bash(npm:*, node:*, npx:*)"
+allowed-tools: "Read, Grep, Glob, Bash(git status, git status *, git diff, git diff *, git log, git log *, git show, git show *, git ls-files, git ls-files *, git rev-parse, git rev-parse *, git ls-tree, git ls-tree *, git blame, git blame *, git cat-file *, npm *, node *, npx *)"
 argument-hint: "[file-or-directory]"
 compatibility: "Works best in a git repository or when the review target is provided explicitly."
 ---
@@ -14,8 +14,10 @@ compatibility: "Works best in a git repository or when the review target is prov
 ## 范围判定
 
 - 如果提供了 `$ARGUMENTS`，审查对应文件、目录、diff 或提交范围。
-- 如果没有提供参数，优先审查当前 git 改动；如果不在 git 仓库中，就明确说明缺少范围并请求更具体的目标。
+- 如果没有提供参数，先用 git status 清点任务相关的已暂存、未暂存与未跟踪文件，分别读取 staged/unstaged diff，并用 Read 检查相关未跟踪文件。一次 git diff 不代表审完全部改动。
+- PR/提交范围使用明确基线，只审该范围，不混入当前工作区的无关修改；不在仓库且没有目标时才补齐范围。
 - 在下结论前，尽量查看相邻实现、调用方、测试和相关配置，避免脱离上下文的误报。
+- review-only 只报告，不编辑实现或暂存文件。测试前查看脚本副作用，沿用宿主授权；不为审查自动运行安装、--fix 或破坏性 Git 命令。
 
 ## 审查重点
 
@@ -39,23 +41,9 @@ compatibility: "Works best in a git repository or when the review target is prov
   - 具体文件和行号
   - 为什么这是问题，可能造成什么影响
   - 建议的修复方向
-- 如果没有发现值得报告的问题，明确写 `No findings.`，然后补充剩余风险或测试空白。
+- 如果没有发现值得报告的问题，明确写 `No findings.`，并说明实际覆盖和未验证范围；不能暗示未运行的测试已通过。
 - 需要时再追加 `## Open Questions` 或 `## Change Summary`，但不要用总体打分或“亮点”冲淡问题。
 
-## 输出模板
-
-```markdown
-## Findings
-- [High] Title — `path/to/file.ts:42`
-  Why it matters and what to change.
-
-## Open Questions
-- Optional clarification or assumption.
-
-## Change Summary
-- Optional short summary only after findings.
-```
-
 ## 使用示例
 
 - `/code-review src/auth.ts` - 审查单个文件

package/dist/builtin/git-workflow/SKILL.md

@@ -2,10 +2,9 @@
 name: git-workflow
 description: 执行明确的 Git 操作，例如查看状态、提交、建分支、push、stash 或创建 PR。只有在用户明确要求实际执行这些 Git 操作时才使用；不要用于单纯解释 Git 概念或讨论策略。
 user-invocable: true
-disable-model-invocation: true
-allowed-tools: "Read, Grep, Glob, Bash(git:*, gh:*)"
+allowed-tools: "Read, Grep, Glob, Bash(git *, gh *, node *)"
 argument-hint: "[status|commit|branch|push|pr|stash] [args]"
-compatibility: "Requires a Git repository. Pull request creation works best when GitHub CLI (gh) is installed and authenticated."
+compatibility: "Requires Git for local operations. Remote actions use an available, authorized hosting tool and the repository's authentication rules."
 ---
 
 # Git Workflow Skill
@@ -15,8 +14,8 @@ compatibility: "Requires a Git repository. Pull request creation works best when
 ## 总流程
 
 1. 先检查仓库状态，例如 `git status --short --branch`，必要时补充 `git diff --stat`、`git diff --cached`、`git log --oneline`。
-2. 根据第一个参数判断操作类型；如果用户表达明确，就直接执行对应流程。
-3. 对会改写历史、删除数据或影响远程分支的操作，先说明风险；只有在用户明确要求时才继续。
+2. 从自然语言或参数确定操作类型与文件范围；沿用当前会话已有的授权，明确的 commit/push 请求直接推进。
+3. 历史改写、强推或删除须有对应授权；普通已授权提交和推送不重复确认。宿主授权与执行策略始终生效。
 4. 所有 Git 命令都使用非交互方式执行。
 
 ## 支持的操作
@@ -41,7 +40,7 @@ compatibility: "Requires a Git repository. Pull request creation works best when
 
 ### branch
 - `create` / `new`: 创建新分支。除非用户指定，否则遵循仓库已有命名风格。
-- `switch` / `checkout`: 切换分支前，先检查当前工作区是否干净。
+- `switch` / `checkout`: 先检查工作区；只有会覆盖或混入当前改动时才处理冲突，保留无关修改。
 - `list`: 列出本地/远程分支，并在有帮助时指出当前分支。
 - `delete` / `remove`: 仅在删除条件安全且用户请求明确时执行。
 
@@ -53,7 +52,9 @@ compatibility: "Requires a Git repository. Pull request creation works best when
 ### pr
 - 检查当前分支是否已 push，必要时先推送。
 - 基于 diff 和提交历史生成简洁的 PR 标题与描述。
-- 使用 `gh pr create` 前确认 `gh` 可用且已认证；否则清楚说明阻塞点。
+- 使用当前宿主和 Skill 策略允许的、已经授权的 Git 托管连接器、CLI 或 API；遵守仓库认证约定，不回显凭据、不主动切换认证或交互登录。
+- 没有可用的 `gh` 时，声明允许经 Node 调用托管 API；仅为当前已授权的 Git 操作使用现有凭据，仍通过普通 Host 授权与沙箱。不要假定任意连接器工具都已被当前 Skill 策略放行。
+- `gh` 可用时可用 `gh pr create`，但它不是所有宿主的前提。没有允许的创建路径时，保留已完成的提交与推送，说明缺少的能力。
 
 ### stash
 - `save`: 有上下文时附带说明性消息。
@@ -65,7 +66,7 @@ compatibility: "Requires a Git repository. Pull request creation works best when
 
 - 不要使用 `git reset --hard`、`git checkout --`、`git clean -fd`、`git commit --amend`、强推、历史改写等危险操作，除非用户明确要求。
 - 不要回滚、覆盖或丢弃用户的无关改动。
-- 遇到脏工作区、冲突、无 upstream、权限不足、缺少 `gh` 等阻塞时，要先解释现状再继续。
+- 按实际操作处理冲突、无 upstream 或权限不足；脏工作区及缺少 `gh` 本身不阻塞所有 Git 任务。
 - 对“合并分支”“rebase”“cherry-pick”等这里没有明确定义的操作，如果用户明确提出，可以按 Git 最佳实践执行，但要先说明风险和计划。
 
 ## 汇报方式

package/dist/builtin/skill-creator/SKILL.md

@@ -1,127 +1,57 @@
 ---
 name: skill-creator
-description: 创建、重写、迁移和优化 KodaX/Agent Skills。当用户想新建 skill、把外部 skill 迁移到 KodaX、改进触发描述、整理 supporting files、设计评测用例、补齐 grading/benchmark/review/comparison 流程或验证 skill 结构时使用。即使用户没有明确说“skill”，只要目标是在沉淀可复用的代理工作流、提示词或脚本能力，也应该使用这个 skill。
+description: 创建、修改、迁移、验证或打包 Skill，或优化其描述与评测时使用；也用于把已有工作流沉淀成可反复调用的代理能力。不用于普通一次性写作、代码实现或仅使用某项既有 Skill 完成业务任务。
 user-invocable: true
-allowed-tools: "Read, Grep, Glob, Write, Edit, Bash(node:*, npm:*, npx:*)"
+allowed-tools: "Read, Grep, Glob, Write, Edit, Bash(node *, npm *, npx *)"
 argument-hint: "[skill-name-or-task]"
-compatibility: "Optimized for KodaX and Agent Skills style directories. Bundled helper scripts use Node.js instead of Python."
+compatibility: "KodaX/Agent Skills directories; helpers are plain Node ESM. Model evaluation needs a separately configured, authorized SDK Provider."
 ---
 
 # Skill Creator
 
-把用户的工作流整理成一个可维护、可触发、可评估的 skill。优先适配 KodaX 的 skill 运行方式，而不是逐字复制外部平台的实现。
+复用当前会话已有的目标、样例、范围和授权，区分用户要创建/修改、验证、打包还是
+评测。仅补齐会改变结果的缺失信息；小改描述不必扩展成完整模型评测。
 
-## 何时使用
+下面的 scripts/ 与 references/ 都相对本 Skill 目录。保留目标工作区语境，执行
+helper 时给脚本路径和目标路径，不假定当前目录就是 Skill 目录。
 
-- 用户要新建 skill，或把一次对话里的工作流沉淀成 skill。
-- 用户要改已有 skill 的触发描述、结构、supporting files 或提示词。
-- 用户要把 Claude / Anthropic / 其他平台的 skill 移植到 KodaX。
-- 用户要为 skill 设计测试提示、评估结构、人工 review 流程或 benchmark 汇总。
+## 创建、修改与迁移
 
-## 工作方式
+- 新建时先起草，或用 `node scripts/init-skill.js <name> --path <skills-dir>` 初始化，
+  再按真实任务填写；已有 Skill 在原目录做必要修改。验证-only 只报告问题，不改文件。
+- description 写任务与调用边界；默认开放模型发现。只有用户要求显式调用时才设
+  `disable-model-invocation: true`。每个已启用 Skill 仍接受 `/<name>` 和 `/skill:<name>`；
+  `user-invocable` 是兼容字段，不是执行权限。
+- SKILL.md 保留共同方法和分支入口。机械步骤放 scripts/，分支细节放 references/，
+  模板放 assets/；只有实际需要时才新增支持文件。内置脚本使用 plain Node ESM `.js`，
+  `.ts` 需要相应构建链，不能假定被直接复制的 TypeScript 可以执行。
+- allowed-tools 遵守当前宿主契约，例如 `Bash(npm *, node *)` 匹配完整命令文本，
+  不是 `npm:*` 冒号前缀。Skill 声明不会授予宿主权限，仍执行原有授权与沙箱检查。
+- 移植时核对工具、路径、依赖和事件语义，保留真正可用的行为。记录可核实的来源
+  URL、revision、许可与改写范围；未核实的来源明确标未知，不追认一个上游版本。
 
-### 1. 先收敛目标
+完成后用 `node scripts/quick-validate.js <skill-dir>` 做结构检查，并核对正例、相邻
+任务反例及支持文件引用。结构通过不等于真实触发或脚本执行已验证。交付实际修改
+和证据；工具不足时继续有依据的起草/检查，明确未运行部分。
 
-先明确四件事：
-1. 这个 skill 要解决什么任务。
-2. 什么时候应该触发，什么时候不应该触发。
-3. 输出是什么形态。
-4. 是否需要评测和人工 review。
+## 打包与分享
 
-如果用户已经给了样例对话、提示词或外部 skill 仓库，先从已有材料里提炼，不要重复让用户描述。
+`node scripts/package-skill.js <skill-dir> --output <file.skill>` 校验并生成归档。
+用户只要分享包时，交付归档和验证结果即可，不默认安装到个人技能库。
 
-### 2. 适配 KodaX，而不是照抄外部 skill
+需要验证安装链路时，用临时隔离目录：
+`node scripts/install-skill.js <file.skill> --dest <isolated-dir>`，再检查解包内容和引用。
+仅在任务要求真实安装时写入用户指定目录，沿用已有授权；不以 --force 绕过同名冲突。
 
-迁移外部 skill 时，拆成三类：
-- 可直接复用：SKILL.md 的思路、评测结构、参考文档组织方式。
-- 需要改写：路径约定、触发描述、支持的 frontmatter 字段、命令示例。
-- 不要硬搬：强依赖 Claude Code、`claude -p`、Cowork、Python stdlib 或专有事件流的部分。
+## 评测或优化描述
 
-如果外部 skill 依赖特定宿主能力，优先改成 KodaX 当前能承接的手工流程或 Node 工具，而不是留下名不副实的说明。
+先读 [评测方法与命令](references/evaluation.md)，只执行需要的分支。
 
-### 3. 写 KodaX 风格的 skill
+- quick-validate 是结构检查；run-trigger-eval 是单条描述的**语义筛查**，不是实际触发率。
+- 真实触发需使用实际注册、可见的完整 catalog 和真实 skill 工具定义，记录是否真的
+  调用了 skill；包含自然语言正例和相邻任务反例，不能以判断题分数代替调用证据。
+- run-eval 是独立 SDK 执行，必须明确 Provider、model、cwd、输入/输出路径与预算；
+  不自动继承 Space 当前会话凭据或工具。没有已授权模型能力时仍可完成静态工作。
 
-- `description` 要写“做什么 + 什么时候用”，并稍微主动一点，避免 under-trigger。
-- `SKILL.md` 负责主流程，不要把所有细节都塞进去。
-- 重复性、机械性、易出错的步骤，放到 `scripts/`。
-- 大块参考资料放到 `references/`。
-- 模板或静态文件放到 `assets/`。
-- 如果某个专家流程只服务这个 skill，可以放进 `agents/`，但先把它当私有 contract，不要自动上升成全局产品概念。
-- `description` 同时决定模型发现。自然语言只会看到未设置 `disable-model-invocation: true` 的 name/description。
-- 需要只在显式 slash 后加载时，写 `disable-model-invocation: true`。这只关闭模型 catalog 与模型 `skill` 工具。
-- 每个已启用 Skill 都接受 `/<name>` 和 `/skill:<name>`。
-- token 可在 query 头部或中间。后续文本是 Skill 参数。
-- `user-invocable` 只保留解析兼容。不要把它当成执行权限：宿主忽略该字段后，作者会误以为 `false` 能禁止 slash/SDK 调用。
-
-### 4. Bundled scripts 默认用 Node.js
-
-KodaX 当前会把 builtin skill 目录直接复制到 `dist/`。因此：
-
-- skill 内的可执行脚本默认使用 plain Node ESM `.js`。
-- 只有在你同时修改了构建链、确保脚本会被编译时，才在 skill 内使用 `.ts`。
-- 如果用户只是想“改成 node/typescript”，默认先落成 Node `.js`，这是最稳妥的内建交付方式。
-
-### 5. 先验证，再评估
-
-起草完成后，优先按下面的顺序推进：
-
-1. 用 `node scripts/quick-validate.js <skill-dir>` 做结构检查。
-2. 如果还没有 skill 骨架，用 `node scripts/init-skill.js <skill-name> --path <skills-dir>` 初始化。
-3. 设计 2 到 3 个真实用户会说的测试提示。
-4. 如果要跑端到端 skill eval，把提示整理到 `evals/evals.json`，再用 `node scripts/run-eval.js --skill-path <skill-dir> --evals <evals.json> --workspace <iteration-dir>` 生成 `with_skill` / `without_skill` workspace。
-5. 如果要补第 3 阶段的专家评测流，先用 `node scripts/grade-evals.js <workspace>` 生成 `grading.json`，再用 `node scripts/aggregate-benchmark.js <workspace> --skill-name <name>` 聚合 benchmark，用 `node scripts/analyze-benchmark.js <workspace>` 产出分析结论，用 `node scripts/compare-runs.js <workspace>` 做 blind comparison。
-6. 如果要评估 description 的触发效果，再用 `node scripts/run-trigger-eval.js --skill-path <skill-dir> --evals <evals.json>` 跑一轮触发评测。
-7. 如果要迭代 description，可以用 `node scripts/improve-description.js --skill-path <skill-dir> --eval-results <results.json>` 生成候选描述，或用 `node scripts/run-loop.js --skill-path <skill-dir> --evals <evals.json> --workspace <workspace-dir>` 跑多轮优化。
-8. 如果需要人工 review，把运行结果整理到 workspace，再用 `node scripts/generate-review.js <workspace> --static <html-file>` 或本地服务模式生成 review 页面。
-9. 如果要分享给别的 KodaX/Agent Skills 风格环境，用 `node scripts/package-skill.js <skill-dir>` 打包，再用 `node scripts/install-skill.js <archive-or-dir>` 验证安装链路。
-
-## 评估建议
-
-- 客观任务：优先写断言、grading 结构和 benchmark。
-- 主观任务：优先给人类 review 页面，再用 comparator 做 blind comparison，而不是强行只看单一分数。
-- 描述优化：先整理误触发/漏触发样例，再跑 `run-trigger-eval`，需要时再用 `improve-description` 或 `run-loop` 迭代。
-- 如果需要专家提示词，把 `agents/grader.md`、`agents/analyzer.md`、`agents/comparator.md` 当作私有专家 contract 使用，不要先把它们产品化成通用 swarm 概念。
-
-## 输出要求
-
-默认给出：
-- 修改后的 `SKILL.md`
-- 新增或更新的 supporting files
-- 简短的 trigger/eval 样例
-- 还没覆盖的风险或后续建议
-
-如果用户是在移植外部 skill，还要额外说明：
-- 哪些能力已经迁移
-- 哪些能力因为宿主差异被删减或改写
-- 哪些部分后续值得继续产品化
-
-## 可用工具
-
-- `agents/grader.md`：给 `grade-evals.js` 使用的专家评分契约。
-- `agents/analyzer.md`：给 `analyze-benchmark.js` 使用的分析契约。
-- `agents/comparator.md`：给 `compare-runs.js` 使用的盲比契约。
-- `scripts/quick-validate.js`：校验 skill 结构和 frontmatter。
-- `scripts/init-skill.js`：初始化一个新的 skill 骨架，并可一并创建 `evals/evals.json`。
-- `scripts/run-eval.js`：运行端到端 skill eval，生成 `with_skill` / `without_skill` workspace 结果。
-- `scripts/grade-evals.js`：消费 workspace，给每个 run 生成 `grading.json` 与 `grading-summary.json`。
-- `scripts/aggregate-benchmark.js`：聚合 `grading.json` / `timing.json` 生成 `benchmark.json` 与 `benchmark.md`。
-- `scripts/analyze-benchmark.js`：基于 benchmark 和 grading 产出 `analysis.json` 与 `analysis.md`。
-- `scripts/compare-runs.js`：对两个 config 做 blind comparison，生成 `comparison.json` 与 `comparison.md`。
-- `scripts/run-trigger-eval.js`：对 description 做 KodaX 原生触发评测，检查误触发和漏触发。
-- `scripts/improve-description.js`：基于评测结果生成新的 description 候选。
-- `scripts/run-loop.js`：把触发评测和 description 改写串成可重复的多轮优化流程。
-- `scripts/generate-review.js`：把 workspace 结果生成静态或本地服务版 HTML review 页面。
-- `scripts/package-skill.js`：把 skill 目录打成 `.skill` 归档，便于分享与分发。
-- `scripts/install-skill.js`：把 `.skill` 归档或目录安装到目标 skills 目录。
-- `references/schemas.md`：评测相关 JSON 结构参考。
-
-这里的 description eval、loop、grading、analysis、comparison 和 packaging 都已经是 KodaX 原生实现，不再依赖 Anthropic 的 Python 脚本或 Claude Code 专有宿主能力。
-
-## 使用示例
-
-- `/skill:skill-creator 把这个 Claude skill 迁移成 KodaX builtin`
-- `/skill:skill-creator 新建一个 release-notes skill`
-- `/skill:skill-creator 优化现有 skill 的 description 和 evals`
-- `/skill:skill-creator 给这个 skill 补 trigger eval、grading、benchmark、comparison 和 review 流程`
-- `/skill:skill-creator 把这个 skill 打成可分享的 .skill 包`
-- `/skill:skill-creator 初始化一个新 skill 骨架并生成 eval workspace`
+需要运行结果评审时再加载 agents/grader.md、agents/analyzer.md 或 agents/comparator.md；
+它们是该流程的私有契约，不需要创建通用 swarm 或独立后台任务。

package/dist/builtin/skill-creator/references/evaluation.md

@@ -0,0 +1,50 @@
+# 按证据选择评测
+
+## 结构与描述语义筛查
+
+`node scripts/quick-validate.js <skill-dir>` 只检查结构/frontmatter。
+`node scripts/run-trigger-eval.js --skill-path <skill-dir> --evals <cases.json> --provider <provider> --model <model> --runs-per-query 1`
+让模型仅根据一条 name/description/query 判断“应该使用吗”。输出的 precision/recall
+是描述判断统计，没有竞争 catalog、真实工具调用或可见性执行证据；metadata 会标明
+这是 description_semantic_screening，以及该 Skill 是否开放模型目录。
+
+improve-description.js 根据结果生成候选；run-loop.js 串联筛查与改写。按需要限定
+--max-iterations、--runs-per-query；只有明确要求写回时用 --write-best。改了评分器时
+重读已有 raw，不能为了得到好分数无限重跑。不要把这些脚本的分数写成产品召回率。
+
+## 真实触发
+
+用产品相同的完整 Skill catalog、可见性和工具定义观察自然语言请求后的实际
+skill 调用。保留请求、目录/工具的版本、原始响应、调用参数和未调用证据。覆盖
+正例、邻近 Skill 的 near-miss、无关请求；否定回答中提到技能名不等于调用它。
+描述被隐藏、工具未提供或环境不同的实验，不能证明生产模型发现正确。
+
+## 执行 smoke
+
+run-eval.js 通过公开 Skill SDK 加载/展开内容，使用独立 SDK 运行 with_skill /
+without_skill；它不是重放当前 Space 会话。先明确当前环境中已授权的 provider/model
+与凭据来源、输入文件和隔离 cwd；不要假定会继承产品会话的凭据、工具或工作目录。
+
+示例（脚本路径相对本 Skill，路径含空格时按当前 Shell 引号规则处理）：
+
+```text
+node scripts/run-eval.js --skill-path <skill-dir> --evals <evals.json> --workspace <iteration-dir> --provider <provider> --model <model> --cwd <isolated-workspace> --runs 1 --max-iter 6
+```
+
+先用少量 case 验证脚本和任务有效。执行 smoke 与描述筛查、真实选择是不同证据，
+端到端自由执行不能独自支持提示词优劣结论。冻结 case/config/runs/迭代上限，统计
+实际调用与 token/费用；max-iter 不等于物理 Provider 请求上限。遵守当前项目的
+预算与原始输出保留约定，超时与失败留存，不能盲目追加请求。
+
+## 需要时再评审运行结果
+
+- `grade-evals.js <workspace> --provider <provider> --model <model>` 读取各 run，写 grading。
+- `aggregate-benchmark.js <workspace> --skill-name <name>` 聚合 grading/timing，不调用模型。
+- `analyze-benchmark.js <workspace> --provider <provider> --model <model>` 形成有局限性说明的分析。
+- `compare-runs.js <workspace> --provider <provider> --model <model>` 盲比两个 config。
+- `generate-review.js <workspace> --static <review.html>` 生成静态人工评审页。
+
+按任务加载 agents/ 中的对应契约和 [schemas.md](schemas.md)。报告任务有效性、差异、
+失败归因、未验证范围及建议，不能用单一总分替代判断。若只做打包或静态修改，
+不运行这些独立模型流程。当前 helper 为 KodaX 本地维护；没有锁定的外部版本时，
+不要用外部最新代码覆盖当前宿主适配或声称已完成上游同步。

package/dist/builtin/skill-creator/scripts/analyze-benchmark.d.ts

@@ -6,6 +6,8 @@ export interface AnalyzeBenchmarkOptions {
   skillName?: string;
   provider?: string;
   model?: string;
+  effort?: string;
+  /** @deprecated Use effort. */
   reasoningMode?: string;
   maxIter?: number;
   cwd?: string;

package/dist/builtin/skill-creator/scripts/analyze-benchmark.js

@@ -123,8 +123,8 @@ async function defaultRunAnalyst(prompt, options) {
       provider: options.provider ?? 'anthropic',
       model: options.model,
       maxIter: options.maxIter ?? 20,
-      reasoningMode: options.reasoningMode ?? 'balanced',
-      thinking: options.reasoningMode ? options.reasoningMode !== 'off' : true,
+      effort: options.effort ?? (options.reasoningMode ? undefined : 'medium'),
+      reasoningMode: options.reasoningMode,
       context: {
         gitRoot: path.resolve(options.cwd ?? options.workspaceDir ?? process.cwd()),
       },
@@ -232,7 +232,8 @@ function parseArgs(argv) {
     skillName: undefined,
     provider: 'anthropic',
     model: undefined,
-    reasoningMode: 'balanced',
+    effort: undefined,
+    reasoningMode: undefined,
     maxIter: 20,
     cwd: process.cwd(),
   };
@@ -251,6 +252,8 @@ function parseArgs(argv) {
       args.provider = argv[++index];
     } else if (token === '--model' && argv[index + 1]) {
       args.model = argv[++index];
+    } else if (token === '--effort' && argv[index + 1]) {
+      args.effort = argv[++index];
     } else if (token === '--reasoning' && argv[index + 1]) {
       args.reasoningMode = argv[++index];
     } else if (token === '--max-iter' && argv[index + 1]) {

package/dist/builtin/skill-creator/scripts/compare-runs.d.ts

@@ -6,6 +6,8 @@ export interface CompareWorkspaceOptions {
   markdownPath?: string;
   provider?: string;
   model?: string;
+  effort?: string;
+  /** @deprecated Use effort. */
   reasoningMode?: string;
   maxIter?: number;
   maxPairs?: number;

package/dist/builtin/skill-creator/scripts/compare-runs.js

@@ -124,8 +124,8 @@ async function defaultRunComparator(prompt, options) {
       provider: options.provider ?? 'anthropic',
       model: options.model,
       maxIter: options.maxIter ?? 20,
-      reasoningMode: options.reasoningMode ?? 'balanced',
-      thinking: options.reasoningMode ? options.reasoningMode !== 'off' : true,
+      effort: options.effort ?? (options.reasoningMode ? undefined : 'medium'),
+      reasoningMode: options.reasoningMode,
       context: {
         gitRoot: path.resolve(options.cwd ?? options.workspaceDir ?? process.cwd()),
       },
@@ -273,7 +273,8 @@ function parseArgs(argv) {
     markdownPath: undefined,
     provider: 'anthropic',
     model: undefined,
-    reasoningMode: 'balanced',
+    effort: undefined,
+    reasoningMode: undefined,
     maxIter: 20,
     maxPairs: undefined,
     cwd: process.cwd(),
@@ -293,6 +294,8 @@ function parseArgs(argv) {
       args.provider = argv[++index];
     } else if (token === '--model' && argv[index + 1]) {
       args.model = argv[++index];
+    } else if (token === '--effort' && argv[index + 1]) {
+      args.effort = argv[++index];
     } else if (token === '--reasoning' && argv[index + 1]) {
       args.reasoningMode = argv[++index];
     } else if (token === '--max-iter' && argv[index + 1]) {

package/dist/builtin/skill-creator/scripts/grade-evals.d.ts

@@ -2,6 +2,8 @@ export interface GradeWorkspaceOptions {
   workspaceDir: string;
   provider?: string;
   model?: string;
+  effort?: string;
+  /** @deprecated Use effort. */
   reasoningMode?: string;
   maxIter?: number;
   cwd?: string;

package/dist/builtin/skill-creator/scripts/grade-evals.js

@@ -216,8 +216,8 @@ async function defaultRunJudge(prompt, options) {
       provider: options.provider ?? 'anthropic',
       model: options.model,
       maxIter: options.maxIter ?? 20,
-      reasoningMode: options.reasoningMode ?? 'balanced',
-      thinking: options.reasoningMode ? options.reasoningMode !== 'off' : true,
+      effort: options.effort ?? (options.reasoningMode ? undefined : 'medium'),
+      reasoningMode: options.reasoningMode,
       context: {
         gitRoot: path.resolve(options.cwd ?? options.workspaceDir ?? process.cwd()),
       },
@@ -351,7 +351,8 @@ function parseArgs(argv) {
     workspaceDir: argv[2] ?? '',
     provider: 'anthropic',
     model: undefined,
-    reasoningMode: 'balanced',
+    effort: undefined,
+    reasoningMode: undefined,
     maxIter: 20,
     cwd: process.cwd(),
     overwrite: false,
@@ -364,6 +365,8 @@ function parseArgs(argv) {
       args.provider = argv[++index];
     } else if (token === '--model' && argv[index + 1]) {
       args.model = argv[++index];
+    } else if (token === '--effort' && argv[index + 1]) {
+      args.effort = argv[++index];
     } else if (token === '--reasoning' && argv[index + 1]) {
       args.reasoningMode = argv[++index];
     } else if (token === '--max-iter' && argv[index + 1]) {

package/dist/builtin/skill-creator/scripts/run-eval.js

@@ -3,9 +3,7 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { expandSkillForLLM } from '../../../skill-expander.js';
-import { loadFullSkill } from '../../../skill-loader.js';
-import { ensureDirectory, loadKodaXSDK } from './utils.js';
+import { ensureDirectory, loadKodaXSDK, loadKodaXSkills } from './utils.js';
 
 function normalizeAssertion(assertion) {
   if (typeof assertion === 'string') {
@@ -124,6 +122,7 @@ async function defaultRunAgent(prompt, options) {
 
 async function prepareConfigPrompt(configName, skill, taskPrompt, options) {
   if (configName === 'with_skill') {
+    const { expandSkillForLLM } = await loadKodaXSkills();
     const expanded = await expandSkillForLLM(
       skill,
       taskPrompt,
@@ -196,6 +195,7 @@ export async function runEvalWorkspace(
   options,
   runner = defaultRunAgent
 ) {
+  const { loadFullSkill } = await loadKodaXSkills();
   const skill = await loadFullSkill(path.resolve(options.skillPath), 'user');
   if (!skill) {
     throw new Error(`Failed to load skill from ${options.skillPath}`);

package/dist/builtin/skill-creator/scripts/run-loop.js

@@ -3,7 +3,7 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { loadSkill, pathExists, writeSkill } from './utils.js';
+import { ensureDirectory, loadSkill, pathExists, writeSkill } from './utils.js';
 import { improveDescription } from './improve-description.js';
 import { runTriggerEval } from './run-trigger-eval.js';
 
@@ -73,6 +73,7 @@ export async function runDescriptionLoop(
     ...dependencies,
   };
   const skill = await loadSkill(options.skillPath);
+  await ensureDirectory(options.workspaceDir);
   const evalFile = JSON.parse(await readFile(options.evalsPath, 'utf8'));
   const allEvals = Array.isArray(evalFile.evals) ? evalFile.evals : [];
   const { train, test } = splitEvalSet(allEvals, options.holdout, options.seed);

package/dist/builtin/skill-creator/scripts/run-trigger-eval.d.ts

@@ -33,6 +33,8 @@ export interface TriggerEvalReport {
     model?: string | null;
     runs_per_query: number;
     trigger_threshold: number;
+    evaluation_kind: 'description_semantic_screening';
+    model_catalog_visible: boolean;
     note: string;
   };
 }

package/dist/builtin/skill-creator/scripts/run-trigger-eval.js

@@ -149,7 +149,9 @@ export async function runTriggerEval(options, runner = defaultRunPrompt) {
       model: options.model ?? null,
       runs_per_query: runsPerQuery,
       trigger_threshold: threshold,
-      note: 'This is a KodaX-native description eval, not a Claude Code tool-trace replay.',
+      evaluation_kind: 'description_semantic_screening',
+      model_catalog_visible: skill.frontmatter['disable-model-invocation'] !== true,
+      note: 'Single-description semantic screening; not observed Skill tool selection from a competing catalog.',
     },
   };
 }

package/dist/builtin/skill-creator/scripts/utils.d.ts

@@ -1,3 +1,3 @@
 export declare function setKodaXSDKForSkillCreator(
-  sdk: Readonly<Record<string, unknown>>,
+  sdk: Readonly<Record<string, unknown>> | null,
 ): void;

package/dist/builtin/skill-creator/scripts/utils.js

@@ -33,6 +33,14 @@ import YAML from 'yaml';
 
 let _cachedSdk = null;
 
+/** Published single-package entry, or the standalone Agent's public Skill API. */
+export async function loadKodaXSkills() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const bundled = path.resolve(here, '../../../sdk-skills.js');
+  if (existsSync(bundled)) return import(pathToFileURL(bundled).href);
+  return import('@kodax-ai/agent/capabilities/skills');
+}
+
 export function setKodaXSDKForSkillCreator(sdk) {
   _cachedSdk = sdk;
 }