Agent skill

API Contract Architecture

by devcodex-labs in devcodex-labs/devcodex

API 契约架构专家 Owner — 当任务涉及 public API、HTTP/SDK/CLI 契约、版本兼容、错误模型、分页过滤、幂等、Schema、类型、迁移或消费者影响时使用;要求先冻结消费者契约,再设计实现与验证。

AGPL-3.0Auto-check passedBackend & APIs

Install API Contract Architecture

skills CLI
$ npx skills add devcodex-labs/devcodex --skill api-contract-architecture -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install devcodex-labs/devcodex api-contract-architecture --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/devcodex-labs/devcodex.git skills-src && mkdir -p .claude/skills && cp -r skills-src/content/skills/api-contract-architecture .claude/skills/api-contract-architecture && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
api-contract-architecture
GitHub stars
439
Token cost
~865 tokens
SKILL.md length
182 words
Files
2
Skills in repo
70
Repo updated
First seen
Licence
AGPL-3.0

At a glance

API 契约架构专家 Owner — 当任务涉及 public API、HTTP/SDK/CLI 契约、版本兼容、错误模型、分页过滤、幂等、Schema、类型、迁移或消费者影响时使用;要求先冻结消费者契约,再设计实现与验证。

  • Works in 7 steps: 列出所有消费者:前端、SDK、CLI、Hook、文档示例、测试、外部系统。 → 冻结现状契约:字段、类型、错误、版本、默认值、边界条件。 → 执行… → …
  • Tasks that involve API design
  • SKILL.md covers 定位, 触发条件, 核心门禁 and 执行步骤, plus 3 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

API Contract Architecture is an agent skill from devcodex-labs/devcodex. API 契约架构专家 Owner — 当任务涉及 public API、HTTP/SDK/CLI 契约、版本兼容、错误模型、分页过滤、幂等、Schema、类型、迁移或消费者影响时使用;要求先冻结消费者契约,再设计实现与验证。

Its SKILL.md is about 870 tokens, which your agent loads only when the skill is triggered. The skill folder holds 1 other file (for example `intent.json`).

It sits in Backend & APIs, covering API design. The repository describes itself as: Intent-driven AI coding workflow runtime for consistent context, skills, approvals, validation, and handoffs across six AI coding hosts. The licence is AGPL-3.0.

When your agent uses it

  • Tasks that involve API design

Example prompts

  • “/api-contract-architecture”

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

  1. 列出所有消费者:前端、SDK、CLI、Hook、文档示例、测试、外部系统。
  2. 冻结现状契约:字段、类型、错误、版本、默认值、边界条件。
  3. 执行 ReleaseAuthorityBeforeCompatibilityGate:核对 tag/registry/release note/public docs/实际消费者;已发布才进入兼容评估,未发布且无稳定消费者默认直接收敛,未发布但存在产品取舍则交用户决策,事实不明…
  4. 定义目标契约与兼容策略:新增、保留、弃用、迁移、拒绝。
  5. 为错误模型、分页过滤、幂等和重试写稳定语义;CLI JSON 合同还要冻结 success/failure 字段互斥和 exit=0/1/2 映射。
  6. 若合同存在 discriminator 或条件完成态,执行 cross-variant 字段注入与完成证据删除/反转 mutation;Schema、semantic validator、docs field set 与 runtime 必须给出同一结论。
  7. 把契约映射到文档、示例、.http / .cjs、types、runtime probe。

What it can do on your machine

Read from SKILL.md and the folder at commit 1dd4525. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

API Contract Architecture loads about 865 tokens when it runs. Until then it costs about 35 tokens; SKILL.md has 182 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~35
When it runs · the whole SKILL.md, loaded when a task matches
~865

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from devcodex-labs/devcodex at commit 1dd4525, republished under its AGPL-3.0 licence (© devcodex-labs). 182 words, ~865 tokens.

Download SKILL.mdSave it as .claude/skills/api-contract-architecture/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
api-contract-architecture
description
API 契约架构专家 Owner — 当任务涉及 public API、HTTP/SDK/CLI 契约、版本兼容、错误模型、分页过滤、幂等、Schema、类型、迁移或消费者影响时使用;要求先冻结消费者契约,再设计实现与验证。

API Contract Architecture Skill

定位

本 Skill 负责 API 契约 Owner 视角。它确保方案先回答“谁消费、契约是什么、如何兼容、如何验证”,再进入实现细节。

触发条件

场景是否触发
新增或调整 HTTP API、SDK API、CLI 参数、Hook payload、MCP tool/resource、事件、配置 Schema 或 public types必须
涉及版本兼容、迁移、错误码、分页、过滤、幂等、鉴权响应或消费者文档必须
修复会影响调用方行为或示例用法必须
纯内部实现且不改变任何公开输入/输出/错误/类型N/A + skipReason

核心门禁

Gate要求证据
ApiContractArchitectureGate公开契约必须有消费者、输入、输出、错误、兼容和验证矩阵consumerSurface、contractInventory
ConsumerSurfaceGate先列真实消费者,避免首个实现反向定义公共契约README、types、examples、route、SDK
ErrorModelGate错误结构、错误码、detail 和恢复路径必须稳定errorModel、docs
CliJsonContractGate机器可读 CLI 必须冻结 envelope 字段、成功/失败互斥、错误码、nextStep 与 native exit codeDevCodexCliEnvelopeV1、spawn fixtures
VersionCompatibilityGate兼容、弃用、迁移和 breaking change 必须明确versionCompatibility
ReleaseAuthorityBeforeCompatibilityGate先证明契约是否已发布并形成稳定消费者,再决定兼容、迁移或直接收敛publishedState、consumerEvidence、authoritySources、decision
ConfigurationErgonomicsGate公开配置 Schema 必须证明最小任务、字段必要性、复杂度预算和可选字段省略行为MinimalTaskConfig、FieldNecessityMatrix、OptionalFieldOmissionProbe
ContractVariantIsolationMutationGatediscriminated union/tool/event/state 合同必须拒绝 sibling variant 字段,并验证完成态必需证据不能被删除或反转ContractVariantIsolationMatrix、CompletionEvidenceDeletionMatrix
IdempotencyPaginationGate写操作、分页、过滤、排序和重试场景必须定义语义idempotencyPagination

执行步骤

  1. 列出所有消费者:前端、SDK、CLI、Hook、文档示例、测试、外部系统。
  2. 冻结现状契约:字段、类型、错误、版本、默认值、边界条件。
  3. 执行 ReleaseAuthorityBeforeCompatibilityGate:核对 tag/registry/release note/public docs/实际消费者;已发布才进入兼容评估,未发布且无稳定消费者默认直接收敛,未发布但存在产品取舍则交用户决策,事实不明时不得编造兼容义务。
  4. 定义目标契约与兼容策略:新增、保留、弃用、迁移、拒绝。
  5. 为错误模型、分页过滤、幂等和重试写稳定语义;CLI JSON 合同还要冻结 success/failure 字段互斥和 exit=0/1/2 映射。
  6. 若合同存在 discriminator 或条件完成态,执行 cross-variant 字段注入与完成证据删除/反转 mutation;Schema、semantic validator、docs field set 与 runtime 必须给出同一结论。
  7. 把契约映射到文档、示例、.http / .cjs、types、runtime probe。

输出字段

markdown
## ApiContractArchitectureGate

| 字段 | 内容 |
|------|------|
| consumerSurface | 消费者列表和调用入口 |
| contractInventory | 当前/目标输入、输出、错误、类型、配置 |
| versionCompatibility | 兼容、弃用、迁移、breaking change |
| releaseAuthority | publishedState、consumerEvidence、authoritySources 与兼容决策 |
| errorModel | 错误码、detail、恢复路径 |
| cliJsonContract | envelope、字段互斥、错误码、nextStep、exit map 与默认人读兼容 |
| idempotencyPagination | 幂等、分页、过滤、排序、重试语义 |
| sdkDocsImpact | SDK、README、examples、public types、文档影响 |
| evidenceMatrix | 判断 -> 代码 / 类型 / 文档 / 测试 / 运行时证据 |
| contractMutationMatrix | variant isolation、completion evidence deletion/reversal、schema/semantic/docs/runtime 结论 |

反模式

反模式修正
先写实现,再让消费者适配输出先冻结 contractInventory 和 consumerSurface
只写 happy path,没有错误模型补 errorModel 和失败恢复
首个 provider 字段反向定义公共 API区分业务契约与 provider payload
用单个示例证明兼容抽样 public types、README、tests 和 runtime
未发布候选也默认背负历史兼容层先做 ReleaseAuthorityBeforeCompatibilityGate;无稳定消费者时直接收敛 canonical contract
JSON 错误只写 message 或以 exit 0 返回冻结稳定 errorCode/nextStep,并用原生退出码区分合同错误与检查失败

与其他 Skill 的关系

  • developer-experience-architecture:API 示例、错误信息和迁移路径共同影响 DX。
  • backend-domain-architecture:领域不变量和权限策略必须映射到 API 契约。
  • test-router:API 变更触发 .http / .cjs、types、runtime 或 docs sync 验证。

© devcodex-labs, AGPL-3.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in content/skills/api-contract-architecture of devcodex-labs/devcodex.

  • SKILL.md
  • intent.json

Open the folder on GitHubat commit 1dd4525

Compare with similar skills

API Contract Architecture next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

API Contract Architecture compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
API Contract Architecture this skilldevcodex-labs/devcodex439—~865Automated safety check: PassAGPL-3.0
API DesignerJeffallan/claude-skills12k2 repos~2kAutomated safety check: PassMIT
Nodejs Backend Patternsever-works/ever-works15817 repos~4kAutomated safety check: PassAGPL-3.0
Pangolin CRUD Endpointsfosrl/pangolin23k—~461Automated safety check: PassCustom licence
Backend PatternshellangleZ/burn-in-cceverywhere-ralph11217 repos~3.3kAutomated safety check: PassNone
API And Interface Designdzhalaevd/Donatello1359 repos~2.6kAutomated safety check: PassApache-2.0

Similar skills

  • API Designer

    Jeffallan/claude-skills

    Designs REST and GraphQL APIs from resource modeling to an OpenAPI 3.1 contract, with versioning, pagination and RFC 7807 error handling.

    12k GitHub starsUsed in 2 repos~2k tokens
    Backend & APIsAuto-check passed
  • Nodejs Backend Patterns

    ever-works/ever-works

    Build production-ready Node.js backend services with Express/Fastify, implementing middleware patterns, error handling, authentication, database integration, and API design best practices.

    158 GitHub starsUsed in 17 repos~4k tokens
    Backend & APIsAuto-check passed
  • Use whenever asked to add, create, or scaffold a CRUD endpoint, router, or entity in this repo's server (create/list/get/update/delete handlers, new…

    23k GitHub stars~461 tokensUpdated today
    Backend & APIsAuto-check passed
  • Backend Patterns

    hellangleZ/burn-in-cceverywhere-ralph

    Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.

    112 GitHub starsUsed in 17 repos~3.3k tokens
    Backend & APIsAuto-check passed
  • API And Interface Design

    dzhalaevd/Donatello

    Guides stable API and interface design. An agent skill from dzhalaevd/Donatello.

    135 GitHub starsUsed in 9 repos~2.6k tokens
    Backend & APIsAuto-check passed
  • API Design Principles

    jh941213/my-cc-harness

    REST 및 GraphQL API 설계 원칙 가이드. An agent skill from jh941213/my-cc-harness.

    126 GitHub starsUsed in 19 repos~3.4k tokens
    Backend & APIsAuto-check passed

More from devcodex-labs/devcodex

All 70 skills in this repo
  • Accessibility I18n

    devcodex-labs/devcodex

    无障碍与国际化专家 Owner — 当任务涉及可访问性、键盘操作、焦点、屏幕阅读器、ARIA、语言地区、本地化、RTL、翻译资源、用户可见文案或多语言文档时使用;要求把包容性体验和本地化验证绑定到真实用户路径。

    439 GitHub stars~718 tokensUpdated 20 days ago
    Auto-check passed
  • AI Agent System Architecture

    devcodex-labs/devcodex

    AI Agent 系统架构专家 Owner — 当任务涉及 Agent 路由、工具调用、上下文管理、记忆、状态机、权限、人机协作、可观测性、回放验证或模型辅助治理时使用;要求把 Agent 行为设计成可解释、可恢复、可审计。

    439 GitHub stars~2.4k tokensUpdated 20 days ago
    Auto-check passed
  • Architecture Design

    devcodex-labs/devcodex

    架构设计文档编排 Owner — 当用户要求架构设计、系统设计、技术架构或可指导开发、Review 与任务拆分的完整方案时使用;要求从业务流程反推节点、状态、数据、一致性、异常补偿、ADR 与实施任务。

    439 GitHub stars~1.1k tokensUpdated 20 days ago
    Auto-check passed
  • Audit Common

    devcodex-labs/devcodex

    审查公共维度 G0~G5 + Profile Freshness Check — 所有 audit 子类型必先执行的基础维度层

    439 GitHub stars~4.1k tokensUpdated 20 days ago
    Auto-check passed
  • Audit Session

    devcodex-labs/devcodex

    审计工作流的跨会话状态机 — 在 <audit-root/.audit-state/<session-id.json 持久化轮次/发现项/收敛状态,支持 Token 中断后精准恢复

    439 GitHub stars~1.8k tokensUpdated 20 days ago
    Auto-check passed
  • Backend Domain Architecture

    devcodex-labs/devcodex

    后端领域架构专家 Owner — 当任务涉及领域模型、业务流程、权限、API、事务、一致性、幂等、兼容、数据边界、服务职责或用户要求从后端/领域专家角度审查时使用;要求用领域语言和业务不变量约束实现。

    439 GitHub stars~575 tokensUpdated 20 days ago
    Auto-check passed

Categories

Questions about API Contract Architecture

What does API Contract Architecture do?

API 契约架构专家 Owner — 当任务涉及 public API、HTTP/SDK/CLI 契约、版本兼容、错误模型、分页过滤、幂等、Schema、类型、迁移或消费者影响时使用;要求先冻结消费者契约,再设计实现与验证。. API Contract Architecture is an agent skill from devcodex-labs/devcodex.

When should I use API Contract Architecture?

API Contract Architecture fits situations like: tasks that involve API design.

How do I install API Contract Architecture in Claude Code?

Run `npx skills add devcodex-labs/devcodex --skill api-contract-architecture -a claude-code`. Or copy the skill folder (content/skills/api-contract-architecture in devcodex-labs/devcodex) into .claude/skills/api-contract-architecture in your project. Claude Code loads it when a task matches its description.

How do I install API Contract Architecture in Codex?

Run `npx skills add devcodex-labs/devcodex --skill api-contract-architecture -a codex`. Or copy the skill folder (content/skills/api-contract-architecture in devcodex-labs/devcodex) into .agents/skills/api-contract-architecture in your project. Codex loads it when a task matches its description.

Can I use API Contract Architecture in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add devcodex-labs/devcodex --skill api-contract-architecture -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/api-contract-architecture, .gemini/skills/api-contract-architecture, .github/skills/api-contract-architecture and .opencode/skills/api-contract-architecture in your project.

What does API Contract Architecture need to run?

SKILL.md names no scripts, command-line tools or credentials: API Contract Architecture is instructions for the agent only.

Does API Contract Architecture access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is API Contract Architecture safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does API Contract Architecture use?

API Contract Architecture is published under the AGPL-3.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does API Contract Architecture use?

About 865 tokens (SKILL.md is roughly 3.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to API Contract Architecture?

Skills that share tags, products or a category with API Contract Architecture: API Designer (Jeffallan/claude-skills, 12k stars), Nodejs Backend Patterns (ever-works/ever-works, 158 stars), Pangolin CRUD Endpoints (fosrl/pangolin, 23k stars) and Backend Patterns (hellangleZ/burn-in-cceverywhere-ralph, 112 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains API Contract Architecture?

devcodex-labs (a GitHub organization) maintains it in devcodex-labs/devcodex, which has 439 GitHub stars. The repository holds 70 skills in this directory. The repository was last updated on September 17, 2026.

Source: devcodex-labs/devcodex on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.