Skilo：AI Agent技能分享的革命性工具，链接即安装

1. 项目概述：Skilo，一个为AI Agent技能分享而生的“链接”

如果你和我一样，日常在Claude Code、Cursor、Codex这些AI编程工具里折腾，肯定遇到过这样的场景：同事在群里丢过来一个超好用的“代码审查”技能，你兴冲冲地想装上试试，结果发现对方给的是一个GitHub仓库链接。接下来就是一系列标准操作：克隆仓库、找到SKILL.md文件、手动复制到本地工具的技能目录、检查依赖、配置环境……一套流程下来，热情都凉了半截。更别提有时候对方只是口头描述，连个仓库都没有。

这就是Skilo要解决的问题。它把“分享一个AI技能”这件事，简化到了极致——就像分享一个网页链接那么简单。你不再需要关心背后的GitHub仓库、复杂的项目结构或者团队内部的技能清单。skilo share ./my-skill，生成一个短链接；skilo add skilo.xyz/s/xxx，技能就装好了。整个过程，没有注册，没有复杂的配置，甚至不需要你有GitHub账号。它瞄准的就是开发者之间那种即时、轻量、点对点的技能传递需求，尤其是在没有现成代码仓库流程、或者不想把内部工具技能公开到大型发现平台的场景下。

简单来说，Skilo是一个命令行工具和配套的Web服务，它重新定义了AI Agent技能的分享方式：从“分享一个项目”变成了“分享一个链接”。这对于需要快速在团队内部同步最佳实践、或者想和朋友分享一个刚调教好的提示词技能的开发者来说，简直是生产力利器。

2. 核心设计思路：为什么是“链接优先”？

在深入命令行细节之前，理解Skilo背后的设计哲学至关重要。这决定了它和市面上其他技能平台（比如Vercel的skills.sh）的根本区别。

2.1 定位差异：发现 vs. 传递

Vercel的skills.sh更像是一个“技能应用商店”或“技能发现平台”。它提供了排行榜、搜索、分类浏览，鼓励开发者将技能公开，供社区发现和使用。它的核心价值在于“发现优秀的公开技能”。

而Skilo的基因是“传递”。它的首要目标是解决“我手头有一个现成的技能文件夹，如何最快速、最无摩擦地把它交给另一个人（或另一台机器）？”这个问题。这个“另一个人”可能是你的同事、你的小号、或者你在另一个AI工具里的自己。因此，Skilo默认的分享模式是“非公开”的，生成的链接只有知道的人才能访问和安装。它不追求技能的曝光度，而是追求传递的效率和私密性。

这种设计带来了几个关键特性：

1. 零门槛分享：无需登录，无需创建项目清单，本地文件夹直接变链接。
2. 灵活的分享策略：你可以创建一次性链接、有效期一小时的链接、最多使用5次的链接，甚至给链接加密码。这非常适合分享还在测试中的、或包含敏感信息的技能。
3. 对私有和临时场景友好：很多内部工具技能并不适合公开，Skilo的“非公开”默认行为完美契合。

2.2 技术实现：从文件夹到可验证的包

Skilo的魔法在于它如何将一个本地的技能文件夹，变成一个安全、可验证、可通过链接分发的实体。这个过程大致分为三步：

第一步：本地打包与签名当你运行skilo share ./my-skill时，CLI工具会做以下几件事：

1. 读取与验证：检查目标路径下是否存在有效的SKILL.md文件（这是大多数AI Agent技能的标准入口文件）。
2. 创建清单：生成一个.skilo-manifest文件，里面包含了技能的名称、版本、创建时间、文件结构树以及每个文件的SHA-256哈希值。这个清单是后续所有验证的基础。
3. （可选）签名：如果你已经通过skilo login登录并拥有一个已验证的身份，CLI会使用你的私钥对这个清单进行Ed25519签名。这为技能提供了发布者身份验证。
4. 打包：将SKILL.md、技能代码文件、资源文件以及.skilo-manifest一起打包成一个压缩的.skl文件格式。这个包是自包含的。

第二步：上传与链接生成打包好的.skl文件会被上传到Skilo的后端服务（默认是官方的 skilo.xyz，也支持自托管）。后端服务接收到文件后：

1. 存储：将文件包存储到对象存储（如Cloudflare R2）。
2. 生成唯一ID：为这个技能包生成一个短而唯一的标识符（如a3xK9mP2）。
3. 创建数据库记录：在数据库（如Cloudflare D1）中创建一条记录，关联这个ID、文件存储位置、元数据（如过期时间、使用次数上限、密码哈希等）以及发布者信息。
4. 返回链接：将形如https://skilo.xyz/s/a3xK9mP2的链接返回给用户。

第三步：安装与验证当另一个用户运行skilo add https://skilo.xyz/s/a3xK9mP2时：

1. 解析链接：CLI从链接中提取技能ID。
2. 获取元数据：向Skilo后端请求该ID对应的技能元数据。后端会检查链接是否过期、使用次数是否超限、是否需要密码等。
3. 下载包：验证通过后，下载对应的.skl文件包。
4. 解压与验证：解压文件包，读取.skilo-manifest。重新计算本地文件的SHA-256哈希，与清单中的记录比对，确保文件在传输过程中未被篡改。
5. （可选）验证签名：如果清单包含Ed25519签名，CLI会使用对应的公钥验证签名，确认发布者身份。
6. 安装到目标工具：根据自动检测或用户指定的参数，将技能文件复制到对应AI工具的技能目录（如~/.cursor/skills/my-skill/）。

整个流程确保了技能从分享到安装的完整性、安全性和可追溯性，同时保持了用户操作的极度简洁。

3. 从安装到上手：完整实操指南

理解了核心思路，我们来看看如何把Skilo用起来。我会从最基础的安装开始，带你走完分享和安装一个技能的完整闭环，并穿插我实际使用中总结的技巧和容易踩的坑。

3.1 环境准备与CLI安装

Skilo的核心是一个Node.js命令行工具。确保你的系统已经安装了Node.js（版本16或以上）和npm。

安装方式有两种：

1. 全局安装（推荐用于高频使用）

   npm install -g skilo-cli

   安装后，你就可以在任何终端直接使用skilo命令了。这种方式最方便，CLI还会在后台静默自我更新，确保你一直用的是最新版。

2. 使用npx（免安装，适合尝鲜或一次性操作）

   npx skilo-cli <command>

   每次运行npx skilo-cli，它都会自动获取最新版本并执行。对于不常使用的机器，或者想在CI/CD流水线中临时使用，这种方式很干净。

实操心得：关于自动更新Skilo CLI的自动更新机制很贴心，但有时在受限的网络环境或CI中可能造成问题。如果你需要禁用这个功能，可以设置环境变量：

• SKILO_NO_AUTO_INSTALL=1: 禁用npx运行时的自动安装/更新检查。
• SKILO_NO_AUTO_UPDATE=1: 禁用已全局安装的CLI的自我更新。 在Docker镜像或自动化脚本中，我通常会设置这些变量以保证行为一致。

安装完成后，运行skilo --help可以查看所有可用命令和简要说明，确认安装成功。

3.2 创建并分享你的第一个技能

假设你已经在Claude Code里调教好了一个用于“生成JSDoc注释”的技能，文件夹路径是~/dev/skills/jsdoc-generator。

基础分享：

cd ~/dev/skills skilo share ./jsdoc-generator

几秒钟后，终端会输出一个类似https://skilo.xyz/s/a3xK9mP2的链接。这个链接现在就可以发给任何人了。他们不需要登录Skilo，直接就能用这个链接安装技能。

进阶分享选项：

• 一次性链接：skilo share ./jsdoc-generator --one-time。链接在被成功安装一次后即刻失效，适合分享极其敏感或一次性的内容。
• 限时链接：skilo share ./jsdoc-generator --expires 1h。链接在1小时后失效。--expires参数支持1h(1小时)、30m(30分钟)、7d(7天) 等格式。
• 限额链接：skilo share ./jsdoc-generator --uses 5。链接最多只能被成功安装5次。
• 密码保护：skilo share ./jsdoc-generator --password。执行后会提示你输入并确认密码。对方安装时也需要提供这个密码。
• 公开列出：skilo share ./jsdoc-generator --listed。默认分享是“非公开”的，只有有链接的人能访问。加上--listed后，这个技能会出现在你的公开技能列表中（需要先登录），也可能被搜索到。

注意事项：分享的“粒度”skilo share命令是针对一个技能文件夹操作的。这个文件夹必须包含一个有效的SKILL.md文件。如果你有一个包含多个子技能的大仓库，你需要进入每个子技能的目录分别分享，或者使用后面会讲到的skilo pack命令来打包分享。

3.3 安装他人分享的技能

拿到一个Skilo链接后，安装过程简单得令人发指。

基础安装：

skilo add https://skilo.xyz/s/a3xK9mP2

或者，因为域名固定，甚至可以省略协议：

skilo add skilo.xyz/s/a3xK9mP2

CLI会自动检测你系统上安装了哪些支持的AI工具（如Claude Code, Cursor等），并尝试将技能安装到检测到的工具中。如果只检测到一个工具，它会直接安装；如果检测到多个，在交互式终端中它会让你选择；在非交互式环境（如脚本）中，它会报错并提示你明确指定目标。

指定安装目标：你可以用标志位明确告诉Skilo把技能装到哪里：

• --cc或--claude-code: 安装到 Claude Code
• --cursor: 安装到 Cursor
• --codex: 安装到 Codex
• --roo: 安装到 Roo
• 可以同时指定多个，例如--cursor --codex会同时安装到这两个工具。

安装前的检查：如果你对来源不放心，可以先“窥探”一下这个技能包里有什么，再决定是否安装：

skilo inspect https://skilo.xyz/s/a3xK9mP2

这个命令会列出技能的名称、描述、包含的文件、哈希值以及发布者信息（如果有签名）。加上--json标志可以输出机器可读的JSON格式，方便集成到其他流程中。

3.4 技能包（Pack）：批量分享与管理

当你有一组相关的技能想一起分享时（比如“前端开发入门包”，包含ESLint配置、组件生成、API请求等多个技能），逐个分享链接很麻烦。这时可以使用skilo pack命令。

创建一个技能包：

skilo pack ./skills/eslint-helper ./skills/react-component-gen https://skilo.xyz/s/abc123 --name "Frontend Starter Pack"

skilo pack可以接受本地技能路径、其他Skilo链接、甚至GitHub仓库引用（如flrabbit/original-landing-page-builder）作为源。它会将这些引用打包成一个新的“包链接”。

分享和安装包：创建成功后，你会获得一个包链接，如https://skilo.xyz/p/def456。分享这个链接，别人安装时，会看到一个交互式选择器，默认选中包内所有技能，用户可以取消勾选不想安装的。

选择性安装包内技能：安装时也可以直接用参数选择：

• --only reviewer,planner: 只安装包中名为“reviewer”和“planner”的技能。
• --skip debugger: 安装除“debugger”之外的所有技能。

避坑技巧：包的“派生”特性这里有一个非常巧妙的设计：当用户通过交互式选择器取消勾选某些技能后，Skilo并不会直接安装选中的部分，而是会基于用户的选择生成一个新的、派生出来的包链接，然后从这个新链接安装。这样做的好处是，原始的包链接始终保持不变且完整，而派生出的子集链接也可以继续被分享。这个设计保证了分享链条的持久性和灵活性。

4. 高级用法与集成场景

掌握了基本操作后，Skilo还有一些强大的高级功能，能让你在更复杂的开发工作流中游刃有余。

4.1 与现有GitHub技能仓库的兼容

很多团队或项目已经按照Vercel skills.sh的规范，将技能存放在GitHub仓库中（通常是仓库根目录或一个skills/子目录下，每个技能一个文件夹，内含SKILL.md）。Skilo完全兼容这种模式。

从GitHub仓库安装特定技能：

skilo add owner/repo --skill resolve-issue --cursor

这个命令会克隆（或获取）指定的GitHub仓库，在仓库中寻找名为resolve-issue的技能文件夹，并将其安装到Cursor。

探索仓库内的所有技能：

skilo add owner/repo --list

这个命令不会安装任何技能，而是列出该仓库中发现的所有技能目录，方便你浏览。

安装仓库内的所有技能：

skilo add owner/repo --all

这会将该GitHub仓库中发现的所有技能都安装到你的本地工具中。

直接从GitHub tree链接安装：如果你在GitHub上浏览时，直接复制了某个技能文件夹的浏览器地址，也可以直接安装：

skilo add https://github.com/user/repo/tree/main/skills/resolve-issue --cursor

4.2 在AI工具间同步技能

你可能在多个AI工具中工作（比如在Claude Code中写业务逻辑，在Cursor中调试）。Skilo可以轻松地在它们之间同步技能。

同步所有技能：

skilo sync claude opencode

这个命令会将Claude Code中安装的所有技能，复制一份到OpenCode中。

同步特定技能：

skilo import claude --skill reviewer --oc

这个命令会从Claude Code中导出名为reviewer的技能，然后安装到OpenCode (--oc)。

批量安装到多个工具：

skilo add https://skilo.xyz/s/a3xK9mP2 --codex --cursor --roo

一个链接，同时安装到三个不同的工具，效率极高。

4.3 发布到技能注册表（需登录）

虽然Skilo的精髓在于快速、私密的链接分享，但它也支持更正式的“发布”流程，类似于npm publish。这适合那些你希望长期维护、并可能拥有一个固定命名空间的技能。

登录与身份管理：

skilo login your-username

首次登录会引导你通过GitHub OAuth或邮箱验证来创建/关联一个身份。登录后，你就拥有了一个专属的命名空间（如your-username/）。

发布技能：在你本地的技能目录中，运行：

skilo publish --listed

--listed表示公开列出，--unlisted则是非公开（但仍有固定名称，如your-username/skill-name）。发布后，别人就可以通过skilo add your-username/skill-name来安装你的技能了，无需再通过有时效的分享链接。

管理已发布技能：

• skilo list --published: 列出你名下所有已发布的技能。
• skilo deprecate your-username/skill-name: 标记某个技能版本为已弃用，安装时会收到警告。
• skilo yank your-username/skill-name@1.0.0: 彻底移除某个特定版本，使其无法再被安装。

4.4 为自动化流程与AI Agent设计的使用模式

Skilo的CLI设计充分考虑到了非交互式环境，比如在CI/CD流水线中初始化环境，或者让AI Agent自己管理技能。

非交互式环境指定目标：在脚本或Agent中，为了避免CLI因检测到多个工具而等待交互，可以预先设置环境变量：

export SKILO_TARGETS=codex,cursor skilo add https://skilo.xyz/s/a3xK9mP2

这样，Skilo就会明确地将技能安装到Codex和Cursor，而不会弹出选择提示。

JSON输出模式：几乎所有主要命令都支持--json标志，输出结构化的JSON数据，方便被其他程序解析。

skilo inspect https://skilo.xyz/s/a3xK9mP2 --json skilo share ./my-skill --json

这对于构建自动化工具或让AI Agent读取技能元数据非常有用。

引导式入口：直接运行npx skilo-cli（不带任何命令）会进入一个交互式的引导模式，通过问答的方式帮助你完成分享或安装。这对于不熟悉命令行的用户或者初次接触时非常友好。

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

在实际使用中，你可能会遇到一些问题。下面是我和社区里遇到的一些典型情况及其解决方法。

5.1 安装失败：“No supported tools detected”

问题描述：运行skilo add <link>时，提示未检测到任何支持的AI工具，安装失败。

原因分析：

1. 你确实没有安装任何Skilo支持的AI工具（Claude Code, Cursor, Codex等）。
2. 工具已安装，但Skilo无法找到其标准技能目录。可能是自定义了安装路径，或者工具版本较旧目录结构不同。
3. 在无GUI的服务器环境或Docker容器中运行。

解决方案：

• 方案A：明确指定目标。如果你知道技能应该装到哪里，使用目标标志，例如skilo add <link> --cc（假设你想装到Claude Code，即使没检测到）。
• 方案B：设置回退目标。通过环境变量SKILO_DEFAULT_TARGET设置一个默认工具。例如export SKILO_DEFAULT_TARGET=claude。
• 方案C：手动导出文件。使用skilo add <link> --dry-run或skilo inspect <link>查看技能内容，然后手动将文件复制到你工具的技能目录。技能目录路径可以参考上文“Supported Tools”表格。
• 方案D：检查工具安装。确认你安装的AI工具是否在支持列表中，并且是最新版本。

5.2 分享失败：“Invalid SKILL.md” 或 “Skill validation failed”

问题描述：运行skilo share ./path时，提示技能无效。

原因分析：

1. 目标路径下没有SKILL.md文件。
2. SKILL.md文件格式不符合要求（例如，缺少必需的元数据如name,description）。
3. 技能文件夹中包含不安全的符号链接或权限异常的文件。

解决方案：

• 运行skilo validate ./path命令。它会详细检查SKILL.md的格式并给出具体错误信息，比如“Missing required field 'name'”。
• 确保SKILL.md至少包含以下基本结构：

  # 技能名称 一段清晰的技能描述。 ## 触发器 - `@skill-name 做一些事情`

• 检查技能文件夹中是否包含非必要的、过大的或二进制文件。分享前最好保持技能的精简。

5.3 链接失效：“Link expired” 或 “Maximum uses exceeded”

问题描述：尝试安装一个Skilo链接时，提示链接已过期或使用次数已达上限。

原因分析：分享者在创建链接时设置了--expires或--uses限制。这是一种安全特性，确保链接只在特定时间或次数内有效。

解决方案：联系技能的分享者，请求他重新分享一个新的链接。作为分享者，如果你希望链接长期有效，创建时不要添加--expires或--uses参数（但要注意，无限制的链接一旦泄露，可能被他人随意安装）。更安全的方式是使用--password为长期链接添加密码保护。

5.4 从GitHub安装缓慢或超时

问题描述：使用skilo add owner/repo或从GitHub URL安装时，速度很慢，甚至超时。

原因分析：Skilo需要克隆或获取GitHub仓库的内容。如果仓库很大，或者网络连接GitHub不畅，就会导致延迟。

解决方案：

• 使用--skill精确指定：如果你知道需要的技能名称，使用--skill <name>，Skilo会尝试使用GitHub API只获取必要的文件，而不是克隆整个仓库，这通常快得多。
• 使用Skilo链接替代：如果这个技能有对应的Skilo分享链接，直接使用链接安装。Skilo链接背后是压缩包，下载速度远快于克隆Git仓库。
• 检查网络：确保你的网络可以正常访问api.github.com。

5.5 自托管部署问题

问题描述：按照官方文档自托管Skilo后端时，遇到数据库初始化、Worker部署或配置错误。

原因分析：自托管涉及Cloudflare Workers、D1数据库、R2存储和KV等多个服务，配置步骤较多，容易出错。

解决方案与排查清单：

1. 仔细核对wrangler.toml：确保database_id、bucket_name、kv_namespace_id等字段的值与你通过wrangler命令创建资源时获得的ID完全一致。一个字符错误都会导致部署失败。
2. 按顺序执行SQL：运行pnpm dlx wrangler d1 execute skilo --file=schema.sql --remote时，确保schema.sql文件路径正确，且D1数据库已成功创建。
3. 检查环境变量：前端站点（@skilo/site）需要配置指向你自托管API Worker的VITE_API_URL。在wrangler.toml或部署平台的设置中正确配置。
4. 查看Worker日志：部署后，在Cloudflare Dashboard的Workers & Pages部分，找到你的API Worker，查看其“日志”面板。任何运行时错误（如数据库连接失败、R2权限错误）都会在这里显示，这是最直接的调试信息。
5. 分步部署：先单独部署API Worker (pnpm --filter @skilo/api deploy)，测试其端点（如GET /health）是否能正常响应。成功后再部署前端站点。

6. 安全、信任与架构考量

对于一个负责分发和执行代码（尽管是提示词和脚本）的系统，安全是重中之重。Skilo在这方面做了多层设计。

6.1 信任模型的三层阶梯

1. 匿名技能：任何人不登录即可分享。这是最便捷但信任度最低的层级。安装时，Skilo会提供文件的SHA-256校验和供你核对。最佳实践是，对于匿名链接，务必使用skilo inspect命令仔细检查内容，尤其是index.js等可执行文件，确认无误后再安装。

2. 认领技能：一个已登录的用户可以“认领”一个之前匿名分享的技能，将其归到自己名下。这增加了可追溯性。

3. 验证技能：发布者通过GitHub OAuth或邮箱验证了身份。其发布的技能会使用Ed25519算法进行数字签名。安装时，CLI会自动验证签名，确认技能确实来自该发布者且未被篡改。这是最高信任层级。

6.2 安装前的安全检查清单

养成以下习惯，能极大降低风险：

• 始终先inspect：对于任何来源的链接，尤其是匿名链接，先用skilo inspect <link>查看详情。
• 审查SKILL.md：仔细阅读技能描述、触发器和预期行为，判断其是否合理。
• 检查代码文件：如果技能包含index.js、main.py等文件，在inspect的输出中查看其内容。警惕任何进行网络请求、文件系统操作（尤其是写操作）或执行外部命令的代码。
• 使用skilo audit：定期在已安装技能的AI工具目录下运行skilo audit。这个命令会扫描所有已安装技能，检查其清单的完整性和签名状态，并标记出高风险项目（如匿名技能、未经验证的技能）。
• 利用沙盒环境：如果条件允许，可以先在一个隔离的虚拟机或容器环境中安装和测试未知技能。

6.3 技术架构带来的优势与限制

Skilo选择基于Cloudflare Workers无服务器架构构建，这带来了明显的优点和些许限制：

优势：

• 极速全球分发：技能包存储在Cloudflare R2，通过其全球网络缓存，确保世界各地的用户都能快速下载。
• 无服务器成本低：对于个人或中小规模使用，Worker的免费额度通常足够，成本可控。
• 开发部署简单：整个项目使用现代JavaScript工具链，前后端清晰，便于社区贡献和自行修改。

限制与考量：

• 供应商锁定：自托管版本也深度依赖Cloudflare的生态系统（D1, R2, KV）。如果你需要迁移到其他平台，工作量较大。
• 无服务器冷启动：免费Worker在闲置后会有冷启动延迟，可能导致API偶尔响应稍慢。对于高频使用的企业，可能需要升级到付费计划。
• 功能边界：作为一个专注于“传递”的工具，它没有内置的版本管理、复杂的权限系统或团队协作功能。这些更适合通过GitHub仓库 + Skilo链接的组合，或者未来的企业版来解决。

从我个人的使用体验来看，Skilo精准地切入了一个细分但高频的需求点，用极简的“链接”抽象屏蔽了底层所有的复杂性。它可能不会取代GitHub作为技能源码托管和协作的平台，但它作为“技能交付的最后一步”，极大地优化了开发者之间的协作体验。无论是快速分享一个调试技巧给同事，还是为自己在多台设备间同步配置，Skilo都提供了一个近乎完美的解决方案。它的成功在于克制地做好了这一件事，并且做得足够优雅和可靠。