Api Design

API design specification and best practices skill. Use when: designing new APIs, reviewing existing APIs, generating API documentation, standardizing interfa...

Security Scan

This is an instruction-only API design/reference skill that is internally consistent: it only reads its bundled documentation and does not request credentials, install software, or contact external endpoints.

Purpose & Capability

Name and description (API design, review, documentation) match the packaged files: design principles, templates, review checklists, and docs. There are no unrelated requirements (no binaries, env vars, or config paths).

Instruction Scope

SKILL.md instructs the agent to read local reference files and use templates to produce docs/review output — this is appropriate. The reference docs contain example CLI commands (npm, docker, curl) and sample tokens/passwords in examples; those are illustrative only. Recommend caution: do not paste real secrets into examples or prompt the agent to run those commands automatically.

Install Mechanism

No install spec and no code files to write or execute. Lowest-risk category (instruction-only).

Credentials

The skill requires no environment variables, credentials, or config paths. All content is local documentation and templates, so requested privileges are proportional.

Persistence & Privilege

always is false and there is no install-time modification or persistent agent configuration. The skill is user-invocable and the platform default allows autonomous invocation, but that default is not combined here with any broad privileges or credentials.

Scan Findings in Context

[no_regex_findings] expected: The regex-based scanner found nothing to analyze; this is expected for an instruction-only skill composed of markdown files (no executable code).

Assessment

This skill is a local API design guide and appears coherent and low-risk. Before installing: (1) confirm you trust the skill source (homepage unknown); (2) avoid pasting real secrets or production tokens into prompts or example templates (the docs include sample tokens/passwords for illustration); (3) if your agent environment can run shell/CLI commands, be explicit about whether you want the agent to execute any npm/docker/curl examples from the docs — the skill itself does not automatically install or run those tools. If you need networked behavior or credential use, request that from a skill that explicitly declares those needs.

API Design Skill

API 设计规范与最佳实践技能，提供从设计到文档生成的完整指导。

核心能力

1. API 设计原则 — RESTful 设计最佳实践
2. 命名规范 — 资源、端点、参数命名标准
3. HTTP 状态码 — 完整状态码参考
4. 错误响应格式 — 统一错误结构
5. 版本管理 — URL 版本策略
6. OpenAPI 模板 — 快速生成 API 文档
7. 审查清单 — 设计审查检查点

使用场景

场景 1: 设计新 API

1. 读取 references/common/design-principles.md 了解设计原则
2. 读取 references/design/resource-modeling.md 进行资源建模
3. 读取 references/design/endpoint-design.md 设计端点
4. 使用 references/templates/openapi3-template.md 生成 OpenAPI 文档
5. 使用 references/review/api-review-checklist.md 自查

场景 2: 审查现有 API

1. 读取 references/review/api-review-checklist.md
2. 按清单逐项审查
3. 输出审查报告

场景 3: 规范化接口

1. 读取 references/common/naming-conventions.md 检查命名
2. 读取 references/common/error-response-format.md 检查错误格式
3. 读取 references/common/versioning-strategy.md 检查版本策略
4. 生成整改建议

文件结构

api-design/
├── SKILL.md
└── references/
    ├── common/
    │   ├── design-principles.md
    │   ├── naming-conventions.md
    │   ├── http-status-codes.md
    │   ├── error-response-format.md
    │   └── versioning-strategy.md
    ├── design/
    │   ├── resource-modeling.md
    │   ├── endpoint-design.md
    │   └── security-best-practices.md
    ├── templates/
    │   └── openapi3-template.md
    ├── review/
    │   └── api-review-checklist.md
    └── documentation/
        └── doc-generation-guide.md