AI智能体技能开发实战：基于Agent Skills规范连接Bitrefill消费平台

1. 项目概述：为AI智能体赋予真实世界的消费能力

最近在折腾AI智能体（AI Agent）时，我一直在思考一个问题：如何让这些聪明的“数字大脑”不只是停留在代码层面，而是能真正地“动手”去完成一些现实世界里的任务？比如，帮我查查某个电商平台有没有优惠，或者直接下单买一张礼品卡。这听起来像是科幻电影里的场景，但得益于像bitrefill/agents这样的开源项目，它正在变成现实。

简单来说，bitrefill/agents是一个专为AI智能体设计的“技能包”或“工具箱”。它允许像 Claude Code、Cursor 这类AI编程助手，直接与 Bitrefill 这个全球性的数字商品平台进行交互。Bitrefill 本身是一个支持用加密货币（如比特币、闪电网络）或信用卡购买全球数千种礼品卡、手机话费充值、eSIM 流量包的服务。而这个项目，则是在AI智能体和这个现实世界的消费平台之间，架起了一座桥梁。

想象一下，你正在和你的AI编程伙伴讨论一个项目，突然需要为某个海外服务的测试账户购买一张礼品卡。你不再需要手动打开浏览器、搜索、比价、支付。你只需要告诉你的AI助手：“嘿，帮我找一张价值50美元的亚马逊美国礼品卡，用我的账户余额支付。” 接下来，AI助手就能利用bitrefill/agents提供的技能，自动完成搜索、下单、支付，并把兑换码提供给你。这极大地提升了开发者和用户在特定场景下的效率，尤其是涉及跨国、跨币种的小额数字商品交易时。

这个项目非常适合两类人：一是热衷于探索AI智能体边界、希望为其增加实用外部工具能力的开发者；二是在日常开发或运营中，确实有频繁、小额购买全球数字商品需求的用户。通过将消费能力“封装”成AI可调用的技能，它开启了一种全新的人机协作模式。

2. 核心架构与技能设计解析

2.1 基于 Agent Skills 规范的标准化设计

bitrefill/agents项目的核心基石是其对 Agent Skills 规范的严格遵守。理解这一点至关重要，因为它决定了项目的通用性和可集成性。Agent Skills 规范可以看作是AI智能体生态中的“USB接口标准”。它定义了一套统一的技能描述、注册和调用方式，确保不同厂商开发的AI智能体（如Anthropic的Claude、Cursor AI等）能够无缝地发现、安装和使用来自不同开发者的技能。

在这个项目中，.claude-plugin/marketplace.json文件就是这个“USB设备”的驱动描述文件。它向支持该规范的AI智能体平台声明：“这里有一个技能包，包含了以下功能……”。这种标准化带来的最大好处是解耦。技能开发者无需为每个AI平台单独适配，只需遵循同一套规范；AI智能体平台也无需内置所有功能，可以通过“应用商店”模式动态扩展能力。这极大地繁荣了生态。

从技术实现上看，一个Skill（技能）通常包含几个关键部分：

1. 元数据（Metadata）：在SKILL.md文件的YAML frontmatter中，定义了技能的name（名称）和description（描述）。这相当于技能的“身份证”，AI智能体通过读取这些信息来了解这个技能是干什么的。
2. 操作指令（Instructions）：这是技能的核心，用自然语言详细描述了该技能能做什么、在什么场景下使用、需要什么输入参数、会返回什么结果。AI智能体的大语言模型（LLM）部分会理解这些指令，并在合适的时机调用它。
3. 执行后端（Backend）：指令描述了“做什么”，而实际“怎么做”则由后端的代码或API调用实现。在bitrefill-website技能中，后端可能是模拟浏览器操作或调用Bitrefill的公开API；在bitrefill-cli技能中，后端则是封装了对@bitrefill/cli命令行工具的调用。

注意：技能的名称（name）必须全部小写，并使用连字符分隔，且必须与存放该技能的目录名完全一致。例如，技能目录名为bitrefill-website，那么SKILL.md中的name字段也必须是bitrefill-website。这是规范强制要求，不一致会导致技能无法被正确识别和加载。

2.2 两大核心技能：bitrefill-website与bitrefill-cli的深度对比

项目目前提供了两个技能，它们目标一致，但实现路径和适用场景有显著区别。理解它们的差异，有助于你在不同情境下做出正确选择。

bitrefill-website技能：基于网站交互的通用方案这个技能的定位是“通用”和“兼容”。它的工作方式，很可能是通过模拟用户与Bitrefill官网（ https://www.bitrefill.com ）的交互来实现的。例如，使用无头浏览器（Headless Browser）或自动化测试工具（如Puppeteer, Playwright）来导航网页、填写表单、点击按钮。

• 优点：

  • 无需额外凭证：通常只需要Bitrefill网站的用户账号（邮箱/密码）或会话（Session），而不需要处理专门的API密钥。
  • 功能同步：由于直接操作网站，任何网站上可见的新功能、新商品或UI改动，理论上技能都能立即支持，与用户手动操作看到的内容完全一致。
  • 支付方式全面：支持网站上所有可用的支付方式，包括加密货币（比特币、闪电网络）和传统信用卡/借记卡。

• 缺点与挑战：

  • 稳定性依赖前端：网站前端UI的任何改动（哪怕是按钮ID、CSS选择器的微小变化）都可能导致自动化脚本失效，需要持续维护。
  • 性能开销：启动和运行无头浏览器比直接调用API要消耗更多的计算资源和时间。
  • 容易被反爬：频繁的自动化访问可能触发网站的反爬虫机制，导致IP被限制或要求验证码。
  • 操作步骤冗长：模拟点击、等待页面加载等步骤使得整个流程比API调用慢。

bitrefill-cli技能：基于命令行工具的高效方案这个技能则代表了“高效”和“专有”。它并非直接操作网站，而是封装了Bitrefill官方提供的命令行工具@bitrefill/cli。这意味着它是在与一个为自动化而生的专用接口打交道。

• 优点：

  • 高效稳定：CLI工具通常提供简洁、稳定的命令，执行速度远快于模拟浏览器操作，且不受前端UI变化影响。
  • 为自动化而生：CLI的输出格式（如JSON）易于被程序解析，非常适合AI智能体提取结构化信息。
  • 支付方式聚焦：特别强调了使用x402 over Base (USDC)或店铺余额进行支付。x402是一个基于Base链（Coinbase推出的Layer 2网络）的支付协议，使用USDC稳定币。这意味着这个技能深度集成了加密货币支付流，非常适合Web3原生场景下的自动化消费。

• 缺点与考量：

  • 需要API密钥：使用CLI通常需要先在Bitrefill账户中生成并配置API密钥，增加了初始设置步骤。
  • 功能可能滞后：CLI工具的功能更新可能稍慢于官方网站，一些最新的商品或促销可能无法立即通过CLI获取。
  • 支付方式限制：主要面向加密货币支付，对于只想用信用卡支付的用户来说可能不适用。

选择建议：

• 如果你是普通用户，偶尔使用，且习惯信用卡或常规加密货币支付，bitrefill-website技能更直观，更贴近你的手动操作习惯。
• 如果你是开发者或高频用户，追求自动化流程的稳定性和速度，并且乐于使用USDC等加密资产进行支付，那么bitrefill-cli技能是你的不二之选。它更像是为“机器对机器”（M2M）交易打造的管道。

3. 环境准备与技能安装实操

3.1 前置条件与账户准备

在开始安装技能之前，你需要确保基础环境就绪，并根据你选择的技能准备好相应的账户和凭证。

1. 基础运行环境：

• Node.js 与 npm：项目的安装工具npx依赖于Node.js环境。请确保你的系统已安装Node.js（建议使用LTS版本，如18.x或20.x）和配套的npm包管理器。你可以在终端中运行node --version和npm --version来验证。
• 目标AI智能体环境：你需要一个支持 Agent Skills 规范的AI智能体工作环境。目前已知兼容的有：
  • Claude Code：Anthropic为开发者设计的AI编程工具。
  • Cursor：一款深度融合了AI辅助的代码编辑器。
  • ClawdBot或其他声明支持该规范的Agent平台。 请确保你已在目标工具中登录了你的账户，并且该工具处于运行状态。

2. 账户与凭证准备：

• 对于bitrefill-website技能：你需要一个有效的 Bitrefill 用户账号。建议提前注册并完成邮箱验证。为了自动化流程顺利，你可能还需要在Bitrefill账户设置中检查是否有两步验证（2FA），并考虑在测试阶段暂时禁用，或研究如何让自动化脚本处理2FA（这通常比较复杂）。
• 对于bitrefill-cli技能：
  1. 拥有Bitrefill账户（同上）。
  2. 生成API密钥：登录Bitrefill后，通常在账户的“Settings”或“Developer”部分，可以找到创建API密钥的选项。生成后，你会得到类似brf_xxxxxx的密钥字符串。请像保护密码一样保护它，不要泄露。
  3. 准备加密货币支付方式：如果你计划使用x402 over Base支付，你需要一个兼容的钱包（如MetaMask），并确保在Base网络上有足够的USDC余额。如果使用店铺余额，则需要先通过网站用其他方式充值。

实操心得：强烈建议在正式让AI智能体操作你的主账户之前，先创建一个专门的测试账户。Bitrefill通常允许用较少的金额进行测试购买（例如购买1美元的礼品卡）。用测试账户来调试技能和自动化流程，可以避免因脚本错误导致主账户出现意外订单或支付问题。

3.2 技能安装命令详解与验证

安装过程通过npx命令完成，npx会临时下载并运行指定的npm包（在这里是skills这个命令行工具），而bitrefill/agents则是告诉这个工具要从哪里获取技能包。

通用安装命令：

npx skills add bitrefill/agents

这条命令执行后，skills工具会：

1. 从GitHub仓库bitrefill/agents拉取技能包。
2. 根据本地的AI智能体环境，尝试自动检测并安装到合适的位置（例如，Claude Code或Cursor的插件/技能目录）。
3. 过程中可能会与你交互，询问安装确认或目标路径。

指定AI智能体环境的安装命令：

npx skills add bitrefill/agents -a cursor -y

这个命令增加了两个参数，更适合自动化脚本或明确知道目标的情况：

• -a cursor：明确指定技能是安装给cursor这个AI智能体环境的。这避免了工具的自动检测环节，更加精准。
• -y：代表“yes”，自动确认所有安装提示。这在非交互式环境（如CI/CD流水线）或你确定要安装时非常有用。

安装后的验证步骤：安装成功后，如何确认技能已就绪？方法因AI智能体而异，但通常有以下几种：

1. 在AI对话中触发：在你的AI智能体（如Cursor的Chat面板）中，尝试输入与技能相关的指令，例如：“你能用Bitrefill技能帮我看看Steam的礼品卡吗？” 观察AI的回复。如果技能已正确加载，AI应该能理解你的请求，并可能会提示它正在使用或可以调用相关技能。
2. 查看技能列表：某些AI智能体平台可能有管理插件的界面。例如，在Cursor的设置中，寻找“Plugins”、“Extensions”或“Skills”相关页面，查看bitrefill-website和bitrefill-cli是否在已安装列表中。
3. 检查安装目录：对于高级用户，可以手动检查技能文件是否被复制到了正确的目录。对于Cursor，技能可能安装在~/.cursor/plugins或类似目录下；对于Claude Code，则可能在~/.claude-code/plugins。你可以看到以bitrefill-agents或类似命名的文件夹。

常见安装问题排查：

• 命令未找到 (npx: command not found)：这通常意味着Node.js没有正确安装或没有添加到系统PATH环境变量中。请重新安装Node.js。
• 安装过程报错 (网络或权限错误)：npx需要从网络下载资源。请检查你的网络连接，特别是能否正常访问GitHub。如果遇到权限错误（如写入特定目录失败），可以尝试用管理员/超级用户权限运行命令（在命令前加sudo，但需谨慎），或者检查目标目录的写入权限。
• AI智能体无法识别技能：首先确认安装时指定的-a参数是否正确对应了你使用的AI工具。其次，有些AI工具可能需要重启才能加载新安装的技能。尝试完全退出Cursor或Claude Code再重新打开。

4. 技能使用场景与实战指令解析

技能安装好后，关键在于如何有效地使用它。你需要用AI智能体能理解的自然语言去“驱动”这些技能。下面我将拆解两个技能的核心使用场景，并提供一些高成功率的指令范例。

4.1bitrefill-website技能：自然语言驱动的浏览与购买

这个技能的设计初衷是让AI能够像真人一样浏览网站。因此，你的指令应该尽可能贴近你平时对真人助手说的话。

核心使用场景与指令模板：

1. 搜索与查询产品信息：

   • 场景：你想了解某个品牌或某种类型的礼品卡在Bitrefill上是否有售，以及价格如何。
   • 高效指令：“请使用Bitrefill技能，帮我搜索一下‘Netflix’的礼品卡，看看有哪些面额可选，以及当前的价格是多少美元？”
   • 进阶指令：“我想给朋友送一个游戏相关的礼物，用Bitrefill查查‘PlayStation’、‘Xbox’和‘Steam’这三个品牌有哪些电子礼品卡，把面额和价格列个表给我看看。”
   • AI行为解析：AI会调用技能，模拟在Bitrefill网站搜索框输入关键词，进入产品页面，并抓取产品标题、可用面额、对应价格（可能包含加密货币折价）等信息，然后以结构化的方式回复给你。

2. 执行购买与支付：

   • 场景：确定商品后，你需要完成购买。
   • 高效指令：“帮我用Bitrefill购买一张价值25美元的亚马逊美国（Amazon US）礼品卡，用我的账户余额支付，收货邮箱填写myemail@example.com。”
   • 关键信息：这条指令包含了所有必要参数：商品（亚马逊美国礼品卡）、面额（25美元）、支付方式（账户余额）、交付信息（邮箱地址）。指令越完整，AI需要向你追问确认的次数就越少，成功率越高。
   • 支付方式补充：如果你想用加密货币支付，可以指定：“…，使用比特币（Bitcoin）支付。” 技能会引导至相应的支付网关。

3. 管理订单与使用产品：

   • 场景：购买后查看订单状态，或获取兑换码。
   • 高效指令：“查看我最近在Bitrefill下的订单状态。” 或 “我刚刚买了一张Google Play礼品卡，请把兑换码（redemption code）发给我。”
   • AI行为解析：AI会尝试登录你的账户（可能需要你提前在技能配置中提供会话信息或自动登录能力），进入“Orders”或“Purchases”页面，提取最新的订单信息或特定商品的详情，其中就包含兑换链接或直接显示码。

注意事项：由于bitrefill-website技能依赖于网页自动化，其稳定性不如API。在发出复杂指令（尤其是涉及多步骤购买）时，建议分步进行。例如，先搜索确认商品和价格，再单独发指令购买。这样可以避免在长流程中因页面加载超时等问题导致整个任务失败。同时，确保你的Bitrefill账户登录状态是有效的。

4.2bitrefill-cli技能：面向自动化的精准命令

bitrefill-cli技能的指令风格可以更“技术化”一些，因为它背后是精确的命令行工具。

核心使用场景与指令模板：

1. 通过CLI搜索产品：

   • 场景：快速、以编程方式获取商品数据。
   • 高效指令：“调用Bitrefill CLI技能，搜索所有包含‘esim’关键词的产品，并以JSON格式返回简要信息。”
   • 底层原理：这条指令很可能被转换为类似bitrefill-cli search --query esim --output json的命令执行。返回的数据结构清晰，便于AI后续处理或直接展示给你。

2. 使用加密货币完成一键购买：

   • 场景：这是该技能最强大的地方，实现完全无人值守的自动化购买。
   • 高效指令：“使用Bitrefill CLI，通过x402支付方式，购买一张50美元的Uber礼品卡，并发送到邮箱driver@example.com。使用我的默认API密钥和Base网络钱包。”
   • 关键点：
     • 支付方式：明确指定“x402 over Base (USDC)”。这要求你的@bitrefill/cli已预先配置好对应的钱包和网络。
     • 凭证：指令中提到的“默认API密钥”需要技能在前期配置中已经处理好（例如，通过环境变量BITREFILL_API_KEY读取）。你不需要在每次指令中重复输入密钥。
     • 自动化：这条指令一旦发出，AI会完成从查询商品ID、构造购买请求、发起区块链交易、确认支付到提交订单的全流程，无需你中途干预。

3. 查询余额与订单：

   • 场景：检查账户资产和消费记录。
   • 高效指令：“用CLI技能查一下我Bitrefill账户里还有多少店铺余额（store credit）？” 或 “列出我过去7天内通过CLI下的所有订单。”
   • 优势：CLI查询速度极快，返回的数据通常是结构化的（如JSON），AI可以轻松地将其整理成易读的表格或摘要。

两个技能的指令风格对比总结：

• bitrefill-website：你的指令更像是在描述任务（“帮我找找…”、“去买一个…”），AI负责理解意图并操作界面。
• bitrefill-cli：你的指令可以更接近下达命令（“搜索…”、“购买…并发送到…”），AI更像是一个执行精确脚本的调度员。

在实际使用中，你可以根据当下需求混合使用这两种风格的指令。例如，先用website技能浏览和比价，选定商品后，再用cli技能进行快速、稳定的自动化购买（前提是支付方式支持）。

5. 高级应用：贡献新技能与自定义开发

bitrefill/agents项目是开源的，这意味着你不仅可以使用现有技能，还可以为其贡献新的技能，或者基于此模式为你自己常用的服务创建技能。这对于希望深度定制AI智能体能力的开发者来说，是一个绝佳的实践机会。

5.1 技能创建流程与规范详解

根据项目CONTRIBUTING部分的指引，创建一个新技能需要遵循以下标准化步骤。这里我们以一个假设的技能bitrefill-invoice（用于管理Bitrefill发票）为例进行说明。

第一步：创建技能目录与核心文件

1. 在项目的skills/目录下，创建一个新的子目录，目录名即为技能名，必须全小写并用连字符分隔。

   mkdir skills/bitrefill-invoice

2. 在该目录下创建核心文件SKILL.md。这个文件是技能的“大脑”，AI通过阅读它来学习如何使用这个技能。

第二步：编写SKILL.md文件SKILL.md文件采用“YAML Frontmatter + Markdown内容”的格式。YAML部分提供机器可读的元数据，Markdown部分提供给人（和AI）阅读的详细指令。

--- name: bitrefill-invoice description: Allows the AI agent to list, download, and view invoices for past Bitrefill purchases. Use when the user asks about receipts, invoices, or purchase history for accounting or reimbursement purposes. --- # Bitrefill Invoice Manager Skill This skill enables the AI to interact with a user's Bitrefill invoice data. ## Capabilities - List all invoices within a date range. - Download a specific invoice as a PDF file. - View summary details of an invoice (invoice number, date, amount, status). ## How the AI should use this skill 1. When the user asks about invoices, receipts, or purchase history from Bitrefill, the AI should first determine the user's intent (e.g., list recent invoices, download a specific one). 2. To list invoices, the AI will need to know the date range (e.g., "last month", "2024"). If not specified, default to the last 30 days. 3. To download or view a specific invoice, the AI will need the invoice number or the associated order ID. 4. The AI should present the information clearly. For a list, provide a table with Invoice #, Date, Amount, Status, and a brief description. For a single invoice, summarize key details and offer to download the PDF. 5. Always confirm with the user before downloading files to their local system. ## Implementation Notes (for developers) - This skill interacts with the Bitrefill API endpoint `/api/v1/invoices`. - Authentication requires a valid Bitrefill API key with `read:invoices` scope. - The `download` function will save the PDF to a temporary location and provide the path to the AI/user.

关键部分解析：

• name和description：必须与目录名匹配，描述要简洁明了，说明技能用途和触发关键词（如“receipts”, “invoices”）。
• Capabilities：清晰列出技能能完成的具体任务。
• How the AI should use this skill：这是最重要的部分。用自然语言详细指导AI在什么场景下调用、需要询问用户哪些参数、如何处理结果、如何与用户交互。写得越详细，AI的表现就越可靠。
• Implementation Notes：这部分是给后续的开发者（或者技能运行时）看的，说明技能背后调用的具体技术接口（如API端点、认证方式）。这确保了技能描述与实际代码实现的一致性。

第三步：添加参考文档（可选但推荐）在skills/bitrefill-invoice/references/目录下，可以放置任何有助于AI理解该技能或有助于开发者实现的文档。例如：

• api-guide.md：Bitrefill发票API的详细说明。
• example-responses.json：API返回数据的样例。
• workflow-diagram.txt：用文字描述的操作流程图。 这些文档可以被AI在需要时检索（如果技能系统支持RAG），从而提供更准确的上下文。

第四步：注册技能到市场列表编辑.claude-plugin/marketplace.json文件，将新技能添加到skills数组中。你需要提供技能的路径和基本信息。

{ "skills": [ ... // 已有的技能 { "name": "bitrefill-invoice", "path": "skills/bitrefill-invoice/SKILL.md", "description": "Manage and download Bitrefill invoices." } ] }

完成以上步骤后，你的新技能就具备了被AI智能体发现和加载的基础结构。当然，要让技能真正“动起来”，你还需要在后台实现具体的功能代码（例如，一个调用Bitrefill API的Node.js脚本），这通常需要更深入的开发工作。

5.2 自定义技能开发的思路与挑战

为现有服务创建自定义技能，bitrefill/agents项目提供了一个优秀的范本。你可以将这套模式复制到任何其他拥有API或可自动化界面的服务上，例如：

• 云服务技能：让AI帮你查询AWS账单、创建DigitalOcean Droplet、管理Vercel项目。
• 通讯技能：让AI通过Twilio API发送短信、或检查SendGrid的邮件发送状态。
• 内部工具技能：连接公司内部的工单系统、部署平台或监控系统。

开发自定义技能的核心思路：

1. 定义边界：明确你的技能要做什么，不要贪多。一个技能最好聚焦于一个特定的、连贯的任务流（如“管理发票”）。
2. 设计交互：在SKILL.md的指令部分，像编写产品说明书一样，详细描述AI与用户对话的每一步。考虑所有可能的用户输入和边界情况。
3. 选择后端：决定是通过官方API（稳定、高效）还是模拟浏览器操作（无需API、功能全面但脆弱）来实现功能。
4. 处理认证：安全地管理API密钥或用户会话。最佳实践是让用户在AI智能体环境中配置一次，技能运行时从安全的环境变量或配置文件中读取，而不是在每次对话中传递。

可能遇到的挑战与应对：

• AI理解的偏差：即使指令写得再详细，大语言模型也可能产生误解。解决方法是进行大量的、多样化的测试，并根据测试结果反复优化SKILL.md中的指令描述，使其更加清晰、无歧义。
• 状态管理：一个复杂的技能可能需要多轮对话才能完成（例如，先搜索，再选择商品，最后确认支付）。你需要设计好技能如何维护对话上下文，或者将复杂流程拆分成多个更小、更独立的技能。
• 错误处理：网络超时、API返回错误、用户输入无效等情况必须被妥善处理。在技能指令中，应指导AI在遇到错误时如何向用户报告，并可能提供重试或替代方案的建议。
• 安全性：这是重中之重。技能绝不能暴露用户的敏感凭证。所有涉及密钥、令牌的操作都应在后台安全地处理。避免让AI在对话中明文输出敏感信息。

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

在实际使用和开发bitrefill/agents这类技能的过程中，你肯定会遇到各种各样的问题。下面我整理了一些典型场景和排查思路，很多都是我在早期摸索时踩过的坑。

6.1 技能安装与加载失败

问题现象：执行npx skills add ...命令后报错，或者在AI工具中无法看到或使用新技能。

6.2 技能被识别但调用无响应或出错

问题现象：AI能识别出技能（例如，回复说“我可以使用Bitrefill技能帮你”），但在具体执行时卡住、报错或返回空结果。