skill-builder by jwynia/agent-skills
npx skills add https://github.com/jwynia/agent-skills --skill skill-builder你帮助创建遵循既定模式的新智能体技能。你的角色是指导技能设计、生成脚手架并验证完整性。
技能是带有工具的诊断框架,而非功能清单。
一项技能诊断一个问题空间,识别状态,并提供干预措施。脚本提供随机化和结构;LLM 提供判断。各司其职。
每个技能都包含以下组件:
skill-name/
├── SKILL.md # 诊断框架 + 文档
├── scripts/ # Deno TypeScript 工具
│ └── *.ts
├── data/ # JSON 数据集(如果需要)
│ └── *.json
└── references/ # 支持文档(可选)
└── *.md
---
name: skill-name
description: 以动作动词开头的单句描述
license: MIT
metadata:
author: your-name
version: "1.0"
maturity_score: [0-20] # 可选
---
# 技能名称:副标题
你 [角色描述]。你的角色是 [具体功能]。
## 核心原则
**抓住诊断本质的加粗陈述。**
## 状态
### 状态 X1:名称
**症状:** 用户注意到的现象
**关键问题:** 需要询问什么
**干预措施:** 应用什么框架/工具
[为每个状态重复]
## 诊断流程
1. 第一步
2. 第二步
...
## 关键问题
### 对于类别 A
- 问题?
- 问题?
## 反模式
### [问题名称]
**问题:** 描述
**修复:** 解决方案
## 可用工具
### script.ts
描述其功能。
```bash
deno run --allow-read scripts/script.ts [args]
```
## 示例交互
**用户:** "问题描述"
**你的方法:**
1. 行动
2. 行动
## 你不做什么
- 边界列表
- 技能从不做的事情
## 集成图
### 入向(来自其他技能)
| 来源技能 | 来源状态 | 导致状态 |
|--------------|--------------|----------------|
| [skill] | [state] | [state] |
### 出向(到其他技能)
| 本状态 | 导致技能 | 目标状态 |
|------------|----------------|--------------|
| [state] | [skill] | [state] |
### 互补技能
| 技能 | 关系 |
|-------|--------------|
| [skill] | [它们如何关联] |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
目的: 识别问题,推荐干预措施 模式: 状态 → 问题 → 干预措施 示例: story-sense, worldbuilding, conlang
关键特征:
目的: 根据参数生成结构化输出 模式: 参数 → 生成 → 输出 示例: story-sense 中的函数,conlang 中的音系学
关键特征:
目的: 支持其他技能,构建基础设施 模式: 输入 → 分析/转换 → 报告 示例: list-builder, skill-builder
关键特征:
目的: 将多个技能协调成自主工作流 模式: 输入 → 多轮评估循环 → 精炼输出 示例: chapter-drafter
关键特征:
必需的前置元数据:
metadata:
orchestrates: # 要协调的子技能
- skill-one
- skill-two
pass_order: # 评估顺序
- skill-one
- skill-two
pass_weights: # 每个技能的权重(总和为 100)
skill-one: 50
skill-two: 50
max_iterations: 3 # 每轮迭代限制
global_max_iterations: 50 # 总上限
有关架构细节,请参阅 skills/fiction/orchestrators/README.md。
技能按照与框架 24 分制平行的 24 分制进行评估。
| 检查项 | 分数 | 标准 |
|---|---|---|
| 核心原则 | 1 | 抓住诊断本质的加粗陈述 |
| 状态 | 2 | 诊断技能有 3-7 个状态(生成器/实用技能不适用) |
| 状态组件 | 2 | 每个状态都有症状、关键问题、干预措施 |
| 诊断流程 | 1 | 记录了逐步流程 |
| 反模式 | 2 | 3 个以上具有问题/修复结构的反模式 |
| 示例 | 2 | 2 个以上展示技能应用的完整示例 |
| 边界 | 1 | 包含 "你不做什么" 部分 |
| 检查项 | 分数 | 标准 |
|---|---|---|
| 自包含 | 1 | 无需阅读其他技能即可使用 |
| 声明类型+模式 | 1 | 必需的前置元数据字段存在 |
| 状态命名 | 1 | 一致的状态前缀匹配技能缩写 |
| 集成映射 | 1 | 记录与其他技能的连接 |
| 工具文档化 | 1 | 所有脚本都有使用文档 |
| 检查项 | 分数 | 标准 |
|---|---|---|
| 输出持久性 | 1 | 定制化(非样板)的持久化部分 |
| 渐进式披露 | 1 | 用于快速查阅的快速参考部分 |
| 决策树 | 1 | 常见场景的路由逻辑 |
| 可操作性 | 1 | 每个诊断都有清晰的后续步骤 |
| 检查项 | 分数 | 标准 |
|---|---|---|
| 推理要求 | 1 | 指定何时扩展思考对任务有益 |
| 执行策略 | 1 | 记录顺序工作与可并行工作 |
| 子智能体指导 | 1 | 识别何时生成专门的子智能体 |
| 上下文管理 | 1 | 记录令牌占用和优化策略 |
| 级别 | 分数 | 描述 |
|---|---|---|
| 草案 | 0-8 | 缺少核心元素 |
| 开发中 | 9-14 | 功能正常但不完整 |
| 稳定 | 15-20 | 可用于生产 |
| 经过实战检验 | 21-24 | 拥有案例研究 + 完整的执行智能 |
每个技能必须在前置元数据中声明其类型:
metadata:
| 类型 | 定义 | 必需部分 |
|---|---|---|
| diagnostic | 识别问题,推荐干预措施 | 状态、诊断流程、反模式 |
| generator | 根据参数生成结构化输出 | 参数、生成逻辑、输出格式 |
| utility | 支持其他技能,构建基础设施 | 流程、模板、验证 |
| orchestrator | 将多个技能协调成自主工作流 | 编排循环、轮次标准、迭代限制 |
每个技能必须在前置元数据中声明其模式:
metadata:
| 模式 | 定义 | 用户关系 |
|---|---|---|
| diagnostic | 识别问题状态并推荐 | 智能体诊断,用户决定 |
| assistive | 指导但不生成内容 | 智能体提问,用户创建 |
| collaborative | 与用户协作 | 智能体生成,用户指导 |
| evaluative | 评估现有工作 | 智能体评审,用户回应 |
| application | 在实时上下文中操作 | 智能体运行,用户参与 |
| generative | 根据参数创建输出 | 智能体生成,用户选择 |
复合模式(例如 diagnostic+generative)在技能执行多种功能时允许使用。
metadata:
maturity_score: 15
状态必须遵循一致的命名模式:
约定: {ABBREV}{NUMBER}: {状态名称}
规则:
标准缩写:
| 技能 | 缩写 | 示例 |
|---|---|---|
| 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 | (编排器 - 使用轮次分数,而非状态) |
新技能应声明一个未使用的缩写并在此处记录。
每个技能必须记录其与其他技能的连接。
必需格式:
## 集成图
### 入向(来自其他技能)
| 来源技能 | 来源状态 | 导致状态 |
|--------------|--------------|----------------|
| story-sense | SS5:无目的的剧情 | D4:无潜台词 |
### 出向(到其他技能)
| 本状态 | 导致技能 | 目标状态 |
|------------|----------------|--------------|
| D6:节奏不匹配 | scene-sequencing | SQ2:缺少续集 |
### 互补技能
| 技能 | 关系 |
|-------|--------------|
| character-arc | 声音反映转变 |
| worldbuilding | 言语反映文化 |
要求:
技能应记录它们如何被 Claude Code 最佳执行。
记录何时扩展思考(ultrathink)对技能有益:
## 推理要求
### 标准推理
- 初始诊断和症状匹配
- 简单的状态识别
- 脚本执行和输出解释
### 扩展推理(ultrathink)
在以下情况使用扩展思考:
- 多框架综合 - [原因:需要同时持有多个模型]
- 复杂的世界构建系统 - [原因:许多相互依赖的变量]
- 跨状态的级联分析 - [原因:二阶效应会叠加]
**触发短语:** "深度分析"、"全面审查"、"多框架综合"
为什么这很重要: LLM 具有完成奖励偏差——它们会匆忙奔向可见的目标。扩展思考在输出前分配推理时间,提高了复杂任务的质量。这符合 LLM 流程设计框架的原则。
记录顺序工作与并行工作:
## 执行策略
### 顺序(默认)
- 诊断必须在干预前完成
- 状态识别在框架选择之前
### 可并行化
- 多个脚本运行(熵 + 函数)可以并发运行
- 跨多个框架的研究可以并行化
- 在以下情况使用:任务独立且可以合并结果
### 子智能体候选
| 任务 | 智能体类型 | 何时生成 |
|------|------------|---------------|
| 代码库探索 | Explore | 当技能需要项目上下文时 |
| 框架研究 | general-purpose | 当需要综合 3 个以上框架时 |
记录令牌使用和优化:
## 上下文管理
### 近似令牌占用
- **技能基础:** ~2k 令牌
- **包含完整状态定义:** ~4k 令牌
- **包含内联脚本:** ~8k 令牌(除非调试,否则避免)
### 上下文优化
- 按需加载脚本,而不是内联包含
- 按名称引用框架文档,而不是嵌入
- 对常见情况使用快速参考部分
### 当上下文紧张时
- 优先处理:当前状态诊断和立即干预
- 推迟处理:集成图、完整的反模式列表
- 丢弃:脚本源代码、历史示例
每个技能必须记录常见错误。
最低要求:
必需结构:
### {反模式名称}
**模式:** 问题行为的表现形式
**问题:** 为什么这会造成危害
**修复:** 如何解决它
**检测:** [可选] 如何识别这种情况正在发生
常见反模式类别:
| 类别 | 示例名称 |
|---|---|
| 范围蔓延 | The Kitchen Sink, The Mission Creep |
| 缺乏深度 | The Surface Treatment, The Checklist |
| 错误层级 | The Bottom-Up Edit, The Premature Optimization |
| 用户关系 | The Puppet Master, The Passive Recipient |
| 集成 | The Orphan Skill, The Boundary Ignorer |
#!/usr/bin/env -S deno run --allow-read
/**
* 脚本名称
*
* 描述其功能。
*
* 用法:
* deno run --allow-read script.ts [args]
*/
// === 接口 ===
interface ResultType {
field: string;
// ...
}
// === 数据 ===
const DATA: Record<string, string[]> = {
category: ["item1", "item2"],
};
// === 实用函数 ===
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));
}
// === 核心逻辑 ===
function generate(/* params */): ResultType {
// 生成逻辑
}
// === 格式化 ===
function formatResult(result: ResultType): string {
const lines: string[] = [];
// 格式化输出
return lines.join("\n");
}
// === 主函数 ===
function main(): void {
const args = Deno.args;
// 帮助
if (args.includes("--help") || args.includes("-h")) {
console.log(`脚本名称
用法:
deno run --allow-read script.ts [选项]
选项:
--flag 描述
--json 输出为 JSON
`);
Deno.exit(0);
}
// 解析参数
const flagIndex = args.indexOf("--flag");
const flagValue = flagIndex !== -1 ? args[flagIndex + 1] : null;
const jsonOutput = args.includes("--json");
// 跳过用于位置参数检测的索引
const skipIndices = new Set<number>();
if (flagIndex !== -1) {
skipIndices.add(flagIndex);
skipIndices.add(flagIndex + 1);
}
// 查找位置参数
let positionalArg: string | null = null;
for (let i = 0; i < args.length; i++) {
if (!args[i].startsWith("--") && !skipIndices.has(i)) {
positionalArg = args[i];
break;
}
}
// 生成
const result = generate(/* params */);
// 输出
if (jsonOutput) {
console.log(JSON.stringify(result, null, 2));
} else {
console.log(formatResult(result));
}
}
main();
// 1. 首先检查帮助
if (args.includes("--help") || args.includes("-h")) { ... }
// 2. 解析 --flag 值对
const flagIndex = args.indexOf("--flag");
const flagValue = flagIndex !== -1 ? args[flagIndex + 1] : defaultValue;
// 3. 布尔标志
const boolFlag = args.includes("--bool");
// 4. 跟踪已使用的索引
const skipIndices = new Set<number>();
if (flagIndex !== -1) {
skipIndices.add(flagIndex);
skipIndices.add(flagIndex + 1);
}
// 5. 查找位置参数
for (let i = 0; i < args.length; i++) {
if (!args[i].startsWith("--") && !skipIndices.has(i)) {
positionalArg = args[i];
break;
}
}
// 对于外部 JSON 文件
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);
}
}
// 相对于脚本的路径
const scriptDir = new URL(".", import.meta.url).pathname;
const dataPath = `${scriptDir}../data/file.json`;
// 始终支持多种格式
if (jsonOutput) {
console.log(JSON.stringify(result, null, 2));
} else if (briefOutput) {
console.log(formatBrief(result));
} else {
console.log(formatFull(result));
}
{
"list_name": [
"具有足够细节以激发想法的具体项目",
"另一个理想长度为 20-60 字符的项目",
"项目应该是具体的,而不是模糊的"
]
}
质量阈值:
{
"_meta": {
"description": "此数据的用途",
"usage": "如何使用它",
"source": "来源(可选)"
},
"category": {
"item_name": {
"property": "value",
"frequency": 0.85,
"tags": ["tag1", "tag2"]
}
}
}
{
"tier_universal": {
"description": "几乎在所有情况下都能找到",
"items": { "a": { "frequency": 0.95 }, "b": { "frequency": 0.90 } }
},
"tier_common": {
"description": "在大多数情况下能找到",
"items": { "c": { "frequency": 0.70 } }
},
"tier_rare": {
"description": "不常见但有记录",
"items": { "d": { "frequency": 0.15 } }
}
}
创建新技能时:
运行 validate-skill.ts 以检查:
生成技能目录结构和模板文件。
# 创建新技能脚手架
deno run --allow-read --allow-write scripts/scaffold.ts skill-name
# 指定类型
deno run --allow-read --allow-write scripts/scaffold.ts skill-name --type diagnostic
# 预览而不写入
deno run --allow-read scripts/scaffold.ts skill-name --dry-run
检查技能完整性和模式符合性。
# 验证一个技能
deno run --allow-read scripts/validate-skill.ts ../worldbuilding
# 验证 fiction 集群中的所有技能
deno run --allow-read scripts/validate-skill.ts --all
# 用于 CI 的 JSON 输出
deno run --allow-read scripts/validate-skill.ts ../conlang --json
问题: 技能是一个它能做的事情的列表,而不是一个诊断框架。 修复: 围绕问题状态重构。用户卡在什么地方?
问题: 技能试图做太多事情,覆盖多个问题领域。 修复: 拆分成专注的技能。一个技能 = 一个诊断空间。
问题: 脚本存在但没有 SKILL.md 解释何时使用它。 修复: 每个脚本都属于一个有文档化目的的技能。
问题: 技能不引用其他技能,也不被其他技能引用。 修复: 添加集成部分。映射到/来自其他技能的状态转换。
问题: 技能复制了另一个技能的状态,但使用了不同的名称。 修复: 合并或明确区分问题空间。
本节记录此技能可以可靠验证的内容与需要人工判断的内容。有关预言机的背景,请参阅 organization/architecture/context-packet-architecture.md。
{ABBREV}{N}: Name 模式(高置信度)| 脚本 | 验证内容 | 置信度 |
|---|---|---|
| validate-skill.ts | 跨完整性/质量/可用性的 20 分成熟度评分 | 结构方面高,语义方面低 |
| scaffold.ts | 生成的文件匹配预期结构 | 高 |
validate-skill.ts 脚本:
本节记录输出如何持久化并为未来的会话提供信息。有关反馈循环的背景,请参阅 organization/architecture/context-packet-architecture.md。
skills/{cluster}/{skill-name}/(目录结构)本节记录前提条件和边界。有关约束的背景,请参阅 organization/architecture/context-packet-architecture.md。
此技能被误用的迹象:
请求: "创建一个用于诊断对话问题的技能"
对话问题与场景排序(结构)和角色弧(转变)不同。这是关于角色如何说话的问题。
脚本:voice-check.ts - 生成声音区分问卷 数据:speech-patterns.json - 地区、阶级、个性标记
deno run --allow-read --allow-write scripts/scaffold.ts dialogue --type diagnostic
此技能将主要输出写入文件,以便工作在不同会话间持久化。
在进行任何其他工作之前:
context/output-config.mdskills/{cluster}/{skill-name}/ 作为标准技能位置context/output-config.md 中.skill-builder-output.md 中对于此技能,持久化:
| 写入文件 | 保留在对话中 |
|---|---|
| 生成的 SKILL.md | 关于问题空间的讨论 |
| 脚本模板 | 状态定义的迭代 |
| 数据文件存根 | 集成规划 |
| 验证结果 | 实时反馈 |
模式:skills/{cluster}/{skill-name}/(目录结构) 示例:skills/fiction/dialogue/
对任何数据文件使用 list-builder 质量标准:
技能可以引用其他集群中的技能:
在集群内构建技能时:
cluster 为父技能每周安装次数
224
仓库
GitHub 星标数
37
首次出现
2026年1月20日
安全审计
安装在
opencode203
codex194
gemini-cli194
github-copilot189
cursor181
amp173
You help create new agent skills that follow established patterns. Your role is to guide skill design, generate scaffolding, and validate completeness.
Skills are diagnostic frameworks with tools, not feature checklists.
A skill diagnoses a problem space, identifies states, and provides interventions. Scripts provide randomization and structure; the LLM provides judgment. Each does what it's best at.
Every skill has these components:
skill-name/
├── SKILL.md # Diagnostic framework + documentation
├── scripts/ # Deno TypeScript tools
│ └── *.ts
├── data/ # JSON datasets (if needed)
│ └── *.json
└── references/ # Supporting documentation (optional)
└── *.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] |
Purpose: Identify problems, recommend interventions Pattern: States → Questions → Interventions Examples: story-sense, worldbuilding, conlang
Key characteristics:
Purpose: Produce structured output from parameters Pattern: Parameters → Generation → Output Examples: Functions in story-sense, phonology in conlang
Key characteristics:
Purpose: Support other skills, build infrastructure Pattern: Input → Analysis/Transformation → Report Examples: list-builder, skill-builder
Key characteristics:
Purpose: Coordinate multiple skills into autonomous workflows Pattern: Input → Multi-Pass Evaluation Loop → Polished Output Examples: chapter-drafter
Key characteristics:
Required 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
See skills/fiction/orchestrators/README.md for architectural details.
Skills are evaluated on a 24-point scale parallel to the framework 24-point system.
| Check | Points | Criteria |
|---|---|---|
| Core Principle | 1 | Bold statement capturing diagnostic essence |
| States | 2 | 3-7 states for diagnostic skills (N/A for generator/utility) |
| State Components | 2 | Symptoms, Key Questions, Interventions for each state |
| Diagnostic Process | 1 | Step-by-step process documented |
| Anti-Patterns | 2 | 3+ anti-patterns with Problem/Fix structure |
| Examples | 2 | 2+ worked examples showing skill application |
| Boundaries | 1 | "What You Do NOT Do" section |
| Check | Points | Criteria |
|---|---|---|
| Self-Contained | 1 | Can be used without reading other skills |
| Type+Mode Declared | 1 | Required frontmatter fields present |
| State Naming | 1 | Consistent state prefix matching skill abbreviation |
| Integration Map | 1 | Documents connections to other skills |
| Tools Documented | 1 | All scripts have usage documentation |
| Check | Points | Criteria |
|---|---|---|
| Output Persistence | 1 | Customized (not boilerplate) persistence section |
| Progressive Disclosure | 1 | Quick reference section for at-a-glance use |
| Decision Tree | 1 | Routing logic for common scenarios |
| Actionability | 1 | Clear next steps for each diagnosis |
| Check | Points | Criteria |
|---|---|---|
| Reasoning Requirements | 1 | Specifies when extended thinking benefits the task |
| Execution Strategy | 1 | Documents sequential vs. parallelizable work |
| Subagent Guidance | 1 | Identifies when to spawn specialized subagents |
| Context Management | 1 | Documents token footprint and optimization strategies |
| Level | Score | Description |
|---|---|---|
| Draft | 0-8 | Missing core elements |
| Developing | 9-14 | Functional but incomplete |
| Stable | 15-20 | Production-ready |
| Battle-Tested | 21-24 | Has case studies + full execution intelligence |
Every skill must declare its type in frontmatter:
metadata:
| Type | Definition | Required Sections |
|---|---|---|
| diagnostic | Identifies problems, recommends interventions | States, Diagnostic Process, Anti-Patterns |
| generator | Produces structured output from parameters | Parameters, Generation Logic, Output Formats |
| utility | Supports other skills, builds infrastructure | Process, Templates, Validation |
| orchestrator | Coordinates multiple skills into autonomous workflows | Orchestration Loop, Pass Criteria, Iteration Limits |
Every skill must declare its mode in frontmatter:
metadata:
| Mode | Definition | User Relationship |
|---|---|---|
| diagnostic | Identifies problem states and recommends | Agent diagnoses, user decides |
| assistive | Guides without producing content | Agent asks questions, user creates |
| collaborative | Works alongside user | Agent produces, user guides |
| evaluative | Assesses existing work | Agent reviews, user responds |
| application | Operates in real-time context | Agent runs, user participates |
| generative | Creates output from parameters | Agent produces, user selects |
Compound modes (e.g., diagnostic+generative) are allowed when skills perform multiple functions.
metadata:
maturity_score: 15
States must follow a consistent naming pattern:
Convention: {ABBREV}{NUMBER}: {State Name}
Rules:
Standard Abbreviations:
| Skill | Abbreviation | Example |
|---|---|---|
| story-sense | SS | State SS1: Concept Without Foundation |
| dialogue | D | State D1: Identical Voices |
| conlang | L | State L1: No Language |
| worldbuilding | W | State W1: Backdrop World |
| revision | R | State R1: Overwhelmed |
| endings | E | State E1: Arbitrary Ending |
| character-arc | CA | State CA1: Static Character |
| scene-sequencing | SQ | State SQ1: Scene-Only Pacing |
| brainstorming | B | State B1: Convergent Ideas |
| research |
New skills should claim an unused abbreviation and document it here.
Every skill must document its connections to other skills.
Required Format:
## 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 |
Requirements:
Skills should document how they're best executed by Claude Code.
Document when extended thinking (ultrathink) benefits the skill:
## 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"
Why this matters: LLMs have a completion reward bias—they rush toward visible goals. Extended thinking allocates reasoning time before output, improving quality on complex tasks. This aligns with the LLM Process Design Framework principle.
Document sequential vs. parallel work:
## 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 |
Document token usage and optimization:
## 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
Every skill must document common mistakes.
Minimum Requirements:
Required Structure:
### 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
Common Anti-Pattern Categories:
| Category | Example Names |
|---|---|
| Scope Creep | The Kitchen Sink, The Mission Creep |
| Missing Depth | The Surface Treatment, The Checklist |
| Wrong Level | The Bottom-Up Edit, The Premature Optimization |
| User Relationship | The Puppet Master, The Passive Recipient |
| Integration | The Orphan Skill, The Boundary Ignorer |
#!/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"
]
}
Quality thresholds:
{
"_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 } }
}
}
When creating a new skill:
Run validate-skill.ts to check:
Generates skill directory structure and template files.
# 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
Checks skill completeness and pattern conformance.
# 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
Problem: Skill is a list of things it can do, not a diagnostic framework. Fix: Restructure around problem states. What are users stuck on?
Problem: Skill tries to do too much, covers multiple problem domains. Fix: Split into focused skills. One skill = one diagnostic space.
Problem: Script exists but no SKILL.md explains when to use it. Fix: Every script belongs to a skill with documented purpose.
Problem: Skill doesn't reference or get referenced by other skills. Fix: Add integration section. Map state transitions to/from other skills.
Problem: Skill duplicates another skill's states with different names. Fix: Merge or clearly differentiate the problem spaces.
This section documents what this skill can reliably verify vs. what requires human judgment. See organization/architecture/context-packet-architecture.md for background on oracles.
{ABBREV}{N}: Name pattern (High confidence)| Script | Verifies | Confidence |
|---|---|---|
| validate-skill.ts | 20-point maturity scoring across Completeness/Quality/Usability | High for structure, Low for semantics |
| scaffold.ts | Generated files match expected structure | High |
The validate-skill.ts script:
This section documents how outputs persist and inform future sessions. See organization/architecture/context-packet-architecture.md for background on feedback loops.
skills/{cluster}/{skill-name}/ (directory structure)This section documents preconditions and boundaries. See organization/architecture/context-packet-architecture.md for background on constraints.
Signs this skill is being misapplied:
Request: "Create a skill for diagnosing dialogue problems"
Dialogue problems are distinct from scene-sequencing (structure) and character-arc (transformation). This is about how characters speak.
Script: voice-check.ts - generates voice differentiation questionnaire Data: speech-patterns.json - regional, class, personality markers
deno run --allow-read --allow-write scripts/scaffold.ts dialogue --type diagnostic
This skill writes primary output to files so work persists across sessions.
Before doing any other work:
context/output-config.md in the projectskills/{cluster}/{skill-name}/ as the standard skill locationcontext/output-config.md if context network exists.skill-builder-output.md at project root otherwiseFor this skill, persist:
| Goes to File | Stays in Conversation |
|---|---|
| Generated SKILL.md | Discussion of problem space |
| Script templates | State definition iteration |
| Data file stubs | Integration planning |
| Validation results | Real-time feedback |
Pattern: skills/{cluster}/{skill-name}/ (directory structure) Example: skills/fiction/dialogue/
Use list-builder quality criteria for any data files:
Skills can reference skills in other clusters:
When building skills within a cluster:
cluster in frontmatter to the parent skillWeekly Installs
224
Repository
GitHub Stars
37
First Seen
Jan 20, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode203
codex194
gemini-cli194
github-copilot189
cursor181
amp173
agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试
147,400 周安装
Next.js TypeScript 最佳实践:性能优化、代码规范与安全架构指南
293 周安装
Spec-Kit技能:基于宪法的规范驱动开发工作流,7阶段GitHub功能开发指南
294 周安装
Seaborn 统计可视化库教程:Python 数据可视化与多变量分析指南
296 周安装
InstantDB 完整指南:现代 Firebase 替代方案,内置实时数据库与权限管理
295 周安装
AI研究查询工具 - 实时学术文献、技术文档与统计数据查找,智能模型选择
299 周安装
Next.js 16+ App Router 开发指南:服务器组件、缓存与路由配置
297 周安装
| RS |
| State RS1: No Research |
| requirements-analysis | RA | State RA1: Vague Requirements |
| system-design | SD | State SD1: No Architecture |
| chapter-drafter | CD | (Orchestrator - uses pass scores, not states) |