skill-forge-build

技能构建器 — 搭建框架并生成

流程

第 1 步：收集输入

确定要构建什么，输入来源包括：

• 计划文档：/skill-forge plan 的输出（首选）
• 描述：对技能的自然语言描述
• 现有技能：用作基础的技能路径

如果没有计划，先快速规划一遍（询问 3 个关键问题）：

1. 这个技能能做什么？（1-2 句话）
2. 应该有哪些命令？（列表）
3. 是否需要脚本或外部工具？（是/否）

第 2 步：生成 Frontmatter

这是最关键的一步。description 字段决定了技能何时激活。

编写描述的框架：

[Capability statement] + [Detailed capabilities] + [Trigger phrases]

规则：

• 总长度少于 1024 个字符
• 不得包含 XML 尖括号（< >）
• 包含用户可能会说的 5-10 个触发短语
• 如果相关，提及文件类型
• 如果存在过度触发的风险，添加负向触发条件

完整框架请参阅 references/description-guide.md。

第 3 步：编写主 SKILL.md

按照以下模板构建正文：

# [Skill Name] -- [Tagline]

[1-2 sentence overview]

## Quick Reference

| Command | What it does |
|---------|-------------|
| /name cmd1 | Description |
| /name cmd2 | Description |

## Orchestration Logic

[How commands route to sub-skills]
[Decision trees for conditional routing]

## [Domain-Specific Section]

[Core rules, thresholds, quality gates]

## Reference Files

[List of on-demand reference files]

## Sub-Skills

[List of sub-skills with one-line descriptions]

SKILL.md 的关键规则：

• 少于 500 行
• 少于 5000 个 token
• 指令应可操作，避免含糊
• 包含错误处理
• 链接到参考文件，不要将其内容直接写入正文

第 4 步：生成子技能（第 3-4 层）

为每个子技能生成一个 SKILL.md，内容如下：

---
name: parent-child
description: >
  [What it does]. Use when user says "[trigger 1]", "[trigger 2]",
  "[trigger 3]", or "[trigger 4]".
---

子技能正文指南：

• 提供一个工作流的完整自包含指令
• 按名称交叉引用其他子技能，不要直接写入其内容
• 引用父技能 references/ 目录中的共享文件
• 明确说明输入和输出

第 5 步：生成脚本（第 2-4 层）

为每个脚本：

#!/usr/bin/env python3
"""
Purpose: [What this script does]
Input: [Expected input format]
Output: [Expected output format]
Usage: python scripts/script_name.py [args]
"""

import argparse
import json
import sys
from typing import Any


def main(args: argparse.Namespace) -> dict[str, Any]:
    """Main execution function."""
    # Validate inputs
    # Do the work
    # Return structured output
    pass


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="[Script description]")
    parser.add_argument("input", help="[Input description]")
    parser.add_argument("--output", "-o", help="Output file path")
    args = parser.parse_args()

    try:
        result = main(args)
        print(json.dumps(result, indent=2))
    except Exception as e:
        print(json.dumps({"error": str(e)}), file=sys.stderr)
        sys.exit(1)

脚本规则：

• 一个脚本只负责一项职责
• 使用 argparse 提供 CLI 接口
• 输出结构化 JSON
• 提供清晰的错误消息
• 尽可能不使用标准库以外的依赖

第 6 步：生成参考文件

每个参考文件应：

• 聚焦一个主题
• 少于 200 行
• 包含具体示例
• 使用表格说明阈值和规格
• 在父 SKILL.md 中标注“按需加载”

第 7 步：生成 Agent 定义（第 4 层）

Agent 文件使用 YAML frontmatter（与技能不同）：

---
name: [skill-name]-[role]
description: >
  [What this agent analyzes].
  <example>User says: "[trigger]"</example>
model: inherit
color: blue
tools:
  - Read
  - Grep
  - Glob
---

You are a [role] specialist.

## Your Role
[What this agent does]

## Process
1. [Steps...]

## Output Format
Return structured markdown with findings and recommendations.

**与技能的主要区别：**Agent 的 name 长度为 3-50 个字符，description 可以使用 <example> 块；仅适用于 Agent 的字段包括 tools、color、permissionMode、 maxTurns、memory。正文将成为系统提示词（使用第二人称）。

第 8 步：生成安装脚本

创建 install.sh，将文件复制到 ~/.claude/skills/ 和 ~/.claude/agents/。

第 9 步：验证

对生成的技能运行 python scripts/validate_skill.py <path>。 检查主 SKILL.md 中的所有质量门槛。

第 10 步：输出摘要

向用户展示：

1. 生成的文件树
2. 关键文件及其用途
3. 安装说明
4. 建议的测试查询（3 个应触发，3 个不应触发）
5. 后续步骤（测试、迭代、发布）

搭建脚手架命令

如需快速搭建脚手架，请使用：

python scripts/init_skill.py <skill-name> --tier <1-4> --path <output-path>

这会创建完整的目录结构，并填入占位内容。