1. 项目概述：为AI智能体打造专属的“技能应用商店”

如果你正在使用Claude、Cursor、Windsurf这类前沿的AI智能体，并且已经厌倦了每次都要手动编写或复制粘贴复杂的工具调用指令，那么你很可能需要一个更优雅的解决方案。 osm （Open Skills Manager）正是为此而生。简单来说，它是一个专为AI智能体设计的“包管理器”，就像 npm 之于Node.js， pip 之于Python，但它的“包”不是代码库，而是可以直接被AI理解和执行的“技能”。

想象一下，你想让AI帮你读取Gmail邮件、查询天气或者控制智能家居。传统做法是，你需要在系统提示词里塞入一大段API文档和函数定义，既臃肿又难以维护。而 osm 的思路是：将这些功能封装成一个个独立的、可复用的“技能包”。你只需要一句 osm install gmail-reader ，这个技能就会被下载、安装到本地，你的AI智能体在运行时就能自动发现并调用它。这极大地简化了为AI扩展能力的工作流，让开发者可以专注于技能的逻辑本身，而非繁琐的集成过程。

2. 核心设计理念与架构解析

2.1 为什么需要AI技能包管理器？

在AI智能体生态发展的早期，功能集成往往是“一次性”的。开发者要么将工具描述硬编码在提示词中，要么通过复杂的插件系统手动挂载。这种方式存在几个痛点：

  1. 复用性差 ：为一个项目写的工具函数，很难直接迁移到另一个项目或另一个AI模型上。
  2. 版本管理混乱 ：工具逻辑更新后，需要手动同步到所有使用它的地方，极易出错。
  3. 发现与分享困难 ：优秀的工具实现散落在个人电脑或私有仓库中，社区无法高效地共享和协作。

osm 借鉴了成熟软件生态的包管理思想，旨在解决这些问题。它将一个“技能”定义为包含元数据（名称、描述、版本）和核心指令（ SKILL.md ）的最小可分发单元。这种设计实现了 关注点分离 ：技能开发者只需关心 SKILL.md 里写给AI的“使用说明书”；技能使用者则通过简单的命令行操作完成获取和部署；而AI智能体框架（如Cursor）只需遵循 OpenSkills 规范，就能自动加载 ~/.osm/skills/ 目录下的所有技能，实现“开箱即用”。

2.2 技能的本质：SKILL.md文件剖析

一个 osm 技能的核心，就是一个 SKILL.md 文件。这非常巧妙，因为它使用了AI智能体最熟悉的媒介：Markdown文本。这个文件承担了双重职责：

  • 元数据容器 ：通过YAML Frontmatter（文件开头以 --- 包裹的部分）声明技能的“身份信息”。
  • AI执行指南 ：Frontmatter之后的内容，就是写给AI智能体的详细指令，其写作风格与系统提示词（System Prompt）完全一致。

让我们拆解一个 SKILL.md 的示例：

---
name: weather-fetcher
description: Fetches current weather and forecast for a given city.
version: 1.1.0
author: jane-doe
---

# Weather Fetcher

你是一个天气查询助手。当用户询问某个城市的天气时，你需要调用我提供的工具。

## 工具：get_weather

请在你认为需要查询天气时，主动调用此工具。

**参数：**
- `city` (string, required): 城市名称，例如“北京”、“New York”。

**行为：**
1.  使用公开的天气API（例如OpenWeatherMap）查询该城市的实时天气。
2.  返回一个结构化的结果，包括：城市、当前温度、天气状况（晴、雨等）、湿度、风速。
3.  如果城市不存在或查询失败，返回友好的错误信息。

**回复格式：**
请以自然、友好的语气向用户汇报天气信息，并补充一些穿衣或出行建议。

关键点解析：

  • Frontmatter是给 osm 看的 ： name 必须与目录名一致，这是技能的唯一标识。 description 要简洁明了，因为这会用于 osm search 的搜索结果展示。
  • 正文是给AI看的 ：这里定义了AI在什么情境下触发技能、如何调用（工具名称、参数）、以及期望AI如何对结果进行后处理和回复。这相当于一个微型的、专属的“系统提示词”。
  • 版本化 ：每次发布（ osm publish ）都是一个不可变的版本。如果你想修复bug或增加功能，必须修改 SKILL.md 中的 version 字段（如从 1.0.0 升到 1.1.0 ），然后再次发布。这保证了使用者环境的稳定性，他们可以明确知道自己安装的是哪个版本。

注意： SKILL.md 的写作质量直接决定了技能的效果。你需要像训练一个人类助手一样，为AI编写清晰、无歧义、覆盖边界情况的指令。避免使用模糊的语言，尽可能结构化。

2.3 系统架构与数据流

osm 的架构清晰且高效，主要分为三个部分：命令行工具（CLI）、技能注册中心（Registry）和本地运行时环境。

  1. CLI（命令行工具） ：用户直接交互的界面。它处理搜索、安装、发布等所有命令。当你执行 osm install 时，CLI会向注册中心请求技能包的下载链接（通常是一个.tgz压缩包）。
  2. 注册中心（osmagent.com） ：中央数据库，存储所有已发布技能的元信息和版本化的压缩包。它处理用户认证（ signup / login ）、技能搜索和包分发。
  3. 本地环境 ：所有操作最终都落地在用户本地的一个目录（默认为 ~/.osm ）。安装的技能被解压到 ~/.osm/skills/ 下，而下载的压缩包会缓存在 ~/.osm/cache/ 中。这种缓存机制实现了离线回退：如果网络不通，但之前安装过某个技能， osm 可以尝试从本地缓存恢复。

数据流示例（ osm install gmail-reader ）：

  1. CLI检查本地是否已有 gmail-reader 。
  2. 向注册中心查询 gmail-reader 的最新版本和下载地址。
  3. 从注册中心下载 gmail-reader-1.0.0.tgz 到本地缓存。
  4. 验证压缩包的完整性（如SHA256校验和）。
  5. 将压缩包解压到 ~/.osm/skills/gmail-reader/ 目录。
  6. 至此，支持 OpenSkills 规范的AI智能体就能在下次启动时，自动扫描并加载这个新技能。

3. 从零开始：完整实操指南

3.1 环境准备与CLI安装

首先，确保你的系统满足基础要求： Node.js 18或更高版本 。你可以通过 node --version 命令来检查。如果没有安装Node.js，建议从官网下载LTS版本进行安装。

osm 提供了便捷的一键安装脚本。打开你的终端（Terminal、iTerm、PowerShell等），执行以下命令：

curl -fsSL https://www.osmagent.com/install.sh | bash

这个命令会做几件事：从官网下载安装脚本，然后脚本会自动检测你的系统，下载对应平台的 osm 二进制文件，并将其放置到系统的可执行路径下（如 /usr/local/bin ）。安装完成后，你可以通过 osm --version 来验证是否成功。

实操心得： 在某些网络环境下（例如企业内网），直接运行远程脚本可能会被安全策略阻止。如果遇到问题，可以尝试分步操作：先用浏览器打开 https://www.osmagent.com/install.sh 查看脚本内容，如果觉得安全，将其保存为本地文件（如 install_osm.sh ），然后运行 bash install_osm.sh 。另一种更“极客”的方式是，直接从项目的GitHub Releases页面下载对应操作系统的预编译二进制文件，手动将其移动到 /usr/local/bin 目录下。

3.2 基础使用：搜索、安装与管理技能

安装好CLI后，你就可以像使用任何其他包管理器一样来探索技能世界了。

搜索技能： 假设你想找一个处理邮件的技能，可以尝试搜索关键词。

osm search email

或者更具体一点：

osm search gmail

搜索结果会列出所有名称或描述中包含关键词的技能，并显示其简要描述，帮助你快速找到需要的功能。

安装技能： 找到心仪技能后，使用其 name 进行安装。例如，安装一个名为 gmail-reader 的技能：

osm install gmail-reader

安装过程会在终端有进度显示。完成后，该技能的所有文件（核心就是那个 SKILL.md ）就已经静静地躺在 ~/.osm/skills/gmail-reader/ 目录里了。

查看与管理已安装技能：

  • osm list ：列出所有已安装的技能及其版本。
  • osm info gmail-reader ：查看某个技能的详细信息，包括其完整的 SKILL.md 内容。这在你想了解一个技能具体如何工作，或者想借鉴其写法时非常有用。
  • osm update gmail-reader ：如果技能作者发布了新版本，此命令会将其更新到最新版。
  • osm remove gmail-reader ：当你不再需要某个技能时，使用此命令将其从本地卸载。

3.3 技能开发与发布全流程

使用别人的技能固然方便，但真正的威力在于创造和分享自己的技能。下面我们一步步创建一个“网络搜索”技能。

第一步：创建技能脚手架 

osm create web-searcher
cd web-searcher

这条命令创建了一个名为 web-searcher 的目录，并在里面生成了一个初始的 SKILL.md 文件。目录名就是技能名，必须使用小写字母、数字和连字符（hyphen）。

第二步：编写SKILL.md 用你喜欢的文本编辑器（如VSCode、Vim）打开 SKILL.md ，将其修改为如下内容：

---
name: web-searcher
description: Performs a web search using the DuckDuckGo API and returns summarized results.
version: 0.1.0
author: your-username # 请替换为你在osm注册的用户名
---

# Web Searcher

你是一个网络搜索专家。当用户的问题需要实时或最新的网络信息时，请主动使用此工具。

## 工具：search_web

当你判断用户的查询涉及你不知道的实时信息、新闻、特定数据或需要从多个来源验证的事实时，调用此工具。

**参数：**
- `query` (string, required): 需要搜索的关键词或问题，请用简洁明确的语言描述。
- `max_results` (number, optional, default: 5): 需要返回的最大结果数量。

**行为：**
1.  使用DuckDuckGo的Instant Answer API或HTML抓取（通过一个如`serpapi`或`duckduckgo-search`的库）执行搜索。
2.  获取前`max_results`个结果的标题、链接和摘要。
3.  对结果进行初步分析，剔除明显不相关或低质量的链接。
4.  将处理后的结果以结构化列表的形式返回。

**回复格式：**
首先，告诉用户你正在或已经进行了搜索。然后，以清晰的方式呈现搜索结果：
- 对于每个结果，先给出序号和标题，然后是简要的摘要。
- 在最后，基于这些搜索结果，综合给出一个直接、准确的答案。如果搜索结果间有矛盾，指出这一点。
- 务必在答案末尾注明信息来源（提供链接）。

第三步：本地测试与迭代 在发布之前，强烈建议进行本地测试。你可以手动将这个 web-searcher 目录软链接或直接复制到 ~/.osm/skills/ 目录下，然后启动你的AI智能体（如Cursor的Agent模式），尝试提出一个需要联网搜索的问题，比如“今天特斯拉的股价是多少？”，观察AI是否会尝试调用你定义的 search_web 工具，以及调用逻辑是否符合预期。

这个测试迭代过程可能需要进行多次，不断调整 SKILL.md 中的指令，直到AI的行为与你设想的一致。这是技能开发中最关键的一步。

第四步：发布到社区 当你对技能效果满意后，就可以将其分享给全世界了。

  1. 注册与登录 ：

    osm signup

    按照提示输入用户名、邮箱和密码，完成注册。

    osm login

    输入你的凭证进行登录。登录成功后，令牌会安全地存储在 ~/.osm/auth.json 中。

  2. 发布技能 ： 确保你在 web-searcher 目录下，然后执行：

    osm publish

    CLI会读取 SKILL.md 中的 name 和 version ，将它们与你的账户信息一起打包上传到 osm 注册中心。成功后，你会看到发布成功的提示，并且全球的用户都可以通过 osm search web-searcher 找到它，并通过 osm install web-searcher 安装它。

重要注意事项： 发布是不可逆的！一旦一个特定版本（如 web-searcher@0.1.0 ）被发布，它就永远存在于注册中心，无法删除或覆盖。这是为了确保依赖此版本的用户环境不会突然崩溃。如果你需要修复bug，必须提升版本号（如改为 0.1.1 ），然后再次发布。

4. 高级技巧与最佳实践

4.1 编写高质量SKILL.md的黄金法则

一个技能是否好用，九成取决于 SKILL.md 的编写质量。以下是来自实践中的几条黄金法则：

  1. 角色定义清晰 ：在正文开头，用“你是一个XXX专家”这样的句式明确AI在使用此技能时的角色。这能更好地引导AI的“行为模式”。
  2. 触发条件具体化 ：在工具描述中，明确说明“在什么情况下调用此工具”。避免使用“当需要时”这种模糊表述。例如：“当用户的问题涉及 未来的日期、时间计算 或需要 查询节假日 时调用”，就比“当用户问时间时调用”要明确得多。
  3. 参数描述详尽 ：为每个参数说明其类型（string, number, boolean）、是否必填、以及具体的格式或示例。例如： date (string, required): 日期，格式为YYYY-MM-DD，例如2023-10-01 。
  4. 处理逻辑分步写 ：在“行为”部分，将AI需要做的逻辑判断和操作，用1、2、3…的步骤清晰地列出来。这相当于给AI写了一个微型函数文档。
  5. 输出格式有要求 ：明确告诉AI你希望它如何呈现结果。是直接给出答案？还是先列出数据再总结？是否要包含原始链接？明确的格式要求能产生更一致、更专业的输出。
  6. 考虑边界情况 ：思考工具可能失败的情况（如网络错误、API限流、无效输入），并在指令中告诉AI此时应如何应对（例如，“如果搜索无结果，请礼貌告知用户并尝试建议更通用的关键词”）。

4.2 技能设计的模块化与组合思想

不要试图创建一个“巨无霸”技能来搞定所有事情。优秀的技能设计应该是模块化的、功能单一的。例如：

  • 一个 fetch-stock-price 技能只负责获取股价。
  • 一个 calculate-portfolio-value 技能负责根据股价计算资产总值。
  • 一个 send-email-notification 技能负责发送通知。

这样设计的好处是：

  • 可复用性高 ： fetch-stock-price 技能既可以被投资分析Agent使用，也可以被新闻摘要Agent使用。
  • 易于维护 ：当股价API变更时，你只需要修改 fetch-stock-price 这一个技能。
  • 便于组合 ：AI智能体可以灵活地在一个会话中串联调用多个小型技能，完成复杂任务。例如，先调用 search-web 查找资料，再调用 summarize-text 进行总结，最后调用 save-to-notion 保存结果。

4.3 本地开发与调试工作流

对于技能开发者，一个高效的本地工作流至关重要：

  1. 使用符号链接（Symlink）进行实时开发 ：你可以在你的项目开发目录（如 ~/dev/my-skills/ ）里创建技能。然后，在 ~/.osm/skills/ 目录下为它创建一个符号链接。

    # 在开发目录创建技能
cd ~/dev/my-skills
osm create my-new-skill
# 创建符号链接，使AI能实时访问开发中的技能
ln -s ~/dev/my-skills/my-new-skill ~/.osm/skills/my-new-skill

    这样，你在 ~/dev/my-skills/my-new-skill/SKILL.md 中的任何修改，都会立即反映在AI智能体可加载的技能中，无需反复执行 osm install 或 osm publish 。

  2. 建立版本控制习惯 ：虽然 osm 本身管理发布版本，但你的技能源代码（尤其是如果你技能包含自定义的API密钥配置文件或辅助脚本时）应该用Git进行管理。为每个技能建立一个独立的Git仓库，便于追踪更改和协作。

  3. 利用 osm info 进行对比 ：当你从社区安装了一个优秀的技能，想学习其写法时， osm info <skill-name> 命令能让你看到其完整的 SKILL.md 内容，这是非常好的学习材料。

5. 常见问题与故障排除实录

在实际使用和开发 osm 技能的过程中，你可能会遇到以下典型问题。这里记录了我的排查思路和解决方法。

5.1 安装与网络问题

问题：执行 osm install 时速度很慢或失败，提示网络错误。

  • 排查思路 ：

    1. 检查网络连通性 ：首先 ping www.osmagent.com ，看是否能通。如果不通，可能是DNS或防火墙问题。
    2. 检查缓存 ：运行 ls -la ~/.osm/cache/ ，查看是否有之前下载过的、同技能不同版本的缓存包。 osm 在网络失败时会尝试使用缓存。
    3. 查看详细日志 ：有些错误信息可能被隐藏。可以尝试设置环境变量 DEBUG=* 来获取更详细的输出（如果CLI支持的话），或者直接查看命令的原始错误信息。

  • 解决方案 ：

    • 如果是临时网络问题，可以稍后重试。
    • 如果是公司网络限制，可能需要配置代理。 osm 的安装脚本和CLI通常遵循系统的HTTP_PROXY/HTTPS_PROXY环境变量。你可以在执行命令前临时设置： 
      export HTTPS_PROXY=http://your-proxy:port
curl -fsSL ... | bash  # 或直接运行 osm install
    • 如果缓存中有旧版本，你可以尝试手动将缓存包（ .tgz 文件）复制到技能目录并解压，但这属于高级操作，且可能版本不匹配。

5.2 技能加载与调用失败

问题：技能已安装（ osm list 可见），但AI智能体（如Cursor）似乎无法识别或调用它。

  • 排查思路 ：

    1. 确认AI智能体支持 ：首先确认你使用的AI智能体是否明确声明支持 OpenSkills 规范或 osm 技能。不是所有AI工具都兼容。
    2. 检查技能目录结构 ：确保 ~/.osm/skills/<skill-name>/ 目录下存在 SKILL.md 文件，且文件名和大小写完全正确。
    3. 检查SKILL.md格式 ：用文本编辑器打开 SKILL.md ，检查YAML Frontmatter的格式是否正确（开头结尾的 --- 不能少，缩进使用空格），以及 name 字段是否与目录名完全一致。
    4. 重启AI智能体 ：许多AI智能体只在启动时扫描技能目录。安装新技能后，尝试完全退出并重新启动你的AI应用。

  • 解决方案 ：

    • 对于Cursor，确保你开启了“Agent”模式，并且在其设置中正确配置了技能路径（通常默认就是 ~/.osm/skills ）。
    • 可以尝试运行 osm info <skill-name> ，如果命令能正确输出技能信息，说明 osm 本身识别该技能，问题很可能出在AI智能体一侧的加载机制上。
    • 编写一个最简单的测试技能（例如，只有一个打招呼功能的技能）进行安装和测试，以排除是特定技能编写错误导致的问题。

5.3 技能发布与版本冲突

问题：执行 osm publish 失败，提示“Skill already exists”或“Version conflict”。

  • 排查思路 ：

    1. 检查技能名所有权 ： osm whoami 确认当前登录的用户名。你只能更新你自己名下的技能。如果你尝试发布一个与他人同名的技能，自然会失败。
    2. 检查本地版本号 ：查看 SKILL.md 中的 version 字段。如果你之前已经发布过 my-skill@1.0.0 ，那么再次发布相同的 name@version 组合是不被允许的。
    3. 检查全局注册表 ：去 https://osmagent.com 网站搜索你的技能名，看看是否已被他人发布。

  • 解决方案 ：

    • 如果技能名已被占用，你需要修改 SKILL.md 中的 name 字段，换一个独一无二的名字。
    • 如果是版本冲突，你必须提升版本号。遵循 语义化版本 规范是一个好习惯：修复bug升修订号（ 1.0.0 -> 1.0.1 ），增加向后兼容的新功能升次版本号（ 1.0.1 -> 1.1.0 ），进行不兼容的更新升主版本号（ 1.1.0 -> 2.0.0 ）。修改 version 后，再次运行 osm publish 即可。

5.4 SKILL.md编写导致AI行为异常

问题：AI要么不调用技能，要么错误地调用技能，或者对技能结果的解读很奇怪。

  • 排查思路 ： 这几乎总是 SKILL.md 指令编写的问题。你需要像一个调试程序一样调试你的提示词。

    1. 不调用 ：检查“触发条件”是否写得太模糊或太严格。AI可能无法理解“在适当的时候”这种表述。尝试将其具体化为更场景化的描述。
    2. 错误调用 ：检查工具的参数定义是否清晰。AI可能会误解参数的类型或含义。确保每个参数都有示例。
    3. 结果解读错误 ：检查“回复格式”部分。你是否明确要求AI“首先…然后…最后…”？你是否要求它对原始数据做总结，而不是直接罗列？指令越明确，输出越可控。

  • 解决方案 ：

    • 迭代测试 ：这是唯一的办法。修改 SKILL.md -> 保存 -> 在AI对话中测试 -> 观察结果 -> 分析问题 -> 再次修改。这是一个需要耐心的过程。
    • 借鉴优秀案例 ：多使用 osm search 和 osm info 查看社区里高星或高频安装的技能，学习他们是如何结构化指令、描述参数和处理边界的。
    • 简化初始版本 ：先实现一个最小可行版本（MVP）。例如，第一个版本只让AI返回固定文本。确保这个基础流程能跑通后，再逐步增加复杂的逻辑和判断条件。

我个人在深度使用 osm 构建了十几个技能后，最大的体会是：它不仅仅是一个工具，更是一种思维方式的转变。它将AI能力的扩展从“提示词工程”的玄学，部分地拉回到了“软件工程”的轨道上，带来了可复用、可版本化、可分享的确定性。虽然目前生态还在早期，技能的质量参差不齐，但正是这种开放性，给了每个开发者参与塑造未来AI工具生态的机会。从解决自己的一个小痛点开始，编写并分享你的第一个技能，你可能会发现，为AI赋能的过程，比自己想象的要简单和有成就感得多。

# AI智能体
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

工具调用管线断点续跑难题：状态机设计如何平衡开发与运维视角

avatar 龙虾开发者社区
cover

OpenClaw 生产可观测性实践：为什么我们最终选择分级 Trace 方案

avatar 龙虾开发者社区
cover

ClawOS 作为 Agent 宿主：不可变根文件系统下的风险隔离实践

avatar 龙虾开发者社区