Skillify：自动化将任意代码库转化为AI智能体可调用技能

1. 项目概述：Skillify，让任意代码库成为AI智能体技能

在AI智能体（AI Agent）的开发与集成领域，一个长期存在的痛点是如何将现有的、功能各异的代码库快速、标准化地转化为可以被智能体平台调用的“技能”（Skill）。想象一下，你手头有一个功能强大的Python脚本、一个Node.js工具链，或者一个完整的Rust项目，你想让一个AI智能体能够理解并使用它，就像调用一个内置函数一样简单。传统做法需要你手动编写大量的适配器代码、定义输入输出接口、撰写使用说明——这个过程不仅繁琐，而且极易出错，更别提不同项目间的标准化问题了。

Skillify正是为了解决这个痛点而生的自动化工具。它的核心使命是“Transform any codebase into an OpenClaw skill”，即将任意代码库转化为符合OpenClaw规范的技能。OpenClaw是一个专注于构建可验证、可审计的智能体基础设施的框架，其“技能”是智能体执行任务的基本单元。Skillify通过分析目标代码库的结构、依赖和文档，自动生成技能所需的所有包装文件，包括标准化的输入输出契约、技能说明文档以及必要的启动脚本。这意味着，开发者或智能体构建者无需深入理解每个代码库的内部细节，就能将其无缝集成到一个更大的智能体工作流中。

这个工具的价值在于其自动化与标准化。它消除了手动包装的重复劳动，确保了所有技能都遵循统一的接口规范，从而使得智能体能够以一致、可靠的方式调用各种外部能力。无论是用于自动化构建、代码生成、数据分析还是系统运维，Skillify都能将散落的工具快速组装成智能体可指挥的“技能军团”。

2. 核心原理与设计思路拆解

要理解Skillify如何工作，我们需要拆解其将一个原始代码库转化为标准化技能所经历的四个关键阶段。这背后是一套对软件项目结构和智能体交互范式的深刻理解。

2.1 阶段一：项目结构与意图解析

Skillify的第一步是扮演一个“代码库侦探”。它不关心代码的具体业务逻辑，而是专注于回答几个元问题：这是一个什么类型的项目？它的入口在哪里？它依赖什么环境？

项目类型检测是基础。Skillify维护了一个轻量级的检测表，通过寻找项目根目录下的标志性文件来快速判断：

• Python: 查找pyproject.toml,setup.py,requirements.txt。
• Node.js: 查找package.json。
• Rust: 查找Cargo.toml。
• Go: 查找go.mod。
• 通用/容器化: 查找Dockerfile。

这种基于约定（Convention）的检测方式效率极高，它利用了不同语言生态的标准实践。检测结果不仅用于后续的依赖处理，也帮助Skillify理解如何为这个技能生成合适的运行环境指令。

入口点推断是关键。一个代码库可能通过多种方式启动，比如一个Python的main.py，一个Node.js的index.js，或者通过命令行参数调用的模块（如python -m package.module）。Skillify会扫描项目结构，尝试识别出最可能的执行入口。对于更复杂的项目（如包含多个子命令的CLI工具），它可能会在生成的包装脚本中提供参数透传机制，将智能体的指令转化为对原始代码库的正确调用。

2.2 阶段二：文档与上下文提取

一个对智能体友好的技能，必须自带说明书。Skillify会主动提取代码库中的文档，将其转化为技能知识库的一部分。

它主要抓取两类文档：

1. 项目级文档：如README.md。这份文件通常包含了项目的概述、安装步骤和基础用法，是智能体了解该技能“是什么”和“能干什么”的第一手资料。
2. API/接口文档：如API.md或代码中生成的文档目录。这些文档详细说明了函数、类或接口的调用方式、参数和返回值，对于智能体精确使用该技能至关重要。

这些提取的文档会被规整地放置在生成技能目录的references/文件夹下。这样，当智能体（或其背后的编排器）需要了解该技能的详细信息时，可以直接查阅这个标准化的知识库，而无需去原始仓库漫无目的地搜索。

2.3 阶段三：技能契约（Wrapper Contract）生成

这是Skillify最核心的贡献——定义技能与智能体之间清晰、无歧义的通信协议。智能体不能像人类一样通过自然语言模糊地调用一个脚本，它需要一个机器可读的、强类型的契约。

Skillify生成的“包装器契约”体现在两个核心文件上：

1. 标准化输入 (input/request.json)这个文件定义了智能体调用技能时必须提供的信息。一个典型的契约包含：

• command: 要执行的具体命令或操作（例如"build","analyze","deploy"）。这对应了原始代码库可能支持的不同模式或子命令。
• args: 一个字典，包含该命令所需的所有参数（例如{"spec": "Build a todo app", "framework": "react"}）。
• project_dir: 一个关键字段，指定技能操作的工作空间路径。这确保了技能的运行是上下文相关的，并且其输出可以放置在正确的位置。

2. 标准化输出 (output/result.json)这个文件定义了技能执行完毕后必须返回的标准化报告。它通常包括：

• status: 执行状态（"ok","error"），让调用者立即知晓成败。
• artifacts: 一个数组，列出本次执行产生的所有“工件”（如生成的文件、报告路径）。这为下游技能或智能体提供了明确的输出抓手。
• summary: 一段人类可读的文本摘要，描述执行了哪些操作。

通过这个契约，任何智能体编排器（如OpenClaw）都可以用完全相同的方式调用任何由Skillify生成的技能，就像调用一个具有统一函数签名的库一样。

2.4 阶段四：技能元数据与集成准备

最后，Skillify会生成技能的“身份证”和“启动器”。

SKILL.md文件是技能的元数据说明书。它通常包含YAML格式的Frontmatter，用于声明技能的名称、版本、作者、所需环境等。更重要的是，它包含了给AI智能体看的自然语言指令，例如：“这是一个代码生成工具，当你需要根据规范创建项目骨架时使用我。调用时，请在args中提供spec参数。” 这份文件是连接机器契约与AI理解的桥梁。

包装脚本（如scripts/entrypoint.py）是契约的具体实现。这个脚本充当了适配器（Adapter）的角色，它的职责是：

1. 读取标准化的input/request.json。
2. 将其中command和args映射到对原始代码库的实际调用（可能是启动一个子进程，或调用某个函数）。
3. 捕获执行结果、输出文件。
4. 将结果格式化为标准的output/result.json并写入指定位置。

这个设计巧妙地将“做什么”（契约）与“怎么做”（原始代码）解耦，使得智能体编排层只需要关心契约，而具体的执行细节被封装在技能内部。

3. 从安装到生成：完整实操指南

了解了原理，我们来看看如何亲手使用Skillify，将一个真实的代码库转化为技能。整个过程非常直观，几乎是一条命令的事情。

3.1 环境准备与工具获取

Skillify最大的优点之一是“开箱即用”。它基于Python 3.10+的标准库开发，没有外部依赖。这意味着你不需要经历复杂的pip install和可能存在的依赖冲突。

获取Skillify只需要一步：

git clone https://github.com/Substr8-Labs/skillify.git cd skillify

克隆完成后，你就拥有了完整的工具。目录里核心的就是skillify.py这个脚本。你可以选择将其路径加入系统PATH，或者就在当前目录下运行。

注意：虽然Skillify本身无依赖，但它生成的技能包装器可能会调用原始项目的环境。因此，确保你的系统具备基本的开发环境（如Python、Node、Rust等）是顺利运行生成技能的前提。

3.2 基础用法：一键生成技能骨架

Skillify的使用接口极其简洁。最基本的使用方式是指向一个代码库的源头。

针对远程GitHub仓库：

python3 skillify.py https://github.com/someuser/awesome-tool

执行后，Skillify会：

1. 在临时目录克隆该仓库。
2. 执行前述的所有分析步骤（类型检测、文档提取等）。
3. 在当前目录下生成一个以仓库名命名的文件夹（如awesome-tool/），里面包含了完整的技能结构。

针对本地已有项目：如果你正在开发一个工具，想立刻把它变成技能，可以直接指向本地路径。

python3 skillify.py /home/you/projects/my-local-script

这种方式避免了网络克隆，速度更快，非常适合在开发迭代中快速测试技能包装效果。

3.3 进阶参数：定制输出与深度集成

除了基础用法，Skillify提供了几个关键参数来满足更复杂的需求。

--output参数：指定输出目录默认输出到当前目录，但你可以使用--output参数指定一个明确的位置，这对于批量处理或集成到CI/CD流水线中非常有用。

python3 skillify.py https://github.com/org/repo --output ./generated-skills/repo-skill

这会将生成的技能直接放在./generated-skills/repo-skill目录下，保持工作区整洁。

--with-wrapper参数：生成可执行的包装契约这是最常用也是最重要的参数。如果不加这个参数，Skillify主要生成的是文档和元数据（SKILL.md和references/）。加上--with-wrapper后，它会额外生成scripts/目录，里面包含实现了标准I/O契约的入口脚本（如entrypoint.py）和环境初始化脚本（如init.sh）。

python3 skillify.py /path/to/repo --with-wrapper

这个生成的entrypoint.py脚本就是智能体编排器实际会调用的对象。它负责解析输入JSON，调用原始代码，并生成输出JSON。

--vendor模式（如果支持）：依赖打包对于一些简单的、依赖较少的项目，Skillify可以尝试将原始代码库的源代码复制到生成技能的vendor/目录下。这样做的好处是将技能及其依赖“打包”在一起，增强了隔离性和可移植性。但需要注意，对于依赖复杂或需要编译的项目，这种方式可能不适用。

3.4 生成物详解与验收检查

运行命令后，你应该会看到一个类似如下的目录结构：

awesome-tool/ ├── SKILL.md ├── references/ │ ├── README.md │ └── API.md ├── scripts/ # 使用 --with-wrapper 时生成 │ ├── entrypoint.py │ └── init.sh └── vendor/ # 可选，原始代码副本

验收清单：

1. 检查SKILL.md：打开此文件，确认Frontmatter信息（如名称、描述）是否正确，自然语言指令是否清晰描述了技能的功能和调用方式。
2. 检查references/：确认关键文档已被提取。如果原项目文档缺失，这里可能为空，你需要考虑手动补充。
3. 检查scripts/entrypoint.py(如果存在)：这是核心。查看其main函数或逻辑，看它是否正确地：
   • 从sys.argv[1]或环境变量读取输入文件路径。
   • 解析input/request.json。
   • 构建了对原始工具的正确调用命令（例如，使用subprocess.run）。
   • 处理了成功和错误的场景，并输出格式正确的result.json。
4. 手动测试契约：你可以手动创建一个input/request.json文件，然后运行python scripts/entrypoint.py path/to/input.json，观察输出和生成的output/result.json是否符合预期。这是确保技能可用的最终测试。

4. 高级集成模式：sessions_spawn与智能体协作

Skillify生成的技能并非孤立运行，它们设计之初就是为了被智能体编排。OpenClaw框架引入了一个强大的模式——sessions_spawn，用于处理技能本身需要AI能力（如LLM推理）的场景。这是一个精妙的设计，解决了技能在沙箱环境中无法直接访问API密钥等敏感信息的问题。

4.1 为什么需要 sessions_spawn？

想象一个叫autoforge的技能，它的功能是根据自然语言描述生成代码。这个技能的核心逻辑需要调用大语言模型（LLM）。然而，出于安全考虑，AI技能通常运行在受限制的沙箱环境中，不允许直接携带或访问LLM的API密钥。

sessions_spawn机制提供了一种安全的委托模式：技能不直接调用LLM，而是向编排它的“父智能体”发起一个“子任务”请求。由父智能体（它运行在可信环境，持有密钥）去执行这个需要AI能力的子任务，并将结果返回给技能。

4.2 机制详解与工作流

在技能包装器（entrypoint.py）的代码中，你可以实现一个类似如下的函数：

def sessions_spawn(task: str, label: str, timeout: int = 300) -> dict: """请求编排器派生子智能体执行任务。""" return { "status": "pending", # 关键状态，表示技能未完成，需要外部介入 "action": { "tool": "sessions_spawn", # 请求的动作类型 "params": { "task": task, # 给子智能体的自然语言指令 "label": label, # 任务标签，用于追踪 "runTimeoutSeconds": timeout # 超时设置 } } }

当技能执行到需要AI的环节时，它不进行实际调用，而是返回一个特殊的响应。这个响应的status是"pending"，并且包含了一个action对象，指明了需要父智能体执行sessions_spawn工具。

完整的工作流如下：

1. 智能体调用技能：父智能体（Orchestrator）启动技能，并传入request.json。
2. 技能请求协助：技能运行到需要LLM的步骤，它生成并返回一个status: "pending"的响应，其中包含了sessions_spawn的请求参数。
3. 编排器处理请求：父智能体接收到这个响应，理解到技能需要帮助。它于是利用自己的权限和环境，执行sessions_spawn：创建一个新的、临时的子智能体会话，将task参数作为指令发给它。
4. 子智能体执行：子智能体（例如，一个专门配置了GPT API的会话）执行任务（如“生成一段符合描述的Python代码”），并产生结果。
5. 结果回传：父智能体获取子任务的结果，然后将这个结果作为新的输入，重新调用原技能（或者直接将结果注入技能的上下文），让技能继续执行后续逻辑。
6. 技能完成：技能接收到LLM生成的结果，完成其核心处理（例如，将生成的代码写入文件），最终返回status: "ok"和最终的result.json。

4.3 实操示例：改造一个代码生成技能

假设我们有一个本地工具code-sketch.py，它接受一个功能描述，然后调用OpenAI API生成代码框架。我们想用Skillify把它包装成一个技能，并集成sessions_spawn。

步骤1：生成基础技能

python3 skillify.py ./code-sketch --with-wrapper

步骤2：修改生成的scripts/entrypoint.py我们需要修改包装器逻辑，将原来直接调用OpenAI API的部分，替换为返回sessions_spawn请求。

# ... 在 entrypoint.py 中 ... import json import sys import os def sessions_spawn(task, label, timeout=300): return { "status": "pending", "action": { "tool": "sessions_spawn", "params": {"task": task, "label": label, "runTimeoutSeconds": timeout} } } def main(): # 1. 读取输入 input_path = sys.argv[1] if len(sys.argv) > 1 else '/input/request.json' with open(input_path, 'r') as f: request = json.load(f) command = request.get('command', 'generate') spec = request.get('args', {}).get('spec', '') if not spec: # 处理错误... pass # 2. 核心逻辑：不再直接调用API，而是请求spawn # 原来的代码：call_openai_api(spec) # 新的代码： llm_task = f"Based on this specification, generate a skeleton code structure. Specification: {spec}" pending_response = sessions_spawn(task=llm_task, label=f"code_gen_{hash(spec)}") # 3. 如果是第一次运行，返回pending响应 # 这里需要一个机制判断当前是初次请求还是接收了spawn结果后的继续执行。 # 一个简单的实现是检查输入中是否包含一个特殊的字段，如 `_spawn_result` if '_spawn_result' not in request.get('args', {}): # 首次执行，返回pending output = pending_response else: # 第二次执行，收到了LLM生成的结果 generated_code = request['args']['_spawn_result'] # 在这里处理生成的代码，比如写入文件 output_dir = request.get('project_dir', '.') output_file = os.path.join(output_dir, 'generated_code.py') with open(output_file, 'w') as f: f.write(generated_code) # 返回成功响应 output = { "status": "ok", "artifacts": [{"type": "file", "path": output_file}], "summary": f"Generated code based on specification and saved to {output_file}" } # 4. 写入输出 output_path = '/output/result.json' with open(output_path, 'w') as f: json.dump(output, f, indent=2) if __name__ == '__main__': main()

这个示例展示了核心模式：技能通过返回pending状态将AI任务“外包”给编排器。编排器需要有能力理解这种响应，执行spawn，并将结果以某种方式（例如，作为新的request.json的一部分）反馈回来，驱动技能继续执行。

重要心得：实现sessions_spawn集成的关键在于状态管理。你的技能包装器需要能够区分“初次执行（请求帮助）”和“收到帮助后继续执行”两种状态。通常可以通过在请求参数中设置一个标志位或传递一个包含结果的特殊字段来实现。这要求智能体编排器与技能之间有一个简单的协议。

5. 常见问题、排查技巧与最佳实践

在实际使用Skillify和集成生成技能的过程中，你可能会遇到一些典型问题。以下是一些排查思路和来自实践的建议。

5.1 技能生成阶段问题

问题1：Skillify运行后报错“无法检测项目类型”或生成的内容非常空。

• 原因：目标仓库可能是一个非常规结构（如单一脚本文件）、使用了Skillify未识别的构建工具（如Bazel），或者标志文件不在根目录。
• 排查：
  1. 使用--verbose或查看Skillify源码中的日志输出，看它检测到了哪些文件。
  2. 检查目标仓库根目录下是否有常见的配置文件。
• 解决：
  • 对于简单脚本，你可以先将其放入一个标准结构中（例如，为Python脚本创建一个pyproject.toml）。
  • 考虑手动创建或补充SKILL.md和包装脚本。Skillify的产出可以作为很好的起点，但并非不可修改。
  • 如果项目类型确实特殊，可以尝试向Skillify项目贡献检测逻辑。

问题2：生成的entrypoint.py脚本无法正确调用原始工具。

• 原因：原始工具的启动方式可能比较复杂（如需要特定环境变量、复杂的参数解析、交互式输入），而Skillify生成的通用包装器逻辑过于简单。
• 排查：
  1. 手动运行原始工具，确认其正确的命令行调用方式。
  2. 对比entrypoint.py中构建命令的逻辑。
• 解决：
  • 手动修改entrypoint.py：这是最常见的方法。根据原始工具的实际需求，调整subprocess.run的参数，例如设置cwd（工作目录）、env（环境变量），或处理标准输入输出。
  • 使用更复杂的调用方式：如果工具是Python模块，考虑用import并直接调用函数，而不是通过子进程。这能获得更好的错误处理和性能。
  • 封装为函数：如果原始代码是一堆脚本，最好先将其重构为一个具有清晰入口函数的模块，这样包装器调用起来会更简单可靠。

5.2 技能运行与集成问题

问题3：技能在OpenClaw或其他编排器中运行时，找不到依赖。

• 原因：生成的技能包含了原始代码，但未包含其依赖的安装步骤。init.sh可能过于简单或缺失。
• 排查：检查scripts/init.sh文件的内容。它是否包含了安装依赖的命令（如pip install -r requirements.txt,npm install,cargo build）？
• 解决：
  • 强化init.sh：编辑此脚本，加入完整的依赖安装和环境准备命令。确保脚本是幂等的（多次运行结果相同）。
  • 使用容器：对于依赖复杂的环境，最好的实践是不依赖宿主机环境。你可以修改技能，使其包含一个Dockerfile。这样，编排器可以在一个纯净的容器中运行技能，通过Dockerfile来定义确定性的环境。Skillify未来可能会支持生成基础的Dockerfile。

问题4：sessions_spawn模式中，技能陷入“pending-回调”的死循环，或结果传递失败。

• 原因：技能和编排器之间的状态协议不清晰或实现有误。
• 排查：
  1. 仔细阅读编排器（如OpenClaw Control Tower）关于如何处理pending响应的文档。
  2. 在技能的entrypoint.py中添加详细日志，打印出每次执行的输入参数，确认_spawn_result等字段是否被正确传递。
• 解决：
  • 设计明确的协议：定义好技能如何告知编排器“我需要spawn”，以及编排器如何将结果传回来。例如，约定在request.json的args中加入一个__callback_data字段存放之前的状态，用__needs_spawn布尔字段标记是否需要请求。
  • 简化流程：对于简单场景，可以让spawn任务完成所有工作，技能只负责发起请求和格式化最终结果，避免复杂的回调状态管理。

5.3 最佳实践总结

1. 从简单项目开始：首次使用Skillify时，选择一个结构清晰、依赖少的项目（例如一个纯Python的CLI工具）。这能帮助你快速理解整个流程和生成物的结构。
2. 生成的技能是起点，不是终点：将Skillify的输出视为一个自动化生成的脚手架。你几乎总是需要手动调整SKILL.md中的描述使其更准确，并修改entrypoint.py以完美适配原始工具的调用方式。
3. 重视init.sh和环境隔离：可靠的技能必须拥有可重复构建的运行环境。花时间完善初始化脚本，或者直接采用Docker容器化，这是保证技能在任何地方都能一致运行的关键。
4. 契约设计要严谨：在定义技能的输入输出契约（request.json/result.json的格式）时，要像设计API一样严谨。参数命名要清晰，数据结构要稳定。一旦发布，对契约的修改就是破坏性的变更。
5. 为技能编写测试：为你生成的技能包装器编写简单的集成测试。模拟输入JSON，运行entrypoint.py，检查输出JSON和产生的文件是否符合预期。这能极大提升技能的可靠性和维护性。
6. 利用references/目录：不要只依赖自动提取的文档。如果原项目文档不佳，主动向references/目录添加详细的用法示例、参数说明和边界情况处理。这些信息对于未来使用该技能的AI智能体或开发者至关重要。

Skillify的理念是降低集成成本，而非完全消除开发。它通过自动化处理了80%的样板代码和标准化工作，剩下的20%——那些与具体业务逻辑紧密相关的适配和优化——则需要开发者基于其生成的蓝图进行精细打磨。当你熟练运用这套模式后，将庞大的开源工具生态快速转化为智能体可调用的技能库，就会从一个复杂的工程挑战，变成一系列高效的流水线操作。