skill-builder

Skill-Builder：用于创建 Skill 的元技能

你负责帮助创建遵循既定模式的新 Agent Skill。你的职责是指导 Skill 设计、生成脚手架，并验证完整性。

核心原则

Skill 是配备工具的诊断框架，而不是功能检查清单。

Skill 用于诊断问题领域、识别状态并提供干预措施。脚本负责随机化和构建结构；大模型负责判断。各司其职，发挥所长。

Skill 构成

每个 Skill 都包含以下组件：

skill-name/
├── SKILL.md           # Diagnostic framework + documentation
├── scripts/           # Deno TypeScript tools
│   └── *.ts
├── data/              # JSON datasets (if needed)
│   └── *.json
└── references/        # Supporting documentation (optional)
    └── *.md

SKILL.md 结构

---
name: skill-name
description: One sentence starting with action verb
license: MIT
metadata:
  author: your-name
  version: "1.0"
  maturity_score: [0-20]                          # Optional
---

# Skill Name: Subtitle

You [role description]. Your role is to [specific function].

## Core Principle
**Bold statement capturing diagnostic essence.**

## The States
### State X1: Name
**Symptoms:** What the user notices
**Key Questions:** What to ask
**Interventions:** What framework/tool to apply

[Repeat for each state]

## Diagnostic Process
1. Step one
2. Step two
...

## Key Questions
### For Category A
- Question?
- Question?

## Anti-Patterns
### The [Problem Name]
**Problem:** Description
**Fix:** Solution

## Available Tools
### script.ts
Description of what it does.
\`\`\`bash
deno run --allow-read scripts/script.ts [args]
\`\`\`

## Example Interaction
**User:** "Problem description"
**Your approach:**
1. Action
2. Action

## What You Do NOT Do
- List of boundaries
- Things the skill never does

## Integration Graph

### Inbound (From Other Skills)
| Source Skill | Source State | Leads to State |
|--------------|--------------|----------------|
| [skill] | [state] | [state] |

### Outbound (To Other Skills)
| This State | Leads to Skill | Target State |
|------------|----------------|--------------|
| [state] | [skill] | [state] |

### Complementary Skills
| Skill | Relationship |
|-------|--------------|
| [skill] | [how they relate] |

Skill 类型

类型 D：诊断型 Skill

用途： 识别问题并推荐干预措施
模式： 状态 → 问题 → 干预措施
示例： story-sense、worldbuilding、conlang

主要特征：

• 包含问题状态及其症状／问题
• 交叉引用干预工具
• 包含“你不应做的事”一节，以明确边界
• 提供映射到其他 Skill 的集成表

类型 G：生成型 Skill

用途： 根据参数生成结构化输出
模式： 参数 → 生成 → 输出
示例： story-sense 中的 functions、conlang 中的 phonology

主要特征：

• 输入参数及默认值
• 支持随机化，可选择设置种子
• 多种输出格式（人类可读、JSON、简要版）
• 质量等级（入门级 → 全面级）

类型 U：实用型 Skill

用途： 支持其他 Skill 并搭建基础设施
模式： 输入 → 分析／转换 → 报告
示例： list-builder、skill-builder

主要特征：

• 元级操作
• 质量指标与验证
• 模板和脚手架
• 可跨 Skill 应用

类型 O：编排型 Skill

用途： 将多个 Skill 协调成自主工作流
模式： 输入 → 多轮评估循环 → 润色后的输出
示例： chapter-drafter

主要特征：

• 按顺序调用多个子 Skill
• 迭代，直到达到质量阈值
• 在各工作单元之间累积上下文
• 自主运行，无需人工检查点

必需的 frontmatter：

metadata:
  orchestrates:           # Sub-skills to coordinate
    - skill-one
    - skill-two
  pass_order:             # Evaluation sequence
    - skill-one
    - skill-two
  pass_weights:           # Weight per skill (sum to 100)
    skill-one: 50
    skill-two: 50
  max_iterations: 3       # Per-pass iteration limit
  global_max_iterations: 50  # Total cap

架构详情请参阅 skills/fiction/orchestrators/README.md。

Skill 成熟度评分（24 分）

Skill 采用与框架 24 分制平行的评分标准进行评估。

完整性（11 分）

检查项	分值	标准
核心原则	1	用醒目的声明概括诊断本质
状态	2	诊断型 Skill 包含 3–7 个状态（生成型／实用型不适用）
状态组成	2	每个状态都包含症状、关键问题和干预措施
诊断流程	1	记录分步流程
反模式	2	至少 3 个反模式，采用“问题／修正”结构
示例	2	至少 2 个完整示例，展示 Skill 的应用
边界	1	包含“你不应做的事”一节

质量（5 分）

检查项	分值	标准
自包含	1	无需阅读其他 Skill 即可使用
声明类型和模式	1	包含必需的 frontmatter 字段
状态命名	1	状态前缀一致，并与 Skill 缩写相符
集成图	1	记录与其他 Skill 的关联
工具文档	1	所有脚本都有用法说明

易用性（4 分）

检查项	分值	标准
输出持久化	1	持久化部分经过定制，而非使用样板文本
渐进式披露	1	提供速查部分，便于快速浏览
决策树	1	为常见场景提供路由逻辑
可执行性	1	为每种诊断提供清晰的后续步骤

执行智能（4 分）——新增

检查项	分值	标准
推理要求	1	说明扩展思考何时有助于完成任务
执行策略	1	记录顺序执行与可并行处理的工作
子 Agent 指引	1	指明何时应启动专用子 Agent
上下文管理	1	记录 token 占用量和优化策略

成熟度级别

级别	分数	说明
草稿	0-8	缺少核心要素
开发中	9-14	功能可用，但不完整
稳定	15-20	可用于生产环境
久经考验	21-24	包含案例研究和完整的执行智能

必需元数据

类型（必需）

每项技能都必须在 frontmatter 中声明其类型：

metadata:

类型	定义	必需章节
diagnostic	识别问题并推荐干预措施	状态、诊断流程、反模式
generator	根据参数生成结构化输出	参数、生成逻辑、输出格式
utility	支持其他技能并构建基础设施	流程、模板、验证
orchestrator	协调多项技能，构建自主工作流	编排循环、通过标准、迭代限制

模式（必需）

每项技能都必须在 frontmatter 中声明其模式：

metadata:

模式	定义	用户关系
diagnostic	识别问题状态并提出建议	Agent 诊断，用户决策
assistive	提供指导，但不生成内容	Agent 提问，用户创作
collaborative	与用户协作	Agent 生成，用户指导
evaluative	评估现有作品	Agent 审查，用户回应
application	在实时情境中运行	Agent 运行，用户参与
generative	根据参数生成输出	Agent 生成，用户选择

当技能执行多种功能时，允许使用复合模式（例如，diagnostic+generative）。

可选元数据

metadata:
  maturity_score: 15

状态命名约定

状态必须遵循一致的命名模式：

约定：{ABBREV}{NUMBER}: {State Name}

规则：

1. 缩写为 1-3 个大写字母，由技能名称派生
2. 编号从 0（表示“不存在 X”的状态）或 1 开始
3. 状态名称应描述具体内容，而不能只是数字
4. 在现有状态之间插入子状态时，使用小数表示法（4.5、5.75）

标准缩写：

技能	缩写	示例
story-sense	SS	状态 SS1：缺乏基础的概念
dialogue	D	状态 D1：声音千篇一律
conlang	L	状态 L1：没有语言
worldbuilding	W	状态 W1：作为背景的世界
revision	R	状态 R1：不知所措
endings	E	状态 E1：随意的结局
character-arc	CA	状态 CA1：静态角色
scene-sequencing	SQ	状态 SQ1：仅以场景推进节奏
brainstorming	B	状态 B1：想法趋同
research	RS	状态 RS1：没有研究
requirements-analysis	RA	状态 RA1：需求模糊
system-design	SD	状态 SD1：没有架构
chapter-drafter	CD	（编排器——使用通过分数，而非状态）

新技能应选择尚未使用的缩写，并在此处记录。

集成图要求

每项技能都必须记录其与其他技能的关联。

必需格式：

## Integration Graph

### Inbound (From Other Skills)
| Source Skill | Source State | Leads to State |
|--------------|--------------|----------------|
| story-sense | SS5: Plot Without Purpose | D4: No Subtext |

### Outbound (To Other Skills)
| This State | Leads to Skill | Target State |
|------------|----------------|--------------|
| D6: Pacing Mismatch | scene-sequencing | SQ2: Sequel Missing |

### Complementary Skills
| Skill | Relationship |
|-------|--------------|
| character-arc | Voice reflects transformation |
| worldbuilding | Speech reflects culture |

要求：

• 至少有 1 项入站或出站关联
• 列出互补技能，以提供上下文
• 明确到状态级别（不能只说明技能之间的关联）
• 双向记录（如果 A 引用了 B，B 也应引用 A）

执行智能要求

技能应记录如何通过 Claude Code 获得最佳执行效果。

推理要求部分

说明扩展思考（ultrathink）对该技能有帮助的情况：

## Reasoning Requirements

### Standard Reasoning
- Initial diagnosis and symptom matching
- Simple state identification
- Script execution and output interpretation

### Extended Reasoning (ultrathink)
Use extended thinking for:
- Multi-framework synthesis - [Why: requires holding multiple models simultaneously]
- Complex worldbuilding systems - [Why: many interdependent variables]
- Cascade analysis across states - [Why: second-order effects compound]

**Trigger phrases:** "deep analysis", "comprehensive review", "multi-framework synthesis"

**重要原因：**大模型存在完成奖励偏差——它们会急于奔向显而易见的目标。扩展思考会在输出前分配推理时间，从而提升复杂任务的质量。这符合 LLM 流程设计框架的原则。

执行策略部分

说明顺序工作与并行工作的选择：

## Execution Strategy

### Sequential (Default)
- Diagnosis must complete before intervention
- State identification before framework selection

### Parallelizable
- Multiple script runs (entropy + functions) can run concurrently
- Research across multiple frameworks can parallelize
- Use when: Tasks are independent and can merge results

### Subagent Candidates
| Task | Agent Type | When to Spawn |
|------|------------|---------------|
| Codebase exploration | Explore | When skill needs project context |
| Framework research | general-purpose | When synthesizing across 3+ frameworks |

上下文管理部分

说明 token 的使用与优化：

## Context Management

### Approximate Token Footprint
- **Skill base:** ~2k tokens
- **With full state definitions:** ~4k tokens
- **With scripts inline:** ~8k tokens (avoid unless debugging)

### Context Optimization
- Load scripts on-demand rather than including inline
- Reference framework documentation by name rather than embedding
- Use Quick Reference section for common cases

### When Context Gets Tight
- Prioritize: Current state diagnosis and immediate intervention
- Defer: Integration graph, full anti-patterns list
- Drop: Script source code, historical examples

反模式要求

每项技能都必须记录常见错误。

最低要求：

• 诊断类技能需包含 3 个反模式
• 生成器／实用工具类技能需包含 2 个反模式

规定结构：

### The {Anti-Pattern Name}
**Pattern:** What the problematic behavior looks like
**Problem:** Why this causes harm
**Fix:** How to resolve it
**Detection:** [Optional] How to recognize this happening

常见反模式类别：

类别	示例名称
范围蔓延	大杂烩、任务蔓延
深度不足	浮于表面、清单
层级错误	自底向上编辑、过早优化
用户关系	提线木偶、被动接收者
集成	孤立技能、忽视边界

脚本模式

标准脚本模板

#!/usr/bin/env -S deno run --allow-read

/**
 * Script Name
 *
 * Description of what it does.
 *
 * Usage:
 *   deno run --allow-read script.ts [args]
 */

// === INTERFACES ===
interface ResultType {
  field: string;
  // ...
}

// === DATA ===
const DATA: Record<string, string[]> = {
  category: ["item1", "item2"],
};

// === UTILITIES ===
function randomFrom<T>(arr: T[], count: number = 1): T[] {
  const shuffled = [...arr].sort(() => Math.random() - 0.5);
  return shuffled.slice(0, Math.min(count, arr.length));
}

// === CORE LOGIC ===
function generate(/* params */): ResultType {
  // Generation logic
}

// === FORMATTING ===
function formatResult(result: ResultType): string {
  const lines: string[] = [];
  // Format output
  return lines.join("\n");
}

// === MAIN ===
function main(): void {
  const args = Deno.args;

  // Help
  if (args.includes("--help") || args.includes("-h")) {
    console.log(`Script Name

Usage:
  deno run --allow-read script.ts [options]

Options:
  --flag     Description
  --json     Output as JSON
`);
    Deno.exit(0);
  }

  // Parse arguments
  const flagIndex = args.indexOf("--flag");
  const flagValue = flagIndex !== -1 ? args[flagIndex + 1] : null;
  const jsonOutput = args.includes("--json");

  // Skip indices for positional arg detection
  const skipIndices = new Set<number>();
  if (flagIndex !== -1) {
    skipIndices.add(flagIndex);
    skipIndices.add(flagIndex + 1);
  }

  // Find positional argument
  let positionalArg: string | null = null;
  for (let i = 0; i < args.length; i++) {
    if (!args[i].startsWith("--") && !skipIndices.has(i)) {
      positionalArg = args[i];
      break;
    }
  }

  // Generate
  const result = generate(/* params */);

  // Output
  if (jsonOutput) {
    console.log(JSON.stringify(result, null, 2));
  } else {
    console.log(formatResult(result));
  }
}

main();

参数解析模式

// 1. Help check first
if (args.includes("--help") || args.includes("-h")) { ... }

// 2. Parse --flag value pairs
const flagIndex = args.indexOf("--flag");
const flagValue = flagIndex !== -1 ? args[flagIndex + 1] : defaultValue;

// 3. Boolean flags
const boolFlag = args.includes("--bool");

// 4. Track consumed indices
const skipIndices = new Set<number>();
if (flagIndex !== -1) {
  skipIndices.add(flagIndex);
  skipIndices.add(flagIndex + 1);
}

// 5. Find positional args
for (let i = 0; i < args.length; i++) {
  if (!args[i].startsWith("--") && !skipIndices.has(i)) {
    positionalArg = args[i];
    break;
  }
}

数据加载模式

// For external JSON files
async function loadData<T>(path: string): Promise<T> {
  try {
    const text = await Deno.readTextFile(path);
    return JSON.parse(text);
  } catch (e) {
    console.error(`Error loading ${path}: ${e}`);
    Deno.exit(1);
  }
}

// Relative path from script
const scriptDir = new URL(".", import.meta.url).pathname;
const dataPath = `${scriptDir}../data/file.json`;

输出模式

// Always support multiple formats
if (jsonOutput) {
  console.log(JSON.stringify(result, null, 2));
} else if (briefOutput) {
  console.log(formatBrief(result));
} else {
  console.log(formatFull(result));
}

数据文件模式

简单列表（用于熵／随机化）

{
  "list_name": [
    "Specific item with enough detail to spark ideas",
    "Another item that's 20-60 characters ideally",
    "Items should be concrete not vague"
  ]
}

质量门槛：

• 入门：10-30 个条目（仅用于演示）
• 实用：30-75 个条目（可供使用）
• 生产级：75-150 个条目（已就绪）
• 全面：150 个以上条目（达到参考级质量）

结构化数据（用于复杂生成）

{
  "_meta": {
    "description": "What this data is for",
    "usage": "How to use it",
    "source": "Where it came from (optional)"
  },
  "category": {
    "item_name": {
      "property": "value",
      "frequency": 0.85,
      "tags": ["tag1", "tag2"]
    }
  }
}

频率加权数据

{
  "tier_universal": {
    "description": "Found in nearly all cases",
    "items": { "a": { "frequency": 0.95 }, "b": { "frequency": 0.90 } }
  },
  "tier_common": {
    "description": "Found in most cases",
    "items": { "c": { "frequency": 0.70 } }
  },
  "tier_rare": {
    "description": "Unusual but attested",
    "items": { "d": { "frequency": 0.15 } }
  }
}

构建技能的诊断流程

创建新技能时：

1. 确定问题领域

• 该技能诊断哪些问题？
• 用户会注意到哪些症状？
• 这与现有技能有何关联？

2. 定义状态

• 创建 3-7 个不同的状态
• 每个状态都需要：症状、关键问题、干预措施
• 状态应互斥，同时覆盖整个问题领域

3. 设计工具

• 哪些工作由脚本完成比大模型判断更好？
• 随机化？结构生成？验证？
• 脚本需要哪些数据？

4. 梳理集成关系

• 该技能与哪些其他技能相关联？
• 其他技能中的哪些状态会引导用户来到这里？
• 这里的哪些状态会引导用户转向其他技能？

5. 验证完整性

运行 validate-skill.ts，检查：

• 必需的 frontmatter 字段
• 包含所有组成部分的状态定义
• 脚本文档
• 集成引用

可用工具

scaffold.ts

生成技能目录结构和模板文件。

# Create new skill scaffolding
deno run --allow-read --allow-write scripts/scaffold.ts skill-name

# With type specification
deno run --allow-read --allow-write scripts/scaffold.ts skill-name --type diagnostic

# Preview without writing
deno run --allow-read scripts/scaffold.ts skill-name --dry-run

validate-skill.ts

检查技能的完整性及其对模式的遵循情况。

# Validate a skill
deno run --allow-read scripts/validate-skill.ts ../worldbuilding

# Validate all skills in fiction cluster
deno run --allow-read scripts/validate-skill.ts --all

# JSON output for CI
deno run --allow-read scripts/validate-skill.ts ../conlang --json

反模式

功能列表式技能

**问题：**技能只是功能清单，而非诊断框架。 **解决方法：**围绕问题状态重新组织。用户卡在哪里？

大杂烩

**问题：**技能试图包揽太多，涵盖多个问题领域。 **解决方法：**拆分为专注的技能。一项技能对应一个诊断领域。

只有脚本，没有技能

**问题：**脚本已存在，但没有 SKILL.md 说明何时使用。 **解决方法：**每个脚本都应属于一项有明确用途说明的技能。

孤立技能

**问题：**该技能既不引用其他技能，也没有被其他技能引用。 **解决方法：**添加集成部分。梳理与其他技能之间的状态转换。

克隆技能

**问题：**该技能用不同名称重复了另一项技能的状态。 **解决方法：**合并技能，或明确区分各自的问题领域。

验证（Oracle）

本部分说明该技能可以可靠验证哪些内容，以及哪些内容需要人工判断。 有关 Oracle 的背景，请参阅 organization/architecture/context-packet-architecture.md。

此工具可以验证的内容

• 结构完整性——validate-skill.ts 检查必需章节是否存在（置信度高）
• 状态命名规范——验证 {ABBREV}{N}: Name 模式（置信度高）
• Frontmatter 是否存在——是否包含必需的 type/mode 字段（置信度高）
• 章节是否存在——是否包含反模式、Integration Graph 和 Output Persistence（置信度高）
• 状态组件结构——每个状态是否包含症状、问题和干预措施（置信度中）

需要人工判断的内容

• 状态质量——各状态是否互斥且全面？（语义判断）
• 集成准确性——跨技能的状态转换是否合理？（上下文判断）
• 反模式的实用性——是否涵盖真实的失败模式？（经验判断）
• 示例相关性——示例是否符合真实用例？（领域知识）
• 边界是否恰当——单个技能的范围是否正确？（设计判断）

可用的验证脚本

脚本	验证内容	置信度
validate-skill.ts	对完整性/质量/可用性进行 20 项成熟度评分	结构方面置信度高，语义方面置信度低
scaffold.ts	生成的文件是否符合预期结构	高

Oracle 的局限性

validate-skill.ts 脚本：

• 无法检测重复的技能覆盖范围（The Clone Skill 反模式）
• 无法检测范围蔓延（The Kitchen Sink 反模式）
• 无法验证集成的双向性（必须手动检查两个技能）
• 只报告是否存在，不评估质量——章节存在并不意味着内容良好

反馈循环

本节说明输出如何持久保存，并为未来的会话提供参考。 背景信息请参阅 organization/architecture/context-packet-architecture.md，了解反馈循环。

会话持久化

• 输出位置：skills/{cluster}/{skill-name}/（目录结构）
• **保存内容：**SKILL.md、scripts/、data/、templates/
• **命名模式：**技能名称将成为目录名称

跨会话学习

• **开始之前：**检查此问题领域是否已有相应技能
• **如果已有技能：**扩展而不是重复创建；检查集成图
• 以下反馈可以改进此技能：
  • 创建技能时发现的新反模式
  • 发现状态命名冲突
  • 效果良好的集成模式

改进触发条件

• validate-skill.ts 揭示常见失败时 → 更新成熟度标准
• 创建技能遇到困难时 → 将相关内容添加到反模式中
• 集成映射不清晰时 → 改进 Integration Graph 章节

设计约束

本节说明前提条件和边界。 背景信息请参阅 organization/architecture/context-packet-architecture.md，了解约束。

此技能的前提

• 用户有明确的问题领域需要解决（而不是模糊的“创建一个技能”）
• 问题领域具有可识别的状态（用户能够察觉的症状）
• 某些部分可以自动化（脚本与大模型的分工合理）

此技能不处理

• 框架开发（更高层次的抽象）——转至：framework-development methodology
• 一次性脚本（没有诊断模型）——转至：simple script writing
• 不含状态的技能（纯生成器）——转至：generator template（结构更简单）

退化信号

以下迹象表明此技能可能被误用：

• 无法为问题领域识别出 3 个或更多不同状态
• 所有“状态”实际上都是单个生成器的参数
• 与现有技能毫无关联（问题领域孤立）
• 问题领域与现有技能明显重叠

示例：构建新技能

请求：“创建一个用于诊断对话问题的技能”

第 1 步：识别问题领域

对话问题有别于场景排序（结构）和角色弧线（转变）。这里关注的是角色如何说话。

步骤 2：定义状态

• D1：没有对话（只有叙事性总结）
• D2：角色声音相同（所有人听起来都一样）
• D3：直白的对话（没有潜台词）
• D4：对话浮于表面（对话缺乏上下文）
• D5：纯功能性对话（推动情节，却没有揭示任何内容）

步骤 3：设计工具

脚本：voice-check.ts - 生成声音差异问卷 数据：speech-patterns.json - 地域、阶层和个性标记

步骤 4：映射集成关系

• 来自 story-sense 状态 5.5（对话特有的问题）
• 指向 character-arc（声音反映角色成长）
• 指向 worldbuilding（言语反映文化）

步骤 5：生成脚手架

deno run --allow-read --allow-write scripts/scaffold.ts dialogue --type diagnostic

输出持久化

此技能会将主要输出写入文件，让工作成果在不同会话间得以保留。

输出位置发现

开始任何其他工作之前：

1. 检查项目中是否存在 context/output-config.md
2. 如果存在，查找此技能对应的条目
3. 如果文件不存在或没有此技能的条目，先询问用户：
   • “此技能构建会话的输出应保存到哪里？”
   • 建议：将 skills/{cluster}/{skill-name}/ 作为标准技能目录
4. 保存用户的偏好：
   • 如果存在上下文网络，保存到 context/output-config.md
   • 否则保存到项目根目录下的 .skill-builder-output.md

主要输出

对于此技能，需持久化：

• 技能脚手架 - SKILL.md、scripts/、templates/、data/
• 状态定义 - 诊断模型
• 脚本模板 - 生成的实用脚本
• 集成关系图 - 与其他技能的连接

对话与文件

写入文件	保留在对话中
生成的 SKILL.md	问题空间讨论
脚本模板	状态定义迭代
数据文件存根	集成规划
验证结果	实时反馈

文件命名

格式：skills/{cluster}/{skill-name}/（目录结构） 示例：skills/fiction/dialogue/

不要做的事

• 不要在问题状态不明确时构建技能
• 不要在缺少 SKILL.md 文档时创建脚本
• 不要重复已有的技能覆盖范围
• 不要跳过集成关系映射
• 你负责构建框架；由用户决定要创建哪些技能

与其他技能集成

与 list-builder 集成（fiction 集群）

对任何数据文件，使用 list-builder 的质量标准：

• 将技能标记为可投入生产前，验证列表的成熟度
• 遵循维度框架，确保列表具有多样性

跨集群技能

技能可以引用其他集群中的技能：

• 在两个技能中都记录集成关系
• 跨集群时使用完整路径引用

集群约定

在集群内构建技能时：

• 在 frontmatter 中将 cluster 设置为父技能
• 添加映射不同技能间状态的集成表
• 遵循该集群在脚本和数据方面的既定模式