stigg

Stigg — 总览技能

Stigg 是一个定价、套餐设计和权益管理平台。此技能是处理任何 Stigg 相关工作的第一站。它会强制执行先搜索规则，并引导你使用合适的子技能。

步骤 0 — 你需要一个 Stigg 账户

其他所有步骤都假设你已经拥有：

1. 一个 app.stigg.io 账户（如果没有，请注册）。
2. 该账户中至少有一个环境（dev / staging / prod — Stigg 会自动创建一个默认沙盒；生产环境仅适用于 Scale 计划）。
3. 一个 API 密钥，在你准备操作的环境中，通过 Integrations → API keys 获取。

如果缺少这三项，子技能中的每个“设置 Stigg”步骤都会因 401 Unauthenticated 而失败。如果用户尚未完成这些操作，请在集成开始时告知他们。

如果项目使用 Stripe Projects，请完全跳过浏览器操作 — stripe projects add stigg/environment 会创建账户和环境，并将密钥写入 .env。加载 stigg-sp。

先搜索规则（不可妥协）

在生成任何 Stigg 集成代码之前，都要搜索实时文档。 Stigg 更新迅速；内置代码片段很快就会过时。即使你“记得它的工作方式”，也必须遵守此规则。

For every Stigg task → search docs → then (if connected) call the Stigg MCP → only then write code.

搜索方式，按优先级排列：

1. Stigg MCP 服务（mcp.stigg.io）— 如果用户已连接，Agent 可以调用 search_docs，并且对真实环境执行操作。参见 stigg-mcp。
2. Mintlify Stigg 文档 MCP — 如果 Agent 可以使用官方文档 MCP（search_stigg、query_docs_filesystem_stigg），请使用它。
3. https://docs.stigg.io/llms.txt — 面向大模型的 URL 索引。获取该索引，找到相关页面，再获取该页面。
4. 直接获取 docs.stigg.io/<path> — 最后的选择。

完整的原因说明和示例：references/search-first.md。

危险信号 — 停下并搜索： 你即将编写 import Stigg from '@stigg/...'、调用 curl https://api.stigg.io/...，或编写任何 GraphQL mutation，但在本轮中尚未打开过文档页面。

选择合适的集成方式

Stigg 提供多种集成方式。请谨慎选择。默认使用 MCP，除非用户明确要求使用 CLI — 完整说明见 stigg-mcp/references/cli-vs-mcp.md。

目标	使用方式
开发期间建模定价、探索和一次性操作（默认）	Stigg MCP 服务（stigg-mcp）
生产环境热路径：权限控制、用量报告、面向客户的页面	后端或前端 SDK（stigg-api → SDK 矩阵）
直接调用 REST（所用语言没有 SDK，或需要轻量级服务端代理）	https://api.stigg.io/api/v1 上的 REST API（stigg-api）
GraphQL（遗留场景或特定高级查询）	https://api.stigg.io/graphql 上的 GraphQL API（stigg-api）
脚本、CI/CD、终端管理 — 仅在用户明确要求使用 CLI 时	Stigg CLI（Go 二进制文件，brew install stiggio/tools/stigg；代码仓库：https://github.com/stiggio/stigg-cli）
即插即用的 UI（付费墙、客户门户、结账）	Widgets — 参见 widgets.stigg.io Storybook

包含边缘情况的决策流程图：references/decision-tree.md。CLI 与 MCP 的详细对比：stigg-mcp/references/cli-vs-mcp.md。

路由 — 你需要哪个子技能

子技能会自动调用。 当用户的请求符合子技能的触发条件（见下表和各子技能的 frontmatter 描述）时，立即通过 Skill 工具调用该子技能。将其与这个总技能一起加载。不要要求用户运行 /stigg-<name>。不要“根据提及内容路由”。用户用普通英文描述目标；此技能会选择正确的支柱并加载它。

任务	技能
首次设置 MCP，将 Claude Code/Cursor 等连接到 Stigg	stigg-mcp
选择 SDK、REST 还是 GraphQL，API 密钥类型、速率限制、身份验证	stigg-api
在目录中建模功能、计划、附加项、产品、额度	stigg-pricing-modeling
控制功能访问、报告用量、回退策略	stigg-entitlements
开通、更新、取消、迁移订阅，试用	stigg-subscriptions
额度发放、消耗、自动充值、席位池	stigg-credits
按实体设置预算——实体层级、用量限制分配、治理树	stigg-governance
付费墙、客户门户、结账、额度组件	stigg-widgets
接收来自 Stigg 的 webhook 事件——签名验证、负载、重试、处理程序框架	stigg-webhooks
选择合适的定价／变现模式	stigg-pricing-expert
多步骤方案（免费增值、混合模式、AI 额度、试用）	stigg-recipes
通过 Stripe Projects 开通 Stigg 环境（stripe projects add stigg/environment）	stigg-sp

子技能（stigg-mcp、stigg-governance 等）是 stigg/ 的同级目录，而非其子目录——skills/stigg/ 和 skills/stigg-governance/ 并列。按名称调用它们；不要在 stigg/ 中查找。

如果存在适用于该任务的子技能，请通过 Skill 工具调用它——不要根据此仓库之外的信息临场编造内容，也不要停下来等用户输入斜杠命令。

60 秒了解 Stigg

开始构建前需掌握的最少术语。完整词汇表：references/core-concepts.md。

• 客户持有某个产品下的计划订阅。订阅可以包含附加项。
• 功能（布尔值／配置／计量型）定义了哪些内容可以受控。权益 = 功能 + 配置值（例如 Pro 计划每月“10k 次 API 调用”）。
• 促销权益是在订阅之外按客户设置的覆盖项。额度池／授予／账本用于基于额度的定价——每种额度货币对应一个额度池。参见 stigg-credits。
• 治理会在功能和额度之上添加按实体设置的预算（部门／团队／Agent）——由账户控制，参见 stigg-governance。
• 环境（沙盒／预发布／生产）是相互隔离的工作区；每个环境都有自己的 API 密钥。

何时不加载此技能

• 任务与 Stigg 无关（定价／计费／权益）。

常见错误

错误	修正方法
不先搜索文档就凭记忆生成 REST／SDK 代码	先搜索——API 接口会不断演进。参见 references/search-first.md。
混淆 CLI 和 MCP 服务（它们是不同的工具）	CLI = 确定性的 Shell；MCP = 由 Agent 驱动。参见上表。
混用 events.report 和 usage.report	它们使用不同的扩展模型，并非面向不同的受众。详见 stigg-entitlements。
开发时调用生产环境	始终从沙盒开始。API 密钥与环境绑定。
在客户端代码中嵌入完整访问权限（服务端）密钥	绝不可这样做。前端 SDK 应使用可发布（客户端）密钥。参见 stigg-api。