SkillForge v5.1

从艺术到工程：AI技能创建宣言。

---

问题

AI开发的核心挑战并非缺乏创意，而是将这些创意转化为稳健、可靠技能的过程始终不够规范。当前的方法往往临时拼凑、脆弱且难以扩展，更像一门艺术而非可预测的工程学科。

---

解决方案

质量是内建的，而非事后附加的。

SkillForge是一种方法论，它将严谨性贯穿于整个创建流程的每一个环节，从最初的构思到最终的验证。这是一种根本性的转变——从被动测试转向主动工程化。

---

v5.1 的新特性

v5.1 在 v5.0 上下文高效重设计的基础上，进一步增强了前言元数据支持、钩子指南、验证覆盖以及打包安全性。

上下文高效的基础（v5.0）

v5.0 的基础依然保持不变：上下文窗口是一项公共资源。 SKILL.md 中的每一行都会与用户的实际工作内容产生竞争。

• SKILL.md 从 872 行精简至 313 行（缩减64%）
• 深度解析内容移至 references/ 目录，仅在需要时加载
• 触发条件移至 description 字段，以便提前路由

简化的前言元数据

现在，技能的前言元数据仅包含 name 和 description。其中，description 是主要的触发机制——它决定了技能何时激活，因此所有“何时使用”的信息都应放在该字段中。

---
name: my-skill
description: 这个技能的功能及适用场景。请包含触发情境。
---

自由度设计

一种新的设计理念，根据任务的脆弱性来匹配指令的具体程度：

• 高自由度（文本指导）——当多种方法都可行时
• 中等自由度（伪代码/参数化脚本）——当存在首选模式时
• 低自由度（精确脚本）——当操作非常脆弱且易出错时

脚手架脚本

新增的 init_skill.py 可以创建丰富的技能模板，包含 TODO 占位符、组织模式建议以及示例资源文件：

python scripts/init_skill.py my-new-skill --path ~/.codex/skills

迭代作为正式步骤

迭代现在已融入第三阶段。技能的改进不仅依赖于合成评审小组的审查，更来自于实际使用中的不断优化。

扩展的前言元数据 + 钩子功能（v5.1）

v5.1 扩展了技能元数据的支持与文档说明：

• 前言元数据覆盖范围扩大至 model、context、agent、hooks 和 user-invocable
• 新增针对 PreToolUse、PostToolUse 和 Stop 的钩子集成指南
• 更新了现代技能创作默认设置的模板

验证与打包加固（v5.1）

v5.1 增加了更强的安全保障措施，以确保分发安全：

• 在各个验证脚本中共享统一的验证常量
• 改进了前言元数据的解析，并进行了更严格的结构检查
• 在打包过程中恢复了 .skillignore 文件的强制执行
• 添加了文档安全检查器，用于标记不安全的命令插值模式
• 对打包排除项增加了回归测试覆盖

---

四阶段架构

SkillForge 通过一套严谨且自主的四阶段架构来践行其理念。这一结构确保每项技能在完成之前，都会经历全面的分析、详尽的规格制定、干净的生成以及客观的批准。

---

第0阶段：技能分类

在开始任何创建工作之前，SkillForge 会先分析您的输入，以确定最佳行动方案：

• USE_EXISTING — 现有技能可以完美解决此问题（匹配度 ≥80%）
• IMPROVE_EXISTING — 现有技能接近但需要改进（匹配度 50-79%）
• CREATE_NEW — 无合适匹配，需创建新技能（匹配度 <50%）
• COMPOSE — 需要多个技能协同工作，建议构建技能链

# 以下几种情况均可正常运作——SkillForge 会自动路由：

SkillForge: 创建一个用于自动化代码审查的技能
→ 创建新技能（第1-4阶段）

帮我调试这个 TypeError
→ 推荐调试相关的技能

我是否有处理 Excel 的技能？
→ 搜索并推荐匹配的技能

---

第1阶段：深度分析

在生成任何一行代码之前的最大深度。

每个问题都会被系统地分解为 11种不同的思维视角，并对每个设计决策的自由度进行评估。

这11种视角包括：第一性原理、逆向思维、二阶效应、事前剖析、系统思维、反方论证、约束条件、帕累托法则、根本原因分析、比较分析以及机会成本。

---

第2与第3阶段：规格制定与生成

将深度分析转化为完美的构建。

分析所得的洞察会被编码成结构化的 XML 规格说明书，随后利用全新上下文生成技能。第3阶段现在还增加了一个明确的 迭代步骤——对照规格说明书审查输出结果，找出不足之处并加以完善，然后再提交给评审小组。

---

第4阶段：多智能体合成

专家评审小组必须一致同意才能通过。

生成的技能会被提交给一个由专业智能体组成的评审小组，每个智能体都会依据不同的标准进行评估。只有全体成员一致同意，技能才能通过审核。

评审小组包括：

• 设计/架构智能体——负责评估结构、模式和正确性
• 受众/可用性智能体——负责评估清晰度、可发现性和完整性
• 进化智能体——负责评估技能的持久性、可扩展性以及未来适应能力（需获得 ≥7/10 的评分）
• 脚本智能体（视情况而定）——在存在脚本的情况下，负责验证代码质量

---

进化要求

仅仅保证第一天的质量是不够的。随着技能生态系统的不断发展，系统必须保持可维护性和可扩展性。

---

三个核心原则

原则	实现方式
为智能体而设计	标准化的目录结构、简化的前言元数据、自动化验证
系统化严谨性	四阶段架构、回归式质询、11种思维视角、多智能体合成
面向进化而设计	专门的进化智能体、强制要求≥7/10的持久性评分、自由度评估

---

智能体能力

SkillForge 的设计使得技能能够执行重复性工作、验证输出结果，并在适当情况下支持自主运行。

---

目录结构

skillforge/
├── SKILL.md                    # 主技能定义文件（少于500行）
├── LICENSE                     # MIT许可证
├── references/                 # 需要时加载到上下文中
│   ├── regression-questions.md
│   ├── multi-lens-framework.md
│   ├── specification-template.md
│   ├── evolution-scoring.md
│   ├── synthesis-protocol.md
│   ├── script-integration-framework.md
│   ├── script-patterns-catalog.md
│   ├── degrees-of-freedom.md
│   └── iteration-guide.md
├── assets/                     # 用于输出，从不加载到上下文中
│   └── templates/
│       ├── skill-spec-template.xml
│       ├── skill-md-template.md
│       └── script-template.py
└── scripts/                    # 自动化质量检查流程
    ├── init_skill.py
    ├── triage_skill_request.py
    ├── discover_skills.py
    ├── match_skills.py
    ├── verify_recommendation.py
    ├── validate-skill.py
    ├── quick_validate.py
    └── package_skill.py

关键区别： references/ 文件夹中的内容会加载到上下文中，以指导模型的推理过程。而 assets/ 文件夹中的内容仅用于生成输出，不会被加载到上下文中。

---

安装与使用

# 安装（自动排除仅存在于仓库中的文件，如 README.md）
git clone https://github.com/tripleyak/SkillForge.git /tmp/skillforge

# Codex 安装
cp -r /tmp/skillforge ~/.codex/skills/skillforge
rm -rf ~/.codex/skills/skillforge/{README.md,LICENSE,.git,.gitignore,.skillignore}

# Claude Code 安装
cp -r /tmp/skillforge ~/.claude/skills/skillforge
rm -rf ~/.claude/skills/skillforge/{README.md,LICENSE,.git,.gitignore,.skillignore}

# 或者打包成 .skill 文件（尊重 .skillignore 规则）
python scripts/package_skill.py /tmp/skillforge ./dist

# 完全自动执行
SkillForge: {目标}

# 自然语言激活
为 {目的} 创建技能

# 仅生成规格说明
skillforge --plan-only

# 搭建新技能框架
python scripts/init_skill.py my-skill --path ~/.codex/skills

注意： README.md、LICENSE 和 assets/images/ 仅用于 GitHub 浏览。它们会被 .skillignore 文件排除在 .skill 包之外，因此不应复制到您的技能目录中。

---

系统要求

• Codex CLI 或 Claude Code CLI
• Python 3.8 及以上版本（用于验证和脚本搭建）

---

结论

SkillForge 是一种系统化的高质量、可重复性方法论。

通过将专家分析、严格规范制定以及多智能体同行评审编码为一个完全自主的系统，SkillForge 提供了一个构建下一代强大、可靠且具备进化意识的人工智能技能的蓝图。

它将技能创建从一门艺术转变为一门工程学科。

---

许可证

MIT 许可证 — 详见 LICENSE

---

更改记录

v5.1.0（当前版本）

• 在 SKILL.md 指令和主机路径中增加了 Codex 兼容性
• 增加了 Codex 技能源发现功能（~/.codex/skills），并支持大写 SKILL.md
• 更新了搭建和验证脚本，使用 Codex 路径示例
• 保持与 Claude Code 路径的完全向后兼容
• 添加了关于进化使命、代理能力及目录结构的补充 README 图文说明
• 增加了对扩展 frontmatter 支持的文档（model、context、agent、hooks、user-invocable）
• 在核心文档和参考资料中添加了钩子集成指南
• 恢复了打包流程中 .skillignore 的强制执行
• 增加了用于检查文档安全性的脚本，防止不安全工具负载的插入
• 添加了针对 .skillignore 排除项的打包回归测试

v5.0.0

• 上下文优化设计：SKILL.md 从 872 行缩减至 313 行（减少 64%）
• 简化 frontmatter 至仅包含 name 和 description
• 将触发器移至 description 字段，以便预加载路由
• 引入自由度概念及其参考文档
• 将迭代指南正式纳入第三阶段
• 新增 init_skill.py 搭建脚本
• 更新验证器以适应新的 frontmatter 标准
• 从技能分发包中移除 README（仅限 GitHub 使用）

v4.0.0

• 由 SkillCreator 更名为 SkillForge
• 新增第 0 阶段：通用技能分类
• 引入基于领域的通用匹配机制
• 新增分类、发现、匹配和验证脚本

v3.2.0

• 为代理型技能引入脚本集成框架
• 在合成小组中新增第 4 个脚本代理（条件性）
• 新增第 1D 阶段：自动化分析

v3.0.0

• 完全重新设计为终极元技能
• 引入回归提问循环
• 引入多视角分析框架（11 种模型）
• 新增进化/永恒性核心视角
• 新增多智能体合成小组

SkillForge v5.1 快速上手指南

SkillForge 是一套将 AI 技能（Skill）创作从“艺术”转变为“工程学科”的方法论工具。它通过严格的四阶段架构、多智能体评审和上下文优化设计，确保生成的技能具备高鲁棒性和可演进性。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL)
• Python 版本：Python 3.8 或更高版本（用于验证和脚手架脚本）
• 宿主 CLI 工具（任选其一）：
  • Codex CLI
  • Claude Code CLI
• 网络环境：需能访问 GitHub 仓库以克隆源码。

安装步骤

SkillForge 推荐通过克隆仓库并复制到对应 CLI 的技能目录进行安装。以下是具体操作命令：

1. 克隆仓库

首先将项目克隆到临时目录：

git clone https://github.com/tripleyak/SkillForge.git /tmp/skillforge

2. 部署到 Codex CLI

如果您使用 Codex，执行以下命令将技能复制到配置目录，并自动清理不必要的文档文件：

cp -r /tmp/skillforge ~/.codex/skills/skillforge
rm -rf ~/.codex/skills/skillforge/{README.md,LICENSE,.git,.gitignore,.skillignore}

3. 部署到 Claude Code CLI

如果您使用 Claude Code，执行以下命令：

cp -r /tmp/skillforge ~/.claude/skills/skillforge
rm -rf ~/.claude/skills/skillforge/{README.md,LICENSE,.git,.gitignore,.skillignore}

注意：README.md、LICENSE 和图片资源仅用于 GitHub 浏览，已通过 .skillignore 排除，不应包含在实际运行的技能目录中。

4. (可选) 打包为 .skill 文件

如需分发生成独立的 .skill 包（自动遵守忽略规则）：

python scripts/package_skill.py /tmp/skillforge ./dist

基本使用

安装完成后，SkillForge 会自动集成到您的 AI 助手工作流中。您可以通过自然语言直接调用其核心功能。

1. 创建新技能

直接使用自然语言描述目标，SkillForge 会自动进入“阶段 0：技能分流”，判断是复用现有技能、改进现有技能还是创建新技能。

示例：创建一个自动化代码审查技能

SkillForge: create a skill for automated code review

系统响应：若匹配度低于 50%，将自动启动完整的四阶段流程（深度分析 -> 规范定义 -> 生成 -> 多智能体合成）来创建新技能。

2. 查询与推荐

询问是否存在特定领域的技能，系统会搜索并推荐最佳匹配项。

示例：查询 Excel 相关技能

do I have a skill for Excel?

3. 辅助调试

直接提出具体问题，系统会推荐相关的调试技能。

示例：调试类型错误

help me debug this TypeError

4. 手动构建技能脚手架

如果您希望手动初始化一个新的技能模板（包含待办事项占位符和组织结构建议），可以使用提供的 Python 脚本：

python scripts/init_skill.py my-new-skill --path ~/.codex/skills

注：请将 ~/.codex/skills 替换为您实际使用的技能目录路径（如 ~/.claude/skills）。

5. 仅生成规划

如果您只想查看技能生成的规范计划而不立即执行生成：

skillforge --plan-only