ima skill格式，安装教程 — 从包结构到部署的完全指南

ima Skill的本质是一组遵循特定规范的文件集合，打包为一个Skill Package。这个Package在ima.copilot中作为一个独立的功能单元运行，为用户提供特定的AI增强能力。

从技术层面看，ima skill格式由两大部分构成：配置层和执行层。

📐 配置层（Configuration Layer）：基于YAML Config和JSON格式，负责描述Skill的元信息、运行参数、依赖关系和权限声明。核心文件是manifest.yaml（Skill元数据配置文件）和config.json（运行时配置）。配置层是ima平台识别和加载Skill的入口——当ima.copilot启动时，会扫描Skill Directory下的所有manifest.yaml文件，构建可用的Skill列表。

⚙️ 执行层（Execution Layer）：主要是Python可执行脚本（main.py），这是Skill的实际逻辑载体。当用户在Copilot对话中触发某个Skill时，ima的运行时会读取manifest.yaml中的配置，然后调用main.py中的入口函数执行具体逻辑，最后将结果返回给Copilot呈现给用户。

两种配置格式的选用原则：ima同时支持YAML和JSON两种配置格式。YAML格式（manifest.yaml）用于定义Skill的元数据和结构化信息——因为YAML的注释支持和可读性更优，适合人类手动编辑。JSON格式（config.json）用于存储运行时参数——因为JSON的解析性能更好且与JavaScript/Python的数据结构无缝对接。部分高级Skill还会包含一个schema.json文件，用于定义config.json中参数的校验规则ima开放平台技术文档 - "Skill Package Specification v2.1"，2025年11月。

这种"YAML做元数据 + JSON做配置 + Python做逻辑"的复合格式设计，在灵活性和标准化之间取得了精妙的平衡。它既不像纯YAML方案那样在复杂逻辑场景下力不从心，也不像纯代码方案那样对非技术用户过高门槛。关于如何安装这些Skill包，我们将在后续章节详细讲解发现广场一键安装、CLI Install命令行安装和手动安装三种方式。

一个标准的Skill Package遵循固定的Skill Directory目录结构。无论Skill的复杂程度如何，以下四个核心文件是必须的：

📄 manifest.yaml：Skill的"身份证"，包含name、version、description、author、dependencies等核心字段。ima平台通过解析此文件来识别和注册Skill。格式为YAML Config标准。

📄 main.py：Skill的执行逻辑入口。ima运行时会在沙箱环境中执行此文件，调用其中定义的handler函数来处理用户请求。支持Python标准库和manifest.yaml中声明的第三方依赖。

📄 config.json：Skill的运行时配置参数，通常包含API密钥、默认参数、环境变量等。config.json中的值可以在安装时由用户自定义，也可以在运行时由Skill自身动态更新。

📄 README.md：Skill的使用说明文档，采用Markdown格式。当用户在发现广场查看Skill详情时，README.md的内容会被渲染展示。优秀的README应包含功能介绍、安装方法、使用示例、API说明和更新日志。

📁 assets/ 目录：存放Skill的静态资源，如图标（icon.png，建议尺寸256×256px）、演示动图（demo.gif）、模板文件等。这些资源在发现广场的Skill卡片和详情页中展示。

需要特别注意的是，Skill的根目录名称必须与manifest.yaml中定义的name字段严格一致（包括大小写），否则ima平台在加载时可能无法正确识别。这一约定对于通过CLI Install和手动安装方式部署的Skill尤为重要ima开放平台最佳实践指南 - "Skill Directory命名规范"，2025年。

关于YAML Config中各字段的详细配置说明，请继续阅读第3章manifest.yaml配置详解。

manifest.yaml是整个Skill Package的核心配置文件，相当于Skill的"身份证+说明书"。ima平台在加载Skill时首先解析此文件。下面是一个完整的manifest.yaml示例：

🔑 必填字段详解：

• name：Skill的唯一标识符，全局不可重复。建议使用小写字母和连词符（kebab-case），如weixin-reading、data-analysis。命名时应避免使用ima、skill等保留前缀。
• version：遵循语义化版本规范（SemVer），格式为MAJOR.MINOR.PATCH。MAJOR版本变更表示不兼容的API改动，MINOR表示向后兼容的功能新增，PATCH表示向后兼容的bug修复。
• description：40-120字符的简短描述，将显示在发现广场的Skill卡片上。建议采用"功能+价值"的句式，如"微信读书Skill - 同步书架、AI精读、跨书对比"。
• runtime：定义Skill的运行环境。目前支持python和typescript两种类型。entry字段指定入口文件路径，handler字段指定入口函数名称——ima运行时会调用此函数处理用户请求。

📦 Runtime Dependencies配置：dependencies字段声明Skill运行所需的第三方包。ima平台在安装Skill时会自动解析并安装这些依赖。如果依赖安装失败，Skill将无法正常加载。Runtime Dependencies的管理是Skill开发中最容易出问题的环节——建议在requirements.txt中列出完整依赖清单，并在README中说明特定版本的兼容性信息ima开放平台开发者文档 - "Dependencies Management"，2025年12月。

🔒 权限声明（permissions）：这是ima skill格式中最重要的安全机制。Skill必须显式声明其需要访问的资源（network、knowledge_base、filesystem等），用户在安装时会看到权限提示并逐项审批。这一设计借鉴了移动操作系统的权限模型，有效防止恶意Skill滥用用户数据。开发者应遵循"最小权限原则"——只申请完成功能所必须的权限。

完整的manifest.yaml配置规范可参考API接口文档中的Skill配置章节。

对于大多数用户而言，从发现广场安装Skill是最简单、最推荐的方式。无需接触命令行或文件系统，全程可视化操作。以下是标准的三步安装法：

安装完成后，你可以在ima.copilot左侧菜单栏的「我的Skills」中看到已安装的Skill列表。在Copilot对话中直接输入你的需求（如"用微信读书Skill总结我最近在读的书"），系统会自动调用对应的Skill来完成任务。

需要注意的是，部分第三方Skill（如广发证券Skill）在首次使用时可能需要额外的账号授权步骤——按照Skill提示完成第三方平台登录即可。如果你在安装过程中遇到任何问题，可以参考使用指南中的常见问题章节。

关于如何在Copilot中实际使用已安装的Skill，可参考Skills使用教程中的详细演示。

对于开发者或有批量部署需求的用户，CLI Install（命令行安装）提供了比图形界面更高效的安装方式。OpenClaw Integration框架提供了完整的命令行工具集，其中openclaw skills install命令是安装Skill的核心指令。

🔧 基本安装命令

📋 常用CLI Install命令一览

💡 从GitHub Repo安装的最佳实践

从GitHub Repo直接安装是开发者最常用的方式。支持的格式包括：

• 公开仓库：openclaw skills install github:username/repo，自动检测默认分支的最新代码。
• 私有仓库：需要先配置GitHub Token：openclaw config set github.token YOUR_TOKEN。
• 指定分支或Tag：openclaw skills install github:username/repo#v2.1.0。

⚠️ CLI Install注意事项：

• 执行CLI命令前，请确保已安装并配置好OpenClaw Integration工具（pip install openclaw-cli）。
• CLI Install会自动安装manifest.yaml中声明的Runtime Dependencies，如果依赖安装失败会显示错误信息。
• 安装后的Skill默认存放在~/.ima/skills/目录下，与手动安装的Skill共用同一个Skill Directory。
• 如果同时使用图形界面安装和CLI Install，注意不要重复安装同名Skill，以免造成版本冲突。

CLI Install方式特别适合需要在多台设备上部署相同Skill集合的场景。你可以编写一个Shell脚本，批量执行一系列openclaw skills install命令，实现"一键部署"效果。详细的CLI参考文档可查看API接口文档中的命令行工具章节。

手动安装是最传统也最灵活的安装方式，尤其适合以下场景：离线环境部署、开发测试阶段的本地调试、或需要自定义修改Skill代码的高级用户。手动安装流程分为三个步骤：

📦 第一步：获取Skill ZIP包

从Skill的GitHub Repo或第三方分发渠道下载Skill的ZIP压缩包。大部分开源Skill会在GitHub的Releases页面提供ZIP格式的发行包。你也可以直接从GitHub仓库页面点击「Download ZIP」获取最新代码——但需要注意，这种方式下载的压缩包可能包含源代码中不必要的开发文件。

推荐从以下渠道获取可靠的手动安装包：

• GitHub Releases：https://github.com/{owner}/{repo}/releases，这里的ZIP包经过版本化管理，包含完整的Skill Package结构。
• Skill Marketplace归档：部分Skill在Marketplace详情页提供「离线下载」链接。
• 开发者直接分发：企业级Skill可能通过内部渠道直接分发ZIP包。

📂 第二步：解压到Skill Directory

将下载的ZIP包解压到ima的Skill目录中。默认的Skill Directory路径为：

• Windows：C:\Users\你的用户名\.ima\skills\
• macOS / Linux：~/.ima/skills/

解压后请确保目录结构正确——ZIP包解压出的根目录应该直接包含manifest.yaml、main.py、config.json和README.md四个核心文件（而不是多一层嵌套文件夹）。如果解压后多出一层目录，请将内部目录移动到skills/下并删除空的嵌套层。

⚙️ 第三步：配置与激活

解压完成后，你需要让ima平台重新扫描Skill目录来识别新安装的Skill：

• 图形界面方式：在ima.copilot客户端的「我的Skills」页面，下拉刷新或点击「扫描新Skill」按钮。
• 命令行方式：执行openclaw skills scan命令手动触发目录扫描。

扫描成功后，新安装的Skill就会出现在「我的Skills」列表中。如果你在安装过程中修改了config.json中的配置参数（如API密钥），建议重新启动ima.copilot客户端以确保配置生效。

手动安装特别适合开发者在本地编辑Skill代码后的快速测试——修改代码 → 刷新技能 → 在Copilot中验证，迭代周期极短。关于如何开发自己的Skill，可参考第7章官方Skill SDK介绍和第8章Skill开发基础。

Skill SDK是ima官方提供的开发者工具包，封装了Skill开发所需的核心API和工具函数，大幅降低开发门槛。无论你是Python开发者还是TypeScript开发者，都能找到适合的SDK版本。

🐍 Python SDK（推荐）

Python SDK是ima官方首选的开发工具包，提供了最完整的API支持和最活跃的社区维护。安装方式：

Python SDK的核心能力包括：

• 知识库操作：KnowledgeBase.read()、KnowledgeBase.write()、KnowledgeBase.search()
• AI模型调用：AI.complete()（文本生成）、AI.embed()（向量嵌入）
• 网络请求：HTTP.get()、HTTP.post()（内置请求重试和超时管理）
• 工具函数：Utils.parse_json()、Utils.validate_config()
• 日志系统：Logger.info()、Logger.error()（自动写入ima日志文件）

📘 TypeScript SDK

面向前端开发者和Node.js生态用户：

TypeScript SDK与Python SDK在API设计上保持高度一致，降低了多语言开发的学习成本。特别适合需要在前端数据处理或Node.js生态中运行的Skill场景。

📚 SDK文档与示例

SDK的完整文档和示例代码托管在GitHub Repo上：

• Python SDK仓库：https://github.com/openclaw/skill-sdk-python
• TypeScript SDK仓库：https://github.com/openclaw/skill-sdk-ts
• 官方示例Skill集合：https://github.com/openclaw/skill-examples（包含10+个从入门到进阶的完整示例）

SDK中内置了一个快速脚手架工具：

执行上述命令后，SDK会自动生成一个完整的Skill项目模板，包含manifest.yaml、main.py/config.json和README.md的标准结构，开发者只需填充业务逻辑即可。如需进一步了解API调用细节和知识库操作方法，可参考API接口文档。

掌握ima skill格式的最终目的是开发自己的Skill。本节以一个简单的"笔记摘要Skill"为例，演示Skill开发的核心流程。

📝 基础Skill示例：笔记摘要Skill

下面的代码展示了一个最简单的Skill实现——读取用户知识库中的指定笔记，并生成AI摘要：

🛠️ API调用实践

大多数实用的Skill都需要调用外部API。以下是通过Skill SDK进行外部API调用的标准模式：

📚 知识库操作高级用法

知识库读写是Skill开发中最常用的能力。SDK提供了丰富的知识库操作API：

• 全文搜索：KnowledgeBase.search(query, limit=10)——语义搜索知识库内容，返回匹配结果列表。
• 分类查询：KnowledgeBase.list_by_category(category_id)——按分类获取知识库条目。
• 内容创建：KnowledgeBase.create(title, content, tags=[])——在知识库中创建新笔记。
• 批量操作：KnowledgeBase.batch_import(files=[])——批量导入文件到知识库。

⚠️ 开发注意事项：

• 所有外部网络请求必须在manifest.yaml的permissions中声明network: true。
• 知识库写入操作需要额外申请knowledge_base.write权限。
• 建议在开发时使用openclaw skills install ./my-skill.zip进行本地测试，迭代效率最高。
• 正式发布前，请通过openclaw skills test my-skill命令运行内置测试套件。

更多开发进阶内容（如多Intent路由、异步任务处理、Webhook回调等），可参考API接口文档中的Skill开发指南和Skills使用教程中的最佳实践案例。

随着Skill生态的日益壮大，版本管理成为维护Skill健康运行的关键能力。ima平台提供了一套完整的版本管理机制，覆盖从版本定义到自动更新的全流程。

📌 语义化版本规范

所有Skill必须遵循语义化版本（SemVer）规范，版本格式为MAJOR.MINOR.PATCH：

• MAJOR（主版本号）：当做了不兼容的API改动时递增。例如修改了handler函数的参数签名、删除了原有功能、变更了返回数据格式。MAJOR版本升级通常意味着用户需要重新适配使用方式。
• MINOR（次版本号）：当做了向下兼容的功能新增时递增。例如新增了一个API端点、增加了新的配置选项。MINOR版本升级不会破坏现有功能。
• PATCH（修订号）：当做了向下兼容的问题修正时递增。例如修复了一个bug、优化了性能。PATCH版本升级最安全，通常可以无感更新。

🔄 版本更新操作

ima提供了多种方式来更新已安装的Skill：

• 自动检查更新：在ima.copilot设置中开启「自动检查Skill更新」选项。系统将每24小时自动检测一次已安装Skill的版本状态，发现新版本时在「我的Skills」页面显示更新角标。
• 手动更新：在「我的Skills」列表中点击具体Skill卡片→查看详情页→点击「更新」按钮。系统会自动下载并安装最新版本，保留原有配置参数。
• 命令行更新：执行openclaw skills update my-skill，可指定版本号：openclaw skills update my-skill@2.2.0。

📋 版本管理最佳实践

• 在README.md中维护CHANGELOG章节，记录每个版本的变更内容。
• 版本号必须与GitHub Repo中的Git Tag一一对应，方便追溯源码。
• MAJOR版本升级前，应在Skill详情页发布升级预告（Deprecation Notice），给用户至少30天的迁移窗口期。
• 对于企业级Skill，建议使用长期支持版本（LTS）策略——同时维护两个MAJOR版本的安全更新。

版本管理的详细操作说明可参考使用指南中的"Skill维护"章节。

当你不再需要某个Skill时，ima提供了三种卸载方式，覆盖不同使用场景。

🗑️ 方式一：图形界面卸载（推荐）

最直观的卸载方式，适合所有用户：

⌨️ 方式二：命令行卸载

适合批量管理和远程操作场景：

📁 方式三：手动删除文件夹

如果您了解文件系统操作，可以直接从Skill Directory中删除对应文件夹：

手动删除后，建议执行openclaw skills scan命令刷新Skill列表，或在ima.copilot中手动刷新「我的Skills」页面。

⚠️ 卸载注意事项：

• 卸载Skill不会删除你的知识库内容、对话记录或其他用户数据。
• 如果某Skill正在被其他Skill依赖（如A Skill调用了B Skill的接口），卸载B可能导致A功能异常——命令行卸载时会显示依赖警告。
• 卸载后如果想重新使用，重新安装即可，无需额外配置（部分需要第三方授权的Skill可能需要重新授权）。
• 建议每月检查一次已安装Skills列表，及时清理不再使用的Skill以优化客户端性能。

更多关于Skill管理的技巧，可参考Skills使用教程中的管理章节。

通过分析实际热门的Skill格式，可以更直观地理解ima skill格式在不同场景下的应用差异。下表对比了五款热门Skill的格式特征：

📊 格式对比发现：

• 低复杂度Skill（公文仿写专家）：主要通过精心设计的YAML Config和Prompt模板实现，main.py代码极简。这类Skill适合纯AI能力驱动的场景，开发周期可控制在数小时内。其Skill Manifest中permissions仅需kb.read，安全性最高。
• 中复杂度Skill（微信读书/广发证券）：需要与第三方平台进行OAuth授权和数据交换，main.py中包含了完整的API对接逻辑。这类Skill对Runtime Dependencies的管理要求较高——微信读书Skill的requirements.txt中包含了6个第三方包。
• 高复杂度Skill（WorkBuddy/QClaw）：涉及多平台集成、异步任务调度和复杂数据处理。WorkBuddy的manifest.yaml中声明了12个Runtime Dependencies，代码结构包含多个模块文件（不仅仅是单个main.py）。这类Skill的开发接近一个完整的小型应用，建议使用Skill SDK的模块化开发模式。

值得注意的是，所有热门Skill都严格遵循OpenClaw Integration标准接口规范——这意味着它们可以在同一个ima.copilot实例中共存且互不干扰。这正是标准化ima skill格式的核心价值所在。如果你想了解这些Skill的具体使用方法，可参考Skills使用教程中的热门Skill实操演示。

💡 深度解读：为什么说Skill格式的标准化是ima生态从"可用"到"繁荣"的转折点？

复盘ima Skill格式的演进历程（v1.0仅支持纯JSON配置 → v2.0引入YAML Config + Python双引擎 → v2.1加入完整的Skill Manifest和Runtime Dependencies管理），我们可以清晰地看到一条主线：标准化程度与生态繁荣度呈正相关。v1.0时期（2025年初）Skills数量不到100个，格式规范不够明确，开发者各自为政；v2.0推出后，统一格式使得Skills数量在3个月内突破500个；v2.1引入依赖管理和权限声明后，企业级复杂Skill（如WorkBuddy、QClaw）开始涌现。

从更深层看，ima skill格式的标准化带来的不仅是开发效率的提升，更是网络效应的释放：标准格式 → 降低开发门槛 → 更多Skill上架 → 用户更多选择 → 更多用户 → 更活跃的社区 → 更多开发者涌入。这一正向飞轮已经在2025年Q4开始加速运转。OpenClaw Integration框架和Skill SDK的持续完善，将进一步降低"将创意转化为Skill"的成本。

对开发者而言，现在正是切入ima Skill生态的最佳时机——格式标准已经成熟、用户基数在快速增长、竞争格局尚未固化。从第8章Skill开发基础起步，利用Skill SDK和发现广场的分发能力，你的第一个Skill可能就在不知不觉中进入数十万ima用户的Copilot对话中。