api-design SKILL.md skillA

This file is byte-identical to the first copy the registry indexed. Same content hash, so the same checks give both the same grade.

api-design from projanvil/mindforge is an agent skill: a SKILL.md folder an AI agent loads when a task calls for it.

mdr add projanvil/mindforge/api-design@git:20261016.6f8a292

Pins git:20261016.6f8a292 in mdr.lock. Pin the fingerprint instead.

Audit grade

A, 17 of 17 checks passed

Kind

SKILL.md skill

Repository

projanvil/mindforge

Path

plugins/mindforge-zh-cn/skills/api-design/SKILL.md

Versions recorded

1

Latest version

git:20261016.6f8a292, committed Oct 16, 2026

Size

9,186 bytes

Repository stars

3

License

MIT

专业的 API 设计技能，涵盖 RESTful API、GraphQL、API 版本控制、身份认证、幂等性和 API 文档最佳实践。使用此技能设计 RESTful API、GraphQL schema、API 版本策略，或需要 API 文档和认证授权指导时使用。.

Collected from public GitHub. Every version is saved exactly as it was and never changes. Install it at an exact version with the mdr tool, and every file is checked before it reaches your agent. The main file is checked against the SHA-256 fingerprint recorded here, and the others against the fingerprints GitHub keeps for its source commit. The automatic checks below grade the latest version, and the same checks always give the same file the same grade.

What the file says

# API 设计技能

你是一位拥有 15 年以上经验的专家级 API 架构师，精通设计健壮、可扩展和开发者友好的 API。你专注于 RESTful API 设计、GraphQL、API 版本控制、身份认证/授权和 API 安全最佳实践。

## 何时使用

触发场景：当用户提出以下请求时，使用本 skill：

- 当需要设计或评审 REST / GraphQL API 时
- 当需要设计版本控制、分页、错误格式或限流时
- 当用户要求编写 OpenAPI 规范或 API 文档时

## 你的专业领域

### 核心 API 技术领域
- **RESTful API 设计**: 资源建模、URI 设计、HTTP 方法选择、HATEOAS
- **GraphQL 设计**: Schema 设计、resolver 模式、查询优化、联邦
- **API 版本控制**: URI 版本控制、Header 版本控制、向后兼容策略
- **幂等性**: 幂等性键模式、分布式锁、状态机设计
- **身份认证/授权**: OAuth 2.0、JWT、API 密钥、RBAC/ABAC、细粒度权限
- **错误处理**: 统一错误响应、错误码设计、国际化
- **API 文档**: OpenAPI/Swagger、示例、变更日志、开发者门户
- **性能**: 缓存策略、分页、压缩、速率限制
- **API 安全**: 输入验证、注入防护、CORS、HTTPS、密钥管理

### 技术深度
- HTTP 协议 (1.1, 2, 3) 和状态码
- API 网关模式和工具
- 服务网格和 API 管理平台
- 契约测试和 API 版本控制策略
- 开发者体验优化
- API 监控和可观测性

## 你遵循的核心原则

### 1. RESTful 设计原则

#### 面向资源的架构
```
✅ 良好的资源设计:
GET    /api/v1/users              # 集合
POST   /api/v1/users              # 创建
GET    /api/v1/users/{id}         # 单个资源
PUT    /api/v1/users/{id}         # 完全更新
PATCH  /api/v1/users/{id}         # 部分更新
DELETE /api/v1/users/{id}         # 删除
GET    /api/v1/users/{id}/posts   # 子资源

❌ 不良设计:
GET    /api/getUsers              # URI 中包含动词
POST   /api/createUser            # 非面向资源
…

Read the whole file at its exact version.

How to install

mdr add projanvil/mindforge/api-design@sha256:af7e5a37889f5100

[![mdr](https://markdownregistry.com/badge/art_ldi5xfnylsrxuuze.svg)](https://markdownregistry.com/a/art_ldi5xfnylsrxuuze)

Versions

The registry has recorded 1 version of this file, committed on Oct 16, 2026.

Audit of the latest version

Source

API

GET https://markdownregistry.com/api/v1/artifacts/art_ldi5xfnylsrxuuze
GET https://markdownregistry.com/api/v1/resolve?ref=projanvil/mindforge/api-design
GET https://markdownregistry.com/api/v1/blob/af7e5a37889f5100a3af1d9d70868dca417344ebbf8a23269166fb5a720a9e77

Your AI assistant does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.

Guides: the SKILL.md format and its required fields · what to check before you install a skill · how to pin a skill to an exact version · where to find agent skills · keeping a team on the same skills · which agent file does what.

More from projanvil/mindforge

Every file in projanvil/mindforge

Other files named api-design

Browse by kind, by grade A, or by owner.