项目定位与覆盖范围

项目聚焦于 稳定币（USDC、USDT 及其他主流稳定币） 在以下两类场所的实时年化收益（APY）：

• DeFi 协议侧：覆盖 500+ 协议 资料来源：README.md
• CEX 侧：覆盖 20+ 中心化交易所的理财/借贷牌价 资料来源：README.md

它通过 免费、无需鉴权 的 API 提供数据，意图降低 Agent 在收益场景中的接入门槛 资料来源：README.md。

交付形态与 Skills 清单

仓库是 Anthropic plugin 形态的 Skills 包，根清单声明在 .claude-plugin/plugin.json 中，版本号与元数据在 package.json 中维护。仓库最新版本为 v2.0.1 资料来源：package.json。

本仓库提供 7 个 Skill，覆盖收益发现、对比、协议查询等典型场景。典型的 7 个 Skills 大致对应：

1. 协议/池子 APY 查询（DeFi 侧）
2. CEX 理财牌价查询（CEX 侧）
3. 跨协议收益对比
4. 按稳定币类型（USDC/USDT/...）聚合最高 APY
5. 协议元数据查询
6. 利率/份额等衍生字段计算
7. 综合"最优收益"建议

说明：上述清单数量与首版发布说明一致，但各 Skill 的具体命名请以 .claude-plugin/ 目录下实际声明为准 资料来源：.claude-plugin/plugin.json。

安装与构建

项目提供两类运行入口：

• CLI 入口：bin/cli.js，用于在终端里直接调用单个 Skill 资料来源：bin/cli.js
• MCP Server 入口：bin/mcp-server.mjs，把 Skills 暴露为 Model Context Protocol 工具，便于 Claude 等客户端按需调用 资料来源：bin/mcp-server.mjs

构建逻辑统一收敛在 build.sh 中，负责把 Skills 的 manifest 打包成可分发形态。标准步骤：

git clone https://github.com/YBSbarker/barker-stablecoin-skills.git
cd barker-stablecoin-skills
./build.sh           # 打包 Skills
node bin/cli.js      # 命令行验证
node bin/mcp-server.mjs   # 启动 MCP 服务给 Claude 连接

快速上手与重要字段语义

在 Claude（或其它 MCP 客户端）里接入 MCP Server 后，模型即可在对话中调用 7 个 Skill 来完成"找最优稳定币收益"的检索-对比-建议链路。

⚠️ 必须关注的版本差异

由于 v2.0.0 是 Breaking Change，升级时务必注意响应字段 资料来源：Releases · v2.0.0：

• 响应 payload 已精简到只保留模型真正用得到的核心字段
• 中间字段被剔除，目的是降低 token 消耗并稳定 LLM 调用
• v1.x 的下游集成需要适配

进一步地，v2.0.1 修正了 share_pct 的数值语义 资料来源：Releases · v2.0.1：

小结

barker-stablecoin-skills = 7 个稳定币收益 Skills + 500+ DeFi / 20+ CEX 数据源 + 免鉴权 API + MCP 友好。要快速跑通，关注三件事：在 .claude-plugin/plugin.json 看清单 资料来源：.claude-plugin/plugin.json、用 bin/mcp-server.mjs 起服务 资料来源：bin/mcp-server.mjs、按 v2.0.1 的字段语义（特别是 share_pct 是小数）读取响应 资料来源：Releases · v2.0.1。

概述与定位

barker-stablecoin-skills 是一个面向大语言模型（LLM）的稳定币收益情报插件套件，共提供 7 个独立 Skill，覆盖 500+ DeFi 协议与 20+ CEX 交易场所的实时 APY 数据，主要服务对象是 USDC、USDT 等主流稳定币的收益查询与策略分析场景 资料来源：README.md:1-40。

每个 Skill 在仓库中以独立目录组织，目录结构遵循统一规范：

skills/<skill-name>/
├── SKILL.md              # Skill 描述与提示词
├── SUMMARY.md            # 能力摘要
├── plugin.yaml           # 插件元数据
└── .claude-plugin/
    └── plugin.json       # Claude 插件注册信息

资料来源：skills/stablecoin-yield-radar/SKILL.md:1-15 与 skills/stablecoin-market-brief/SKILL.md:1-15。该结构便于按需加载单一 Skill，避免一次性注入全部提示词造成的上下文浪费。

七个 Skill 清单与职责

下表汇总了仓库 v1.0.0 首发起的全部 7 个 Skill 及其典型用途。Skill 名称依据目录约定推断，实际命名以仓库 skills/ 根目录为准 资料来源：README.md:18-28。

各 Skill 的 SKILL.md 定义了模型应当理解的任务边界与输出格式，SUMMARY.md 提供面向集成的简要说明，开发者只需查阅对应文件即可快速接入 资料来源：skills/stablecoin-yield-radar/SUMMARY.md:1-20。

关键数据约定与版本演进

响应字段精简（v2.0.0 破坏性变更）

v2.0.0 对 Skill 返回负载做了精简，仅保留 LLM 实际消费的字段，降低 token 消耗并提升调用稳定性。v1.x 集成的字段映射逻辑需要重新核对 资料来源：README.md:30-45。

`share_pct` 语义修正（v2.0.1）

v2.0.1 明确 share_pct 为小数分数而非百分数。例如 0.05 表示 5%，旧版若以 5.0 解释为 5% 的集成需调整数值映射 资料来源：README.md:46-58。此约定适用于所有返回资金分配、份额占比类指标的 Skill，集成方在解析时应统一乘以 100 后再展示。

数据规模与覆盖

整套套件无需鉴权即可调用后端 API，覆盖：

• 协议数：500+ DeFi 协议
• 场所数：20+ CEX 理财与借贷产品
• 资产范围：USDC、USDT 为主，扩展至其他主流稳定币

资料来源：README.md:12-26。

接入与工作流

每个 Skill 通过 plugin.yaml 注册声明式元数据，并由 .claude-plugin/plugin.json 暴露给 Claude 兼容运行时 资料来源：skills/stablecoin-yield-radar/plugin.yaml:1-10 与 skills/stablecoin-yield-radar/.claude-plugin/plugin.json:1-8。

典型调用流程如下：

1. 宿主应用按 Skill 名称加载对应 SKILL.md 提示词
2. LLM 根据提示词构造查询参数
3. Skill 后端调用统一 API 获取最新 APY 数据
4. 返回精简后的 JSON 负载，LLM 据此生成自然语言答复
5. 集成层在展示前注意将 share_pct 等小数字段转换为百分数

资料来源：skills/stablecoin-yield-radar/SKILL.md:20-35 与 skills/stablecoin-market-brief/SKILL.md:20-35。

由于 API 免费且无需鉴权，开发者可在原型阶段直接调用，生产环境建议增加调用频率控制与缓存层，以匹配后端速率限制。迁移到 v2.x 时，请优先审计所有 share_pct 字段的展示逻辑，避免因小数与百分数混用导致收益数据被高估或低估。

1. MCP 服务器与 x402 计费层

bin/mcp-server.mjs 是整个技能集合的入口进程，负责以 JSON-RPC 形式向 LLM 客户端注册能力 资料来源：bin/mcp-server.mjs:1-30。在传输层之上，付费技能通过 x402（HTTP 402 Payment Required）模式实现"先付费、后返回"的语义：客户端在收到 402 响应头中携带的支付凭证（chain id、asset、amount、nonce）后，再次发起带凭据的请求，服务器验证通过后再返回真实数据负载。

sequenceDiagram
    participant LLM as LLM 客户端
    participant MCP as MCP Server (bin/mcp-server.mjs)
    participant API as Upstream Yield API
    LLM->>MCP: tools/call (skill 参数)
    MCP-->>LLM: 402 + 支付参数
    LLM->>MCP: tools/call + 支付凭据
    MCP->>API: GET 聚合端点
    API-->>MCP: 标准化 JSON
    MCP-->>LLM: slim 后的稳定币收益结果

README.md 中声明该仓库"无需鉴权即可使用免费 API" 资料来源：README.md:1-40;付费通道（x402）属于在保留免费基础能力之上叠加的扩展能力，对应 MCP 服务器注册表中的若干高价值工具条目 资料来源：bin/mcp-server.mjs:30-80。

2. 响应负载的"瘦身"约定（v2.0.0 起）

在 v1.x 阶段，技能响应中包含大量中间派生字段，使得下游 LLM 上下文窗口被噪声填满。v2.0.0 发布为破坏性变更，强制收敛响应 schema：仅暴露 LLM 真正会消费的字段（如 apy、tvl、source、chain、asset、share_pct 等），其余原始聚合结构被剥离 资料来源：README.md:40-90。该约束在 llms.txt 的机器可读清单中同样被记录，工具描述只列举最终字段，避免 agent 误引用已删除的键 资料来源：llms.txt:1-60。

这一约定的目的是：

• 降低 token 成本与首包延迟
• 稳定 LLM function-calling 的 schema 校验
• 为后续 v2.x 补丁提供向后兼容基线

3. `share_pct` 语义修正（v2.0.1）

v2.0.1 是面向 v2.0.0 的修正补丁，专门修正 share_pct 字段的数值语义 资料来源：llms-full.txt:1-80。

任何把 share_pct 直接展示为百分比的集成方，必须调整为 value * 100 再做格式化 资料来源：README.md:90-140。

4. 调用方迁移清单

从 v1.x 升级到 v2.x 的集成方需要按以下顺序调整 资料来源：llms-full.txt:80-160：

1. 重新拉取技能清单，确认注册的 tool 名称与参数 shape 未变。
2. 丢弃响应中"曾经存在"的中间字段访问路径，避免在 slim 后变成 undefined。
3. 在数值映射层加上单位常量，强制 share_pct 走"小数 → 百分数"转换管线。
4. 若启用 x402 付费通道，缓存 402 响应中的支付参数 TTL，以避免重复支付。

5. 部署与文件约定

package.json 暴露 bin/mcp-server 入口脚本，便于通过 npx 或 PM2 直接拉起 MCP 服务器 资料来源：package.json:1-40;.gitignore 排除了本地缓存与支付凭据目录，确保密钥不会被提交到仓库 资料来源：.gitignore:1-20。

综上，x402 付费 MCP + slim 响应字段 + share_pct 小数语义共同构成了 v2.x 数据契约的三大支柱，集成方在升级时需要同步刷新客户端的字段映射与支付处理逻辑。

概述

Barker Stablecoin Skills 是一个面向 AI Agent 的稳定币收益情报工具集，提供 7 个 Skill，覆盖 500+ DeFi 协议与 20+ CEX 交易场所的实时 APY 数据。所有 Skill 都遵循 非托管（non-custodial） 设计原则：技能本身只负责数据检索与策略推荐，不持有用户私钥、不直接签署链上交易、不托管用户资金。真正需要广播交易时，由用户或用户控制的 Agent 调用 execute 类技能，结合外部支付协议完成结算。

资料来源：README.md:1-40

x402 是其中一种用于"按次付费 API + 链上结算"的执行路径示例，仓库在 examples/x402-execution-buyer.mjs 中给出了一个完整的买家侧参考实现，演示如何让 Agent 自主发现、定价、支付并执行一个 x402 风格的资源请求。

Pitfall Log / 踩坑日志

项目：YBSbarker/barker-stablecoin-skills

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 barker-stablecoin-skills 与安装入口 @barkermoney/skills 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 复现命令：npx @barkermoney/skills
• 证据：identity.distribution | https://github.com/YBSbarker/barker-stablecoin-skills | repo=barker-stablecoin-skills; install=@barkermoney/skills

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/YBSbarker/barker-stablecoin-skills | host_targets=claude_code, claude, mcp_host, cursor

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/YBSbarker/barker-stablecoin-skills | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/YBSbarker/barker-stablecoin-skills | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/YBSbarker/barker-stablecoin-skills | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/YBSbarker/barker-stablecoin-skills | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/YBSbarker/barker-stablecoin-skills | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/YBSbarker/barker-stablecoin-skills | release_recency=unknown