@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/skills/distilled/distilled-creator.md

@@ -0,0 +1,181 @@
+---
+name: distilled-creator
+version: 0.2.0-distilled
+description: 'Distilled IT-universal skill: skill-creator (score 3.5/5)'
+keywords:
+  - skill creation
+  - create skill
+  - 创建技能
+  - skill development
+  - distill skill
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/anthropics/skills.git
+    license: Apache-2.0
+    commit: unknown
+    paths:
+      - skill-creator/SKILL.md
+  - upstream: https://github.com/anthropics/skills.git
+    license: Apache-2.0
+    commit: unknown
+    paths:
+      - slack-gif-creator/SKILL.md
+distilled_at: '2026-05-29T08:13:11.204Z'
+distilled_by: claude-code skill-distiller agent
+it_universal_score: 3.5
+it_universal_dims:
+  d1: 1
+  d2: 0.5
+  d3: 0.5
+  d4: 0.5
+  d5: 1
+it_universal_rationale: >-
+  Core methodology (intent capture, three-level skill loading, parallel with/baseline eval,
+  assertion timing) is fully language-agnostic and reusable in any Claude skill ecosystem;
+  deductions only for eval-viewer script path and evals.json convention tied to one specific infra.
+---
+
+# Skill Creator: Iterative Design & Evaluation Loop
+
+## When to use
+- You want to create a new Claude skill (markdown + YAML instruction file) from scratch
+- You want to improve an existing skill with test-based evidence
+- A user shows you a workflow in conversation and says "turn this into a skill"
+- You want to optimize a skill's description to fix undertriggering
+- You want to benchmark skill quality with a with/without-skill comparison
+
+## Core idea
+A Claude skill is a markdown file with YAML frontmatter following a three-level loading hierarchy: metadata (always in context), body (loaded on trigger), and bundled resources (on demand). Good skills are built iteratively — capture intent, interview for edge cases, draft SKILL.md, run parallel test cases (with-skill vs. baseline simultaneously), draft quantitative assertions *while runs are in progress*, then evaluate, rewrite, and repeat. Skill descriptions must be slightly "pushy" to overcome Claude's tendency to undertrigger. Communication style should match the user's technical fluency — observe cues before using jargon like "assertion" or "JSON" without explanation.
+
+## Steps
+
+### 1. Capture Intent
+Extract answers from conversation history first, then ask the user to fill gaps:
+1. What should this skill enable Claude to do?
+2. When should it trigger? (specific phrases, contexts, situations)
+3. What is the expected output format?
+4. Do objectively verifiable outputs exist? → plan test cases with assertions. Subjective outputs (writing style, art) → consider qualitative-only evaluation.
+
+### 2. Interview & Research
+Before writing test prompts, ask about edge cases, input/output formats, example files, success criteria, and dependencies. Research relevant docs or analogous patterns concurrently via subagents when available.
+
+### 3. Write SKILL.md
+
+**Frontmatter:**
+```yaml
+---
+name: my-skill          # kebab-case
+description: |
+  What this skill does AND when to use it. Make it slightly pushy:
+  "Use this whenever the user mentions X, Y, or Z — even if they
+  don't explicitly ask for [skill name]."
+compatibility:          # optional — required tools/MCPs
+---
+```
+
+**Directory anatomy:**
+```
+skill-name/
+├── SKILL.md                  ← required; keep under 500 lines
+└── optional-resources/
+    ├── scripts/              ← executable code for deterministic tasks
+    ├── references/           ← docs loaded into context on demand
+    └── assets/               ← templates, icons, fonts
+```
+
+**Three-level loading:**
+
+| Level | Content | When loaded |
+|-------|---------|-------------|
+| Metadata | name + description (~100 words) | Always in context |
+| SKILL.md body | Instructions (<500 lines ideal) | Whenever skill triggers |
+| Bundled resources | Scripts / references (unlimited) | Only when referenced |
+
+**Progressive disclosure:** If approaching 500 lines, split into hierarchy levels with clear pointers to where to read next. For reference files >300 lines, add a table of contents. For multi-variant skills (e.g., AWS / GCP / Azure), one file per variant so only the relevant one loads.
+
+**Output format pattern:**
+```markdown
+## Report structure
+ALWAYS use this exact template:
+# [Title]
+## Executive summary
+## Key findings
+## Recommendations
+```
+
+**Example pattern:**
+```markdown
+## Example 1
+Input: Added user authentication with JWT tokens
+Output: feat(auth): implement JWT-based authentication
+```
+
+Use imperative form. Explain *why* things matter rather than stacking MUSTs. Draft once, then read with fresh eyes and revise.
+
+**Security:** Skills must not contain malware, exploit code, or misleading content. Behavior must not surprise a user who reads the description.
+
+### 4. Draft Test Cases
+Write 2–3 realistic test prompts (the kind a real user would actually type). Share with the user for confirmation before running.
+
+Save to your project's eval file (e.g., `evals/evals.json`):
+```json
+{
+  "skill_name": "example-skill",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "User's actual task prompt",
+      "expected_output": "Description of expected result",
+      "files": [],
+      "assertions": []
+    }
+  ]
+}
+```
+Leave `assertions` empty for now — add them in Step 6.
+
+### 5. Spawn All Runs in One Turn (With-Skill AND Baseline)
+For each test case, launch **two subagents simultaneously in the same turn** — never sequentially:
+
+- **With-skill run:** provide skill path + prompt → save to `<workspace>/iteration-<N>/<eval-name>/with_skill/outputs/`
+- **Baseline run:**
+  - *New skill:* same prompt with no skill → `without_skill/outputs/`
+  - *Improving existing skill:* snapshot old version first, point baseline at snapshot → `old_skill/outputs/`
+
+Create `eval_metadata.json` per eval directory:
+```json
+{
+  "eval_id": 0,
+  "eval_name": "descriptive-name-of-what-is-being-tested",
+  "prompt": "The user's task prompt",
+  "assertions": []
+}
+```
+
+Name eval directories descriptively, not generically. Workspace layout: `<skill-name>-workspace/iteration-<N>/<eval-name>/`.
+
+### 6. Draft Assertions While Runs Are In Progress
+Use the wait time. Draft quantitative assertions — objectively verifiable checks with descriptive names readable at a glance in any benchmark viewer. For subjective skills, rely on qualitative review; do not force assertions.
+
+Update `eval_metadata.json` and the eval file with finalized assertions before runs complete.
+
+### 7. Review Results
+Present with-skill vs. baseline side by side. Use your project's viewer/review script if available. Report both quantitative metrics and qualitative observations to the user.
+
+### 8. Iterate
+Rewrite the skill based on user feedback and quantitative failures. Repeat from Step 5 (or Step 4 if prompts also need changing). After stabilization, expand the test set for larger-scale confidence.
+
+### 9. Optimize the Description (Final)
+Run your project's skill description improver tool (if available) to maximize triggering accuracy. This is the last step, but it's worth doing — a poorly-written description causes good skills to be ignored.
+
+## Anti-patterns
+- Spawning with-skill runs first, then circling back for baselines — always launch everything in one turn
+- Waiting for runs to finish before drafting assertions — use the time productively
+- Forcing quantitative assertions onto subjective skills (style, art quality)
+- Vague or passive descriptions — they must tell Claude *when* to proactively use the skill
+- Exceeding 500 lines in SKILL.md body without adding a hierarchy layer and forward pointers
+- Generic eval directory names (`eval-0`) instead of descriptive ones
+- Assuming `eval_metadata.json` or assertions carry over from a prior iteration without recreating them
+
+## References
+- Upstream: https://github.com/anthropics/skills.git

package/dist/skills/distilled/distilled-db-schema-design.md

@@ -0,0 +1,245 @@
+---
+name: distilled-db-schema-design
+version: 0.1.0-distilled
+description: 'Distilled IT-universal skill: db-schema-design (score 4.5/5)'
+keywords:
+  - db
+  - schema
+  - design
+  - database
+  - 数据库设计
+  - migration
+  - 迁移
+  - sql
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/winspan/claude-forge.git
+    license: MIT
+    commit: 7d96b86c
+    paths:
+      - official/official-db-schema-design.md
+distilled_at: '2026-05-27T01:55:04.825Z'
+distilled_by: claude-sonnet-4-6
+it_universal_score: 4.5
+it_universal_dims:
+  d1: 1
+  d2: 1
+  d3: 1
+  d4: 0.5
+  d5: 1
+it_universal_rationale: DB schema + migration patterns, cross-engine.
+---
+
+## 触发条件
+
+- 新建项目需要设计初始数据库结构时
+- 现有 schema 出现性能问题、数据一致性问题或难以扩展时
+- 添加新业务实体或修改已有实体关系时
+- 需要对生产数据库执行结构变更（加列、改类型、删表等）时
+- Code review 中发现 schema 设计存在反模式需要纠正时
+
+---
+
+## 核心原则
+
+1. **先建模，再建表** — ER 图或实体关系草图能暴露设计缺陷，比直接写 DDL 的返工成本低一个数量级。
+2. **单表单实体** — 每张表只表达一个业务实体；混合多个实体的宽表会导致更新异常和冗余。
+3. **约束下沉到数据库层** — 外键、唯一约束、非空约束在 DB 层强制，而不仅依赖应用层校验；应用可以崩溃，数据库约束不会。
+4. **所有变更通过迁移文件管理** — 手动改生产库无法审计、无法回滚；迁移文件是 schema 的版本历史。
+5. **破坏性变更分阶段执行** — 直接删列或改类型会导致零停机部署失败；分步操作（加→双写→删）保证新旧代码可以同时运行。
+
+---
+
+## 工作流
+
+1. **绘制实体关系图**
+   在动手写 DDL 之前，用任意工具（纸、draw.io、dbdiagram.io 等）画出实体、属性和关系。确认每个实体的边界和基数（1:1 / 1:N / M:N）。
+
+2. **确定命名规范**
+   - 表名：`snake_case` 复数形式（`user_profiles`、`order_items`）
+   - 主键：统一用 `id`（自增整数或 UUID，按项目需求选择）
+   - 时间戳：每张表必须包含 `created_at`、`updated_at`
+   - 软删除：用 `deleted_at`（nullable）而非物理删除
+
+3. **编写 DDL / 迁移文件**
+   使用项目已有的迁移工具（Flyway、Liquibase、Alembic、golang-migrate、Prisma Migrate 等）创建迁移文件，不直接在数据库控制台执行 DDL。
+
+4. **添加必要约束**
+   - 外键列声明 `FOREIGN KEY` 约束
+   - 业务唯一性用 `UNIQUE` 约束而非仅靠应用层
+   - 非空字段显式标注 `NOT NULL`
+
+5. **规划索引**
+   - 所有外键列建索引（大多数数据库不自动创建）
+   - 高频 `WHERE` / `ORDER BY` 列建索引
+   - 复合索引按查询的列顺序排列（最左前缀原则）
+   - 避免过度索引：写多读少的表索引越多写入越慢
+
+6. **编写 down migration（回滚脚本）**
+   每个 up migration 必须有对应的 down migration，并在非生产环境验证回滚可以干净执行。
+
+7. **处理破坏性变更（三步法）**
+   ```
+   Step 1 — 加新列（新旧代码均可运行）
+   Step 2 — 双写：应用同时写旧列和新列，迁移存量数据
+   Step 3 — 确认数据一致后，删旧列（单独一次迁移）
+   ```
+
+8. **Review 检查清单**
+   在合并前对照"验证标准"逐项确认，重点关注缺失索引、缺失时间戳、以及是否绕过了迁移文件直接改库。
+
+---
+
+## 反模式
+
+1. **手动修改生产数据库**
+   直接在生产控制台执行 `ALTER TABLE` 或 `DROP COLUMN`，导致变更无法审计、无法在其他环境复现、无法回滚。所有变更必须走迁移文件。
+
+2. **滥用 `ENUM` 类型**
+   数据库原生 `ENUM` 在多数引擎中修改成本极高（MySQL 需要重建表）。用关联表（lookup table）或受约束的字符串列代替，扩展时只需插入新行。
+
+3. **用 JSON 列存结构化数据**
+   把本应规范化的字段塞进 JSON 列，导致无法建索引、无法做外键约束、查询复杂度上升。JSON 列只适合真正不定结构的数据（如用户自定义元数据）。
+
+4. **EAV 模式（Entity-Attribute-Value）**
+   用三列通用表（`entity_id`, `attribute_name`, `value`）模拟动态字段，看似灵活，实则查询性能极差、类型安全丧失、关联查询变成噩梦。优先考虑 JSONB 或宽表，极端情况才考虑文档数据库。
+
+5. **缺失时间戳或软删除字段**
+   没有 `created_at` / `updated_at` 的表在排查问题时缺乏基本的时间线信息；物理删除数据后无法审计或恢复。每张表默认加时间戳，有审计需求的加 `deleted_at`。
+
+---
+
+## 验证标准
+
+- [ ] 存在 ER 图或等效的实体关系文档，与实际 DDL 保持同步
+- [ ] 每张表有且仅有一个业务实体，无跨实体的宽表
+- [ ] 所有表包含 `created_at`、`updated_at` 字段
+- [ ] 所有外键列已建索引
+- [ ] 高频查询的过滤列已建索引，且索引顺序与查询一致
+- [ ] 无裸 `ENUM` 类型；动态枚举值使用关联表或字符串
+- [ ] JSON 列仅用于非结构化数据，结构化字段已规范化
+- [ ] 每个 schema 变更对应一个迁移文件，且 down migration 可执行
+- [ ] 破坏性变更（删列、改类型）已拆分为多步迁移
+- [ ] 迁移文件已在非生产环境验证（up 和 down 均通过）
+- [ ] 无直接在数据库控制台执行的未记录变更
+
+---
+
+## 适用范围
+
+本技能适用于任何使用关系型数据库的层次：
+
+- **后端服务（backend service）** — 业务逻辑层通过 ORM 或查询构建器与 schema 交互，需遵循命名规范和约束设计
+- **持久化层（persistence layer）** — 迁移文件、连接池配置、事务边界均在此层管理
+- **调度器 / 后台任务（scheduler）** — 批量写入任务需特别关注索引对写入性能的影响
+- **CLI 工具** — 若 CLI 直接操作数据库（如数据导入、初始化脚本），同样需要走迁移流程而非裸 DDL
+- **知识库 / 搜索层（knowledge base）** — 若使用关系型存储作为向量或文档索引的元数据层，schema 设计原则同样适用
+
+> // 项目特定，复用时跳过
+> 若项目使用特定的迁移框架（如 Alembic for Python、golang-migrate for Go、Knex for Node.js），迁移文件的目录结构和命名约定以该框架文档为准，本技能描述的原则不变。
+
+---
+
+## 上游对照
+
+本技能从单一上游的 db-schema-design 规范（来源见 frontmatter）提炼，内容已做通用化处理：移除了项目特定的路径引用和工具名称，补充了多语言生态下的迁移工具示例，并将破坏性变更的三步法展开为可操作的工作流步骤。如后续有更多上游（如针对 NoSQL 或时序数据库的 schema 设计规范）合并进来，应在"核心原则"和"反模式"中增加对应的对比说明。
+
+---
+
+## 示例（伪代码）
+
+### 场景：为"订单系统"新增 `discount_codes` 表
+
+**Step 1 — 建模**
+
+```
+实体：DiscountCode
+属性：id, code(唯一), discount_percent, expires_at, created_at, updated_at, deleted_at
+关系：Order (N) ——uses——> DiscountCode (1)
+      => orders 表加外键列 discount_code_id
+```
+
+**Step 2 — 编写迁移文件（伪代码，适用于任意迁移框架）**
+
+```
+-- UP
+CREATE TABLE discount_codes (
+    id          BIGINT PRIMARY KEY AUTO_INCREMENT,  -- 或 UUID
+    code        VARCHAR(64) NOT NULL UNIQUE,
+    discount_percent NUMERIC(5,2) NOT NULL,
+    expires_at  TIMESTAMP,
+    created_at  TIMESTAMP NOT NULL DEFAULT NOW(),
+    updated_at  TIMESTAMP NOT NULL DEFAULT NOW(),
+    deleted_at  TIMESTAMP                           -- 软删除
+);
+
+-- orders 表加外键（破坏性变更三步法 Step 1：加新列）
+ALTER TABLE orders
+    ADD COLUMN discount_code_id BIGINT,
+    ADD CONSTRAINT fk_orders_discount_code
+        FOREIGN KEY (discount_code_id)
+        REFERENCES discount_codes(id);
+
+-- 外键列建索引
+CREATE INDEX idx_orders_discount_code_id ON orders(discount_code_id);
+
+-- DOWN
+DROP INDEX idx_orders_discount_code_id ON orders;
+ALTER TABLE orders DROP FOREIGN KEY fk_orders_discount_code;
+ALTER TABLE orders DROP COLUMN discount_code_id;
+DROP TABLE discount_codes;
+```
+
+**Step 3 — 多语言迁移工具调用示意**
+
+```
+# Python (Alembic)
+alembic upgrade head
+alembic downgrade -1
+
+# Go (golang-migrate)
+migrate -path ./migrations -database $DATABASE_URL up
+migrate -path ./migrations -database $DATABASE_URL down 1
+
+# Node.js (Knex / Prisma)
+npx knex migrate:latest
+npx knex migrate:rollback
+
+# Java (Flyway)
+flyway migrate
+flyway undo          # 需要 Flyway Teams
+```
+
+**Step 4 — 验证索引覆盖（伪代码）**
+
+```
+-- 检查高频查询是否命中索引
+EXPLAIN SELECT * FROM orders
+WHERE discount_code_id = ?
+  AND deleted_at IS NULL;
+
+-- 期望输出：type = ref 或 range，key = idx_orders_discount_code_id
+-- 若 type = ALL（全表扫描），说明索引未生效，需检查列类型是否匹配
+```
+
+**Step 5 — 破坏性变更示例：将 `discount_percent` 从 `INT` 改为 `NUMERIC`**
+
+```
+-- 错误做法（直接 ALTER，可能锁表或丢精度）
+ALTER TABLE discount_codes MODIFY discount_percent NUMERIC(5,2);
+
+-- 正确做法（三步法）
+-- 迁移 A：加新列
+ALTER TABLE discount_codes ADD COLUMN discount_percent_new NUMERIC(5,2);
+
+-- 应用层双写（伪代码）
+function saveDiscount(record):
+    record.discount_percent     = toInt(value)    // 旧列，兼容旧代码
+    record.discount_percent_new = toDecimal(value) // 新列
+    db.save(record)
+
+-- 迁移 B：存量数据回填 + 删旧列（确认双写稳定后执行）
+UPDATE discount_codes SET discount_percent_new = discount_percent::NUMERIC;
+ALTER TABLE discount_codes DROP COLUMN discount_percent;
+ALTER TABLE discount_codes RENAME COLUMN discount_percent_new TO discount_percent;
+```

package/dist/skills/distilled/distilled-dispatching-parallel-agents.md

@@ -0,0 +1,136 @@
+---
+name: distilled-dispatching-parallel-agents
+version: 0.2.0-distilled
+description: 'Distilled IT-universal skill: dispatching-parallel-agents (score 3.5/5)'
+keywords:
+  - dispatching
+  - parallel
+  - agents
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/obra/superpowers.git
+    license: MIT
+    commit: f2cbfbefebbfef77321e4c9abc9e949826bea9d7
+    paths:
+      - dispatching-parallel-agents/SKILL.md
+distilled_at: '2026-06-15T00:49:21.259Z'
+distilled_by: claude-code skill-distiller agent
+it_universal_score: 3.5
+it_universal_dims:
+  d1: 0.5
+  d2: 0.5
+  d3: 0.5
+  d4: 1
+  d5: 1
+it_universal_rationale: >-
+  Four-step parallel dispatch pattern (identify → task → dispatch → integrate) applies to any
+  codebase and any agent framework; examples are illustrative, not framework-locked
+---
+
+# Dispatching Parallel Agents for Independent Problems
+
+## When to use
+
+- Two or more failures / tasks span **different problem domains** with no shared state
+- Each sub-problem can be understood without context from the others
+- Agents would not edit the same files or race on the same resources
+- You want wall-clock time equal to the slowest agent, not the sum of all agents
+
+**Do NOT use when:**
+- Failures are related — fixing one might fix others (investigate together first)
+- You are still in exploratory mode and don't yet know what's broken
+- Agents would interfere (editing the same file, locking the same resource)
+- All failures share a single root cause
+
+## Core idea
+
+When multiple independent problems exist simultaneously, serialising their
+investigation wastes time proportional to `N - 1` agent turns. The insight is
+simple: **dispatch one agent per independent problem domain and let them run
+concurrently**. Each agent gets a narrow scope, isolated context, and a concrete
+deliverable. The orchestrator's job is to identify the domain boundaries, craft
+tight prompts, and integrate results — not to investigate itself.
+
+Good parallel dispatch rests on three guarantees: agents receive *exactly* the
+context they need (no more, no less), their scopes do not overlap, and the
+orchestrator verifies integration after all agents return.
+
+## Steps
+
+1. **Identify independent domains**
+   Group the work by what is broken or needs doing. Ask: "Could I hand these
+   to two different engineers who never talk to each other?" If yes, they are
+   independent domains.
+
+2. **Write a focused prompt per agent**
+   Each prompt must contain:
+   - **Scope**: one clearly bounded area (one test file, one subsystem, one bug)
+   - **Goal**: what "done" looks like (tests pass / feature works / analysis returned)
+   - **Constraints**: what NOT to touch ("do not change unrelated code")
+   - **Expected output**: what the agent should return ("summary of root cause and changes made")
+
+   Template:
+   ```
+   Fix the N failing cases in <file or subsystem>:
+
+   1. "<test/case name>" — <symptom observed>
+   2. "<test/case name>" — <symptom observed>
+
+   Your task:
+   1. Read <relevant file(s)> and understand what each case verifies
+   2. Identify the root cause
+   3. Fix it — do NOT just increase timeouts or skip assertions
+
+   Constraints: do not touch <out-of-scope areas>.
+
+   Return: brief summary of root cause + list of changes made.
+   ```
+
+3. **Dispatch all agents in a single message** (parallel, not sequential)
+   Emit all `Task` / agent-spawn calls at once. Do not wait for one to finish
+   before dispatching the next — that defeats the purpose.
+
+4. **Review and integrate**
+   When all agents return:
+   - Read each summary; verify scope was respected
+   - Check for conflicts (did two agents edit the same file?)
+   - Run the full test suite / verification step
+   - Spot-check agent reasoning — agents can make systematic errors
+
+## Anti-patterns
+
+- **Too broad a scope per agent**: "Fix all the broken tests" → agent gets lost
+  and thrashes. Give each agent one file or one subsystem.
+- **Missing context in prompt**: "Fix the race condition" with no details →
+  agent hallucinates the problem. Paste actual error messages and failing case
+  names.
+- **No output constraint**: agent may refactor production code unasked.
+  Add "do NOT change X" explicitly.
+- **Vague deliverable**: "Fix it" → you cannot tell what changed or whether it
+  is correct. Ask for a structured summary.
+- **Dispatching sequentially**: spawning agent 2 only after agent 1 returns
+  eliminates the parallelism benefit. Batch all dispatches in one message.
+- **Dispatching when domains overlap**: if agents share mutable state (same
+  file, same DB, same resource), they will conflict silently. Serialise those.
+
+## Example domain split
+
+| Agent | Scope | Why independent |
+|---|---|---|
+| Agent 1 | Abort/interrupt logic tests | Abort flow has no overlap with batch scheduling |
+| Agent 2 | Batch completion behavior tests | Batch scheduling unrelated to race-condition guards |
+| Agent 3 | Approval race-condition tests | Race guard is a thin wrapper layer, isolated |
+
+Each agent investigates in parallel → wall-clock cost = max(agent times), not sum.
+
+## Verification checklist
+
+After all agents return:
+- [ ] Each agent's changes are within its declared scope
+- [ ] No two agents edited the same file/function
+- [ ] Full suite (or end-to-end check) is green
+- [ ] Any systematic misunderstanding caught and corrected before merge
+
+## References
+
+- Upstream: https://github.com/obra/superpowers.git