1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | clerk-billing（所属合集仓库自述名称为 “Clerk Skills”，故单列记录） | GitHub |
| 作者/维护者 | Clerk（身份认证 SaaS 平台，官方组织仓库） | GitHub API |
| 来源链接 | https://github.com/clerk/skills/tree/main/skills/features/clerk-billing | — |
| 许可证 | MIT（SKILL.md frontmatter 明确声明，仓库根目录未附独立 LICENSE 文件） | GitHub API + 仓库核对 |
| GitHub Stars / Forks | 所属仓库 64★ / 4 forks（该数字属整个 20 个技能的合集，不代表本技能个体热度，仅供了解仓库规模） | GitHub API |
| 子技能自身证据 | 近期由 2 位工程师通过 23 次提交迭代打磨，另有围绕计费能力的多次功能性 PR（如新增 Agent 优先的编程式配置） | GitHub API（按路径查询提交历史） |
| 最新版本 | 1.0.0（SKILL.md metadata 声明） | SKILL.md |
| 安装方式 | npx skills add clerk/skills --skill clerk-billing、Codex 插件市场，或手动 git clone（见第 10 章） |
官方 README |
项目自述名称：合集仓库标题为「Clerk Skills」，本文聚焦其中的
clerk-billing子技能。
2. 功能介绍与亮点
clerk-billing 教会编码 agent 在 Clerk 认证的基础上，为应用加上订阅计费与功能门控能力，无需 agent 直接对接 Stripe 原始 API。
主要亮点：
- 一行组件完成定价页与结账：
<PricingTable />自动渲染 Dashboard 中配置的全部套餐，选择后接管 Clerk 自带的应用内结账抽屉，无需自建支付表单 - 两级门控粒度：
has({ feature })用于单项能力开关（如导出、SSO），has({ plan })用于整档套餐门槛，SKILL.md 用对照表明确区分“该用哪一个”，避免 agent 误用 - B2B 按坐位计费：组织级套餐可设坐位上限，邀请成员时由 Clerk 强制封顶，
<PricingTable for="organization" />单独渲染企业侧定价 - Agent 优先的编程式配置：
clerk config pull/patch可把套餐、功能开关整体导出为可版本控制的 JSON 文件再回写，跳过手点 Dashboard 的重复劳动 - Clerk/Stripe 事件名映射表：webhook 一节把 Clerk 计费事件命名（如
subscriptionItem.canceled）与开发者更熟悉的 Stripe 命名逐条对照，避免 agent 按 Stripe 经验直接抄错事件名 - 报错速查表：把“
<PricingTable />渲染空白““has({ plan })结账后仍返回 false”等真实高频报错整理成根因-修复对照表，减少排障来回
3. 适用场景
固定分类：集成与工作流自动化
面向已经使用 Clerk 做身份认证、需要为 SaaS 产品加订阅付费墙、功能分级或 B2B 按坐位计费的开发者——尤其是“给现有 Clerk 项目接入定价页”“区分免费版与付费版功能”“处理订阅生命周期 webhook”这类场景，agent 用该 skill 可以直接产出符合 Clerk 官方约定的组件与门控代码，而不必现学 Clerk 与 Stripe 两套计费概念的映射关系。
4. 跨 Agent 兼容性
- Claude Code：原生支持，可用
npx skills add clerk/skills --skill clerk-billing，或手动git clone到~/.claude/skills/clerk - Codex：原生支持，
codex plugin marketplace add clerk/skills后在/plugins安装启用 Clerk Skills 插件（含本技能） - OpenClaw / Hermes Agent：未验证——官方材料点名支持 Claude Code、Cursor、Windsurf、GitHub Copilot、Codex、Gemini CLI，未提及这两个平台，遵循开放的 Agent Skills 规范理论上可手动安装，但缺乏官方确认
5. 推荐理由
订阅计费是 SaaS 项目里出错率很高的一块——套餐建在哪个 Tab、事件名到底叫什么、has() 该查 feature 还是 plan，稍不注意就会踩坑。这个技能把 Clerk 官方在计费这条产品线上踩过的坑（Stripe/Clerk 事件名不一致、结账后未刷新 session 导致 has() 仍返回旧值等）直接整理成对照表交给 agent，同时把 B2C、B2B 按坐位两种主流计费模式的组件与门控写法都覆盖到，能让 agent 一次产出贴近 Clerk 官方约定的计费代码，减少后续人工返工。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Clerk 官方为整个 Skills 系列发布过独立 changelog 公告与专门文档页，第三方 Skill 目录站亦有收录条目；但该子技能自身提交历史集中于 2 位工程师，尚未发现独立于官方渠道的具名用户评价或活跃 issue 讨论 |
| 可用性 | 8 | 安装一条命令即可完成；SKILL.md 附带 4 篇细分参考文档与错误速查表，文档质量高；但实际启用需要在 Dashboard 开通计费、创建套餐，生产环境还需绑定 Stripe 账号，并非零配置 |
| 安全性 | 9 | 见下方安全检查清单 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令与权限范围 | allowed-tools 仅声明 WebFetch，不含 Bash，agent 无法在未经额外授权的情况下直接执行计费写操作 |
| ② 运行时联网外发 | 仅通过 WebFetch 拉取 clerk.com 官方文档与 Dashboard 链接，目标透明；若选择 npx skills add 安装路径，其依赖的第三方安装器另有未解决的遥测上传投诉（详见第 11 章） |
| ③ API Key/凭据存储 | 文档要求的 CLERK_SECRET_KEY、CLERK_WEBHOOK_SIGNING_SECRET 均为用户自身项目的环境变量，技能本身不落地、不转存任何凭据 |
| ④ 可疑指令 | 全文通读未发现提示注入或隐藏指令，内容均为计费组件用法与官方文档链接 |
| ⑤ 作者/组织信誉 | Clerk 为知名身份认证 SaaS 厂商，官方组织账号，无造假迹象 |
| ⑥ License | MIT，SKILL.md frontmatter 明确声明 |
| ⑦ 最近维护 | 所属仓库最近一次推送为 2026-07-30；该子技能自身的功能提交集中在 2026 年 4-5 月完成一轮集中开发 |
综合评分 = 三项均值 = 8.0
7. 跟同类 Skills 相比的优势
订阅计费/支付集成领域，可比的官方出品 agent 技能包括：
| Skill | 定位 | 与 clerk-billing 的差异 |
|---|---|---|
stripe-best-practices（stripe/ai） |
Stripe 官方出品，教 agent 直接调用 Stripe 原生 API（Checkout Sessions、Billing APIs、Setup Intents 等）做技术选型 | 抽象层级不同：Stripe 技能面向“直接用 Stripe API”的开发者，clerk-billing 面向“已用 Clerk 认证、想用 Clerk 组件包一层”的开发者，生产环境的支付处理最终仍会落到 Stripe，但代码里几乎不出现 Stripe 概念 |
paddle-agent-skills（PaddleHQ） |
Paddle 官方出品，共 10 个技能覆盖订阅管理、结账、客户门户、定价展示与 webhook | Paddle 是记录商家（Merchant of Record，代缴税务合规），定位是 Stripe/Clerk 之外的另一条计费路线；与 clerk-billing 不共享认证层，选型时通常是“用 Clerk 认证 + Clerk billing”还是“整体换成 Paddle”的路线之争而非直接叠加 |
| lemonsqueezy-claude-skills（社区维护） | 面向 Lemon Squeezy 平台的客服、销售分析、折扣码、退款等运营型技能集合 | 非官方出品，且聚焦运营后台操作而非“如何把定价页/门控写进代码”，与 clerk-billing 的开发期定位不同 |
8. 用户评价
该技能所属的 Clerk Skills 合集已被多个第三方 AI Skill 目录站收录展示，但均为目录聚合列表，尚无独立于官方渠道的具名用户评价可供引用。
9. 其他补充
clerk-billing 是 Clerk Skills 合集 20 个技能之一，同属“功能”分组的还有 clerk-orgs（B2B 组织与 RBAC，计费按坐位收费的前提）、clerk-webhooks（webhook 签名校验与路由，计费生命周期事件的通用处理层）与 clerk-testing（E2E 测试），需要配套能力时可在同一仓库内按需取用。
10. 安装使用方式
方式一（推荐，Claude Code 通用安装器）：
npx skills add clerk/skills --skill clerk-billing方式二（Claude Code 手动安装，不依赖第三方安装脚本）：
git clone https://github.com/clerk/skills ~/.claude/skills/clerk方式三（Codex）：
codex plugin marketplace add clerk/skills添加市场后重启 Codex，打开 /plugins，选择 Clerk Skills 安装并启用，再开始新会话。
安装后注意事项：
- 使用前需在 Clerk Dashboard → Billing → Settings 开通 Billing，并配置
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY、CLERK_SECRET_KEY - 需先在 Dashboard 对应 Tab（User Plans / Organization Plans）创建套餐，套餐建错 Tab 是
<PricingTable />渲染空白的最常见原因 - 生产环境需绑定 Stripe 账号处理实际扣款，开发环境可用 Clerk 共享的开发网关免 Stripe 账号试用
11. 注意事项
- 计费 API 仍为实验阶段：SKILL.md 明确提示需锁定
@clerk/nextjs与clerk-js的包版本，避免实验性 API 变动导致代码失效 - 第三方安装器的已知问题：若选择
npx skills add这条安装路径，其底层依赖的通用安装 CLI（vercel-labs/skills）当前存在两个未解决的社区投诉——安装时可能在未明确告知的情况下上传使用遥测数据。选择本报告方式二（手动git clone）或方式三（Codex 插件市场）可完全绕开这一层 - 跨 Agent 支持范围有限：官方仅确认 Claude Code、Cursor、Windsurf、GitHub Copilot、Codex、Gemini CLI，OpenClaw、Hermes Agent 用户需自行验证兼容性
- 生产环境非零成本：套餐与门控逻辑本身免费，但生产环境的实际扣款依赖已连接的 Stripe 账号，属计费产品本身的前提条件，非本技能强加的限制