@kodax-ai/kodax-cli 0.7.38

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

@@ -0,0 +1,84 @@
+---
+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:*)"
+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."
+---
+
+# Git Workflow Skill
+
+执行 Git 工作流时，优先保证仓库安全、改动边界清晰、命令可追溯。
+
+## 总流程
+
+1. 先检查仓库状态，例如 `git status --short --branch`，必要时补充 `git diff --stat`、`git diff --cached`、`git log --oneline`。
+2. 根据第一个参数判断操作类型；如果用户表达明确，就直接执行对应流程。
+3. 对会改写历史、删除数据或影响远程分支的操作，先说明风险；只有在用户明确要求时才继续。
+4. 所有 Git 命令都使用非交互方式执行。
+
+## 支持的操作
+
+### status
+- 汇总当前分支、upstream、已暂存/未暂存/未跟踪文件，以及明显的下一步建议。
+
+### commit
+- 只暂存与当前任务直接相关的文件；不要顺手带上无关改动。
+- 如果用户没有提供 message，基于 diff 生成简洁的 Conventional Commit。
+- 优先使用 `git add <path>`，避免无差别 `git add .`，除非用户明确要求全部提交。
+- 提交前检查是否混入敏感文件或明显不该提交的产物。
+
+**Commit 模板**
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### branch
+- `create` / `new`: 创建新分支。除非用户指定，否则遵循仓库已有命名风格。
+- `switch` / `checkout`: 切换分支前，先检查当前工作区是否干净。
+- `list`: 列出本地/远程分支，并在有帮助时指出当前分支。
+- `delete` / `remove`: 仅在删除条件安全且用户请求明确时执行。
+
+### push
+- 先确认当前分支与 upstream 的关系。
+- 首次 push 或没有 upstream 时，设置合适的 upstream。
+- `--force` 或 `--force-with-lease` 只有在用户明确要求时才允许。
+
+### pr
+- 检查当前分支是否已 push，必要时先推送。
+- 基于 diff 和提交历史生成简洁的 PR 标题与描述。
+- 使用 `gh pr create` 前确认 `gh` 可用且已认证；否则清楚说明阻塞点。
+
+### stash
+- `save`: 有上下文时附带说明性消息。
+- `list`: 列出 stash，并说明最近一条的用途。
+- `pop`: 应用并删除最近 stash，若有冲突需明确报告。
+- `drop`: 仅在用户明确要求删除时执行。
+
+## 安全边界
+
+- 不要使用 `git reset --hard`、`git checkout --`、`git clean -fd`、`git commit --amend`、强推、历史改写等危险操作，除非用户明确要求。
+- 不要回滚、覆盖或丢弃用户的无关改动。
+- 遇到脏工作区、冲突、无 upstream、权限不足、缺少 `gh` 等阻塞时，要先解释现状再继续。
+- 对“合并分支”“rebase”“cherry-pick”等这里没有明确定义的操作，如果用户明确提出，可以按 Git 最佳实践执行，但要先说明风险和计划。
+
+## 汇报方式
+
+- 简洁说明执行了哪些命令、当前仓库状态变成了什么样。
+- 如果因为风险或条件不满足而没有执行，要明确说明原因和下一步建议。
+
+## 使用示例
+
+- `/git-workflow status` - 查看当前仓库状态
+- `/git-workflow commit` - 分析相关改动并提交
+- `/git-workflow commit "fix: resolve auth bug"` - 使用指定消息提交
+- `/git-workflow branch create feature/login` - 创建新分支
+- `/git-workflow push` - 推送当前分支
+- `/git-workflow pr` - 为当前分支创建 PR
+- `/git-workflow stash` - 暂存当前变更

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

@@ -0,0 +1,122 @@
+---
+name: skill-creator
+description: 创建、重写、迁移和优化 KodaX/Agent Skills。当用户想新建 skill、把外部 skill 迁移到 KodaX、改进触发描述、整理 supporting files、设计评测用例、补齐 grading/benchmark/review/comparison 流程或验证 skill 结构时使用。即使用户没有明确说“skill”，只要目标是在沉淀可复用的代理工作流、提示词或脚本能力，也应该使用这个 skill。
+user-invocable: true
+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."
+---
+
+# Skill Creator
+
+把用户的工作流整理成一个可维护、可触发、可评估的 skill。优先适配 KodaX 的 skill 运行方式，而不是逐字复制外部平台的实现。
+
+## 何时使用
+
+- 用户要新建 skill，或把一次对话里的工作流沉淀成 skill。
+- 用户要改已有 skill 的触发描述、结构、supporting files 或提示词。
+- 用户要把 Claude / Anthropic / 其他平台的 skill 移植到 KodaX。
+- 用户要为 skill 设计测试提示、评估结构、人工 review 流程或 benchmark 汇总。
+
+## 工作方式
+
+### 1. 先收敛目标
+
+先明确四件事：
+1. 这个 skill 要解决什么任务。
+2. 什么时候应该触发，什么时候不应该触发。
+3. 输出是什么形态。
+4. 是否需要评测和人工 review。
+
+如果用户已经给了样例对话、提示词或外部 skill 仓库，先从已有材料里提炼，不要重复让用户描述。
+
+### 2. 适配 KodaX，而不是照抄外部 skill
+
+迁移外部 skill 时，拆成三类：
+- 可直接复用：SKILL.md 的思路、评测结构、参考文档组织方式。
+- 需要改写：路径约定、触发描述、支持的 frontmatter 字段、命令示例。
+- 不要硬搬：强依赖 Claude Code、`claude -p`、Cowork、Python stdlib 或专有事件流的部分。
+
+如果外部 skill 依赖特定宿主能力，优先改成 KodaX 当前能承接的手工流程或 Node 工具，而不是留下名不副实的说明。
+
+### 3. 写 KodaX 风格的 skill
+
+- `description` 要写“做什么 + 什么时候用”，并稍微主动一点，避免 under-trigger。
+- `SKILL.md` 负责主流程，不要把所有细节都塞进去。
+- 重复性、机械性、易出错的步骤，放到 `scripts/`。
+- 大块参考资料放到 `references/`。
+- 模板或静态文件放到 `assets/`。
+- 如果某个专家流程只服务这个 skill，可以放进 `agents/`，但先把它当私有 contract，不要自动上升成全局产品概念。
+
+### 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`

package/dist/builtin/skill-creator/agents/analyzer.md

@@ -0,0 +1,12 @@
+# Analyzer
+
+You are the benchmark analysis specialist for KodaX skill evaluation workspaces.
+
+Your job is to look across benchmark and grading artifacts, identify signal vs noise, and recommend the next iteration.
+
+Rules:
+- Focus on stable deltas, variance, repeated failures, and likely weak assertions.
+- Separate real improvement from measurement noise.
+- Prefer specific, operational recommendations over generic advice.
+- Call out when the data is inconclusive.
+- Return JSON only.

package/dist/builtin/skill-creator/agents/comparator.md

@@ -0,0 +1,13 @@
+# Comparator
+
+You are the blind comparison specialist for KodaX skill eval outputs.
+
+Your job is to compare candidate outputs without relying on config names or implementation details.
+
+Rules:
+- Judge against the eval prompt, expected outcome, and explicit assertions.
+- Compare only the quality of the visible outputs.
+- Prefer clearer, more complete, and less risky answers.
+- Use `tie` when both outputs are similarly strong or similarly weak.
+- Use `inconclusive` when the prompt does not provide enough evidence to decide.
+- Return JSON only.

package/dist/builtin/skill-creator/agents/grader.md

@@ -0,0 +1,13 @@
+# Grader
+
+You are the grading specialist for KodaX skill eval runs.
+
+Your job is to judge one run against the eval prompt, expected outcome, and explicit assertions.
+
+Rules:
+- Judge only what is visible in the provided artifacts.
+- Do not assume hidden behavior or give credit for intentions.
+- Prefer concrete evidence from the final output.
+- If an expectation is only partially satisfied, mark it as failed and explain why.
+- Keep uncertainty explicit instead of guessing.
+- Return JSON only.

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

@@ -0,0 +1,227 @@
+# Skill Creator Schemas
+
+这份参考文档定义 KodaX 版 `skill-creator` 默认使用的评测文件格式。它不是强制协议，但建议优先沿用，方便后续聚合、review 和自动分析。
+
+## `evals/evals.json`
+
+用于保存测试提示集合。
+
+```json
+{
+  "skill_name": "example-skill",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "User task prompt",
+      "expected_output": "What a good result should achieve",
+      "files": [],
+      "assertions": []
+    }
+  ]
+}
+```
+
+字段说明：
+- `skill_name`: skill 名称。
+- `evals`: 测试用例数组。
+- `id`: 用例唯一标识。
+- `prompt`: 给 agent 的任务文本。
+- `expected_output`: 对预期结果的简短说明。
+- `files`: 需要作为输入提供的文件列表。
+- `assertions`: 可选，后续 grading 用的断言定义。
+
+## `eval_metadata.json`
+
+用于单个 eval 目录，帮助 review 工具识别 prompt 和断言。
+
+```json
+{
+  "eval_id": 1,
+  "eval_name": "handles-empty-input",
+  "prompt": "Implement validation for empty input",
+  "expected_output": "Reject empty input with a clear message",
+  "assertions": [
+    {
+      "text": "rejects empty input with a clear message"
+    }
+  ]
+}
+```
+
+## `grading.json`
+
+由 `grade-evals.js` 生成，用于保存单次运行后的断言判定结果。
+
+```json
+{
+  "summary": {
+    "passed": 2,
+    "failed": 1,
+    "total": 3,
+    "pass_rate": 0.6667
+  },
+  "expectations": [
+    {
+      "text": "rejects empty input with a clear message",
+      "passed": true,
+      "evidence": "Observed in outputs/result.md"
+    }
+  ],
+  "execution_metrics": {
+    "total_tool_calls": 4,
+    "errors_encountered": 0,
+    "output_chars": 5120
+  },
+  "user_notes_summary": {
+    "uncertainties": [],
+    "needs_review": [],
+    "workarounds": []
+  },
+  "overall_summary": "Mostly correct, but edge cases need review.",
+  "timing": {
+    "total_tokens": 84852,
+    "total_duration_seconds": 23.3
+  },
+  "meta": {
+    "generated_at": "2026-03-17T12:00:00.000Z",
+    "eval_id": 1,
+    "eval_name": "handles-empty-input",
+    "config": "with_skill",
+    "run_id": "run-1"
+  }
+}
+```
+
+要求：
+- `expectations` 里的字段名固定为 `text`、`passed`、`evidence`。
+- `pass_rate` 建议是 `0..1` 之间的小数。
+
+## `timing.json`
+
+用于保存一次运行的耗时与 token 信息。
+
+```json
+{
+  "total_tokens": 84852,
+  "duration_ms": 23332,
+  "total_duration_seconds": 23.3
+}
+```
+
+## `benchmark.json`
+
+由 `aggregate-benchmark.js` 生成，用于总览不同配置的表现。
+
+```json
+{
+  "skill_name": "example-skill",
+  "generated_at": "2026-03-17T12:00:00.000Z",
+  "workspace": "/abs/path/to/iteration-1",
+  "configs": {
+    "with_skill": {
+      "pass_rate": { "mean": 0.9, "stddev": 0.1, "min": 0.8, "max": 1.0 },
+      "time_seconds": { "mean": 12.4, "stddev": 1.1, "min": 11.2, "max": 13.5 },
+      "tokens": { "mean": 4200, "stddev": 380, "min": 3900, "max": 4700 }
+    },
+    "without_skill": {
+      "pass_rate": { "mean": 0.6, "stddev": 0.2, "min": 0.4, "max": 0.8 },
+      "time_seconds": { "mean": 9.5, "stddev": 0.7, "min": 8.9, "max": 10.2 },
+      "tokens": { "mean": 3100, "stddev": 240, "min": 2900, "max": 3400 }
+    }
+  },
+  "delta": {
+    "pass_rate": "+0.3000",
+    "time_seconds": "+2.9000",
+    "tokens": "+1100.0000"
+  },
+  "runs": {
+    "with_skill": [],
+    "without_skill": []
+  }
+}
+```
+
+## `analysis.json`
+
+由 `analyze-benchmark.js` 生成，用于总结 benchmark 的稳定收益、方差热点和下一步建议。
+
+```json
+{
+  "skill_name": "example-skill",
+  "generated_at": "2026-03-17T12:15:00.000Z",
+  "workspace": "/abs/path/to/iteration-1",
+  "verdict": "improves",
+  "release_readiness": "needs_iteration",
+  "recommendation": "Keep the skill, but reduce variance before release.",
+  "key_findings": [
+    "with_skill materially improves pass rate"
+  ],
+  "variance_hotspots": [
+    "baseline repeatedly misses billing details"
+  ],
+  "suggested_actions": [
+    "tighten assertions around billing coverage"
+  ],
+  "watchouts": [
+    "token cost increased"
+  ],
+  "supporting_metrics": {
+    "pass_rate_delta": "+0.3000",
+    "time_seconds_delta": "+2.9000",
+    "tokens_delta": "+1100.0000"
+  },
+  "failure_clusters": {}
+}
+```
+
+## `comparison.json`
+
+由 `compare-runs.js` 生成，用于 blind comparison 两个 config 的输出质量。
+
+```json
+{
+  "workspace": "/abs/path/to/iteration-1",
+  "generated_at": "2026-03-17T12:20:00.000Z",
+  "config_a": "with_skill",
+  "config_b": "without_skill",
+  "summary": {
+    "total_pairs": 3,
+    "config_a_wins": 2,
+    "config_b_wins": 0,
+    "ties": 1,
+    "inconclusive": 0
+  },
+  "comparisons": [
+    {
+      "eval_id": 1,
+      "winner_label": "A",
+      "winner_config": "with_skill",
+      "confidence": 0.9,
+      "rationale": "Candidate A is more complete and specific."
+    }
+  ]
+}
+```
+
+## 推荐目录结构
+
+```text
+my-skill-workspace/
+└── iteration-1/
+    ├── eval-0/
+    │   ├── eval_metadata.json
+    │   ├── with_skill/
+    │   │   ├── outputs/
+    │   │   ├── grading.json
+    │   │   └── timing.json
+    │   └── without_skill/
+    │       ├── outputs/
+    │       ├── grading.json
+    │       └── timing.json
+    ├── benchmark.json
+    ├── benchmark.md
+    ├── analysis.json
+    ├── analysis.md
+    ├── comparison.json
+    └── comparison.md
+```

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

@@ -0,0 +1,46 @@
+export interface BenchmarkRun {
+  eval_id: string | number;
+  run_id: string;
+  pass_rate: number;
+  passed: number;
+  failed: number;
+  total: number;
+  time_seconds: number;
+  tokens: number;
+  tool_calls: number;
+  errors: number;
+  expectations: Array<Record<string, unknown>>;
+  notes: string[];
+}
+
+export interface StatsSummary {
+  mean: number;
+  stddev: number;
+  min: number;
+  max: number;
+}
+
+export interface BenchmarkDocument {
+  skill_name: string;
+  generated_at: string;
+  workspace: string;
+  configs: Record<string, {
+    pass_rate: StatsSummary;
+    time_seconds: StatsSummary;
+    tokens: StatsSummary;
+  }>;
+  delta: {
+    pass_rate: string;
+    time_seconds: string;
+    tokens: string;
+  };
+  runs: Record<string, BenchmarkRun[]>;
+}
+
+export function loadRunResults(iterationDir: string): Promise<Record<string, BenchmarkRun[]>>;
+export function buildBenchmarkDocument(
+  iterationDir: string,
+  skillName: string,
+  configRuns: Record<string, BenchmarkRun[]>
+): BenchmarkDocument;
+export function renderBenchmarkMarkdown(benchmark: BenchmarkDocument): string;