schematize
Skills · Claude Code · Agent Skills

先有契约，再写 handler，没有商量余地。

规范是唯一来源，代码服从规范：声明式安全、标准化错误、幂等写入、签名 Webhook，破坏性变更必须有 ADR 和日期。

v0.2.1Disciplina · Contrato de APIgithub.com/schematizeme/skill-api

维护者 Lucas Andrade

schematize-api · v0.2.1bash
$ schematize install api
GitHub →下载技能 (.zip)/api-help · github.com/schematizeme/schematize-cli

不可妥协的底线

不会为了"更快"而关闭。完整清单见该 skill。

契约优先

规范（OpenAPI 3.1+ 或 .proto）是唯一来源；handler 和客户端由其生成或据其校验，漂移会阻断 CI。

每个操作都声明安全方式

必须有 securitySchemes 且覆盖每个操作；有意公开须显式写 security: []；令牌绝不放在查询字符串里。

错误使用 problem+json（RFC 9457）

每个 4xx/5xx 响应都带稳定的 type；不得用 200 返回错误体，detail 中不得出现堆栈或 SQL。

有副作用的 POST 必须带 Idempotency-Key

按主体限定作用域，重复请求回放同一响应，误用时返回 422/409。

集合使用不透明游标分页

稳定的全序和有上限的 limit；只有写明理由才能用 offset。

签名 Webhook 与重放窗口

每个端点独立 HMAC、id 与时间戳、带退避和抖动的重试、DLQ、防 SSRF；投递是 at-least-once，绝不承诺 exactly-once。

破坏性变更须有 ADR 和日期

兼容性 diff（oasdiff、buf breaking）在 PR 中运行；弃用意味着 Deprecation + Sunset + 迁移链接，到期返回 410。

每个字段有上限，金额用整数

所有输入都设 maxLength、maximum、maxItems；金额用最小单位整数加币种，绝不用 float。

命令

安装在 .claude/commands/。随时运行 /api-help。

/api-breaking对契约变更进行分类，运行兼容性 diff，并制定带日期的弃用计划。
/api-ccContext compact：把 handoff 写入 archive 并运行 /compact。
/api-claude在仓库根目录创建或合并常驻的 API 契约基线 CLAUDE.md（不会覆盖其他 skill 的区块）。
/api-design在写任何 handler 之前，以契约优先的方式设计新的资源或操作。
/api-handoff在不压缩的前提下，把上下文 handoff（context.md + checklist.md）写入 archive。
/api-help列出所有命令及其作用。
/api-load强制加载API 契约的全部规范内容，并在本次会话中应用。
/api-review对照基线审查 OpenAPI/.proto 规范：运行门禁，再人工阅读机器读不到的部分。
/api-webhook设计或审查发出或接收的 Webhook：签名、重放、重试、去重与 SSRF。

面向 AI 智能体

无需人工介入即可安装。元数据见 llms.txt。

  • 运行：git clone https://github.com/schematizeme/skill-api.git && ./skill-api/install.sh
  • 或下载：https://github.com/schematizeme/skill-api/releases/latest/download/skill-api.zip 并解压到 .claude/skills/
  • 将 assets/CLAUDE.md 复制到仓库根目录（常驻规则）。
  • 用 /api-help 确认。

不想安装？

阅读完整规范并直接复制到你的项目——或安装该技能，让智能体自动执行。

GitHub →技能包