skillkit

第 1 节：意图检测与路由

检测用户意图，并路由到相应的工作流。

意图	关键词	路由至
创建完整技能	"create skill", "build skill", "new skill"	第 2 节
创建子 Agent	"create subagent", "build subagent", "new subagent"	第 6 节
验证	"validate", "check quality"	第 3 节
决策	"Skills vs Subagents", "decide", "which to use"	第 4 节
迁移	"convert", "migrate doc"	第 5 节
单项工具	"validate only", "estimate tokens", "scan"	第 7 节

检测意图后，转到相应章节。

停止条件（必须遵守）：

• 如果多个路由都匹配，或意图不明确：停止，并请用户选择一个路由。
• 在用户确认路由前，不要继续。

**工作流价值：**以研究为基础的方法会在构建前验证设计。 包含检查点的顺序步骤，相比临时创建能达到 9.0/10 以上的质量。

---

第 2 节：创建工作流（双模式）

**前提条件：**已提供技能描述，并且工作区可用。

模式选择（开始时必须完成）

在运行创建流程之前，检测或询问工作流模式。

停止条件（必须遵守）：

• 如果未明确提供模式：停止并询问“你想使用快速模式还是完整模式？”
• 在用户确认模式前，不要继续。

模式	步骤	验证	质量目标	耗时
fast	10	仅结构验证	>=9.0/10	<10 min
full	14	结构验证 + 行为验证	>=9.0/10，且行为验证 >=7.0	<20 min

未明确得知模式时，不允许默认使用任何模式。

工作流 A：快速模式（10 步）

当 .skillkit-mode 包含 fast，或标记不存在时使用。

→ 开始前，请完整阅读 references/section-2-fast-creation-workflow.md。 为该文件中列出的每个步骤创建一项任务，然后按顺序执行。 以下大纲仅为摘要——以参考文件为准。

阶段 1：决策与研究

• 步骤 0：决定方案（decision_helper.py）
• 步骤 1：研究并提出方案
• 步骤 2：用户验证
• 停止条件：停止并请求用户批准，然后再继续步骤 3。

阶段 2：创建

• 步骤 3：初始化技能（init.py skill <name> --mode fast）
• 步骤 4：创建内容

阶段 3：结构验证

• 步骤 5：验证技能（validate_skill.py）——一次调用即可运行结构、安全性和 token 检查

阶段 4：打包

• 步骤 6：渐进式披露检查
• 步骤 7：生成测试（test_generator.py）
• 步骤 8：质量评估（quality_scorer.py）
• 步骤 9：打包（package_skill.py）

工作流 B：完整模式（14 个步骤）

当 .skillkit-mode 的内容为 full 时使用。

→ 开始前，完整阅读 references/section-2-full-creation-workflow.md。 为该文件中列出的每个步骤创建任务，然后按顺序执行。 以下大纲仅为摘要——以参考文件为准。

阶段 1：决策与研究

• 步骤 0：决定方案（decision_helper.py）
• 步骤 1：研究并提出方案
• 步骤 2：用户验证
• 停止条件：暂停并请求用户批准，然后再继续执行步骤 3。

阶段 2：行为基线（相较于快速模式新增）

• 步骤 3（RED）：在没有技能的情况下运行压力场景 → 加载 references/section-2-full-creation-workflow.md → “Full Mode Behavioral Testing Protocol” 部分（必需）
• 步骤 4：记录基线失败

阶段 3：创建

• 步骤 5：初始化技能（init.py skill <name> --mode full）
• 步骤 6：创建内容，以解决基线失败

阶段 4：行为验证（相较于快速模式新增）

• 步骤 7（GREEN）：在有技能的情况下运行场景 → 加载 references/section-2-full-creation-workflow.md → “Full Mode Behavioral Testing Protocol” 部分（必需）
• 步骤 8：修复缺漏

阶段 5：结构验证

• 步骤 9：验证技能（validate_skill.py）——一次调用即可运行结构、安全性和令牌检查

阶段 6：完善（相较于快速模式新增）

• 步骤 10（REFACTOR）：组合压力测试 → 加载 references/section-2-full-creation-workflow.md → “Full Mode Behavioral Testing Protocol” 部分（必需）
• 步骤 11：堵上漏洞

阶段 7：打包

• 步骤 12：质量评估（quality_scorer.py --format json）——行为分数根据步骤 3/7/10 的子 Agent 结果得出，而非来自 --behavioral 标志
• 步骤 13：打包（package_skill.py）

模式检测

优先顺序：

1. 显式标志：--mode fast 或 --mode full
2. 技能标记：.skillkit-mode 文件内容
3. 如果未知：暂停并询问用户选择 fast 或 full

---

第 3 节：验证工作流（概览）

适用场景： 验证现有技能

步骤： 执行验证子集（步骤 3-6）

1. 验证技能——结构、安全性和令牌（validate_skill.py，无需标志）
2. 渐进式披露检查
3. 测试生成（可选）
4. 质量评估（quality_scorer.py）

注意： --security-only 和 --tokens-only 标志可用于第 7 节中的单独工具调用，不用于工作流验证步骤。

详细工作流： 参见 references/section-3-validation-workflow-existing-skill.md

---

第 4 节：决策工作流（概览）

适用场景： 不确定 Skills 是否合适

重要：Agent 必须先创建一个临时 JSON 文件。 decision_helper.py 脚本不接受内联 JSON 字符串——它要求提供 JSON 文件的路径。

逐步调用说明： 参见 references/section-4-decision-workflow-skills-vs-subagents.md

准确度： 最高（90-95% 的置信度）。

流程：

1. 使用 JSON 文件运行 decision_helper.py。
2. 回答交互式问题
3. 接收包含置信度分数的建议
4. 如果建议使用 Skills（置信度 >=75%），则继续
5. 如果置信度 <75% 或建议不确定，则暂停并询问用户是继续、更换方案还是完善输入。

详细工作流： 参见 references/section-4-decision-workflow-skills-vs-subagents.md

---

第 6 节：子 Agent 创建工作流（概览）

适用场景： 创建新的子 Agent（用户明确提出要求，或决策工作流建议创建）

前提条件： 角色定义明确，工作区可用
质量目标： 角色清晰、工作流完整、示例可测试
耗时： 使用模板时少于 15 分钟

8 步流程：

步骤 0：需求与角色定义

• 回答：主要角色是什么？触发条件是什么？需要哪些工具？
• 从预定义列表中选择 subagent_type

步骤 1：初始化 Subagent 文件

• 工具：python scripts/init.py subagent subagent-name --path ~/.claude/agents
• 创建：带模板的 ~/.claude/agents/subagent-name.md
• 重要： Subagent 是单独的 .md 文件（不是目录）
• 停止条件：如果目标文件已存在，则停止并询问是否覆盖、重命名或取消。

步骤 2：定义配置

• 编辑 YAML frontmatter（name、description、type、tools、skills）
• 配置工具权限（尽可能精简，但满足需求）

步骤 3：定义角色与工作流

• 角色定义部分
• 触发条件（何时调用）
• 多阶段工作流

步骤 4：定义响应格式

• 输出结构模板
• 语气与风格指南
• 错误处理

步骤 5：添加示例

• 至少 1 个完整示例
• 输入/处理/输出格式

步骤 6：验证

• 检查 YAML 有效性
• 验证结构
• 检查完整性

步骤 7：测试

• 使用 Task 工具测试调用
• 根据结果迭代

步骤 8：文档与部署

• 创建 README.md
• 在系统中注册
• 停止条件：注册/部署操作前，先征求用户的明确确认。

详细工作流： 参见 references/section-6-subagent-creation-workflow.md

---

第 5 节：迁移工作流（概览）

适用场景： 将文档转换为技能

流程：

1. 决策检查（步骤 0）
2. 迁移分析（migration_helper.py）
3. 创建结构
4. 执行验证步骤（5-8）
5. 打包（步骤 9）

停止条件（必须遵守）：

• 创建结构或执行任何写入/覆盖操作前：征求用户确认。
• 在用户确认前，不得修改文件。

详细工作流： 参见 references/section-5-migration-workflow-doc-to-skill.md

---

第 7 节：单个工具的使用

适用场景： 用户需要单个工具，而非完整工作流

入口： 用户询问特定工具，例如“估算令牌数量”或“安全扫描”

可用工具

验证工具：

python scripts/validate_skill.py skill-name/ --format json

指南：knowledge/tools/14-validation-tools-guide.md

令牌估算器：

python scripts/validate_skill.py skill-name/ --tokens-only --format json

指南：knowledge/tools/15-cost-tools-guide.md

安全扫描器：

python scripts/validate_skill.py skill-name/ --security-only --format json

指南：knowledge/tools/16-security-tools-guide.md

模式检测器：

# Analysis mode with JSON output
python scripts/pattern_detector.py "convert PDF to Word" --format json

# List all patterns
python scripts/pattern_detector.py --list --format json

# Interactive mode (text only)
python scripts/pattern_detector.py --interactive

指南：knowledge/tools/17-pattern-tools-guide.md

决策助手：

# Analyze use case (JSON output - agent-layer default)
python scripts/decision_helper.py --analyze "code review with validation"

# Show decision criteria (JSON output)
python scripts/decision_helper.py --show-criteria --format json

# Text mode for human reading (debugging)
python scripts/decision_helper.py --analyze "description" --format text

指南：knowledge/tools/18-decision-helper-guide.md

测试生成器（v1.2：参数更新）：

python scripts/test_generator.py skill-name/ --test-format pytest --format json

• --test-format：测试框架（pytest/unittest/plain，默认：pytest）
• --format：输出样式（text/json，默认：text）
• 向后兼容：仍可使用旧的 --output 参数（已弃用）

指南：knowledge/tools/19-test-generator-guide.md

技能拆分工具：

python scripts/split_skill.py skill-name/ --format json

指南：knowledge/tools/20-split-skill-guide.md

质量评分器：

python scripts/quality_scorer.py skill-name/ --format json

指南：knowledge/tools/21-quality-scorer-guide.md

迁移助手：

python scripts/migration_helper.py doc.md --format json

指南：knowledge/tools/22-migration-helper-guide.md

Subagent 初始化器（新增）：

python scripts/init.py subagent subagent-name --path /path/to/subagents

指南：references/section-6-subagent-creation-workflow.md

工具输出标准化（v1.0.1+）

所有 9 个工具都支持 --format json。文本模式仍可通过 --format text 使用（向后兼容）。decision_helper 默认使用 JSON，以支持自动化。

JSON 输出结构：

{
  "status": "success" | "error",
  "tool": "tool_name",
  "timestamp": "ISO-8601",
  "data": { /* tool-specific results */ }
}

质量保证增强（v1.2+）

文件与引用验证：

• validate_skill.py 现在会全面检查文件引用（Markdown 链接、代码引用、路径模式）
• package_skill.py 会在打包前验证引用，并检测孤立文件
• 防止已部署的技能中出现失效引用和不完整文件

内容预算控制（v1.2+）：

• 严格限制文件大小：P0 ≤150 行，P1 ≤100 行，P2 ≤60 行
• 实时统计令牌数并显示进度
• 防止文件膨胀；此前这种情况曾导致内容超出目标 4–9 倍

执行规划（v1.2+）：

• P0/P1/P2 优先级划分可防止范围过大
• 为每个文件分配令牌预算，以提高效率
• 研究阶段遵循 Verbalized Sampling 概率阈值（p>0.10）

质量评分器的上下文：

• 评分标准已针对通用技能质量启发式规则进行校准
• 目标：70%+ 为良好，80%+ 为优秀
• 风格评分可能不适用于所有技能类型（教育类与技术类）
• 将其作为参考，并在边缘情况下辅以人工审查

---

第 8 节：模式选择指南

技能类型	建议模式	原因
TDD 或规范类技能	full	必须能在压力下抵制自我合理化
代码模式技能	fast	结构检查通常已足够
API 参考技能	fast	主要考察检索准确性
工作流编排技能	full	复杂流程可从压力检查中获益
调试技术技能	fast	技术精简且方法明确

完整模式会增加行为测试（压力场景）。当规范执行是技能核心目的时，请使用该模式。

---

第 9 节：知识参考地图（概览）

按需加载战略背景信息。

基础概念（文件 01-08）：

• 技能存在的原因及其替代方案
• 技能与子 Agent 的选择框架
• 令牌经济与效率
• 平台限制与安全性
• 何时不应使用技能

应用知识（文件 09-13）：

• 真实案例研究（Rakuten、Box、Notion）
• 技术架构模式
• 采用与测试策略
• 竞争格局分析

工具指南（文件 14-22）：

• 每个自动化脚本对应一份指南
• 使用模式与参数
• JSON 输出格式
• 集成示例

完整参考地图：参见 references/section-7-knowledge-reference-map.md

---

工作流合规性

按顺序遵循工作流。带有门控的顺序步骤可实现 9.0/10+ 的质量。经用户说明理由后，可以偏离流程。

灵活的入口：

• 单个工具（第 7 节）：跳过完整工作流
• 仅验证（第 3 节）：运行验证子集
• 子 Agent（第 6 节）：精简为 8 步的工作流

---

其他资源

需要详细的实现指导时，可按需从 references/ 加载参考文件。