技能 api-design

📦

api-design

Name: api-design
Author: supercent-io

v1.0.0 内容修订 r1 安全 ⚙️ 外部命令🌐 网络访问

设计更好的 REST 和 GraphQL API

API 团队需要在实现开始之前建立一致的契约。此技能可指导资源设计、请求格式、错误、版本控制和文档编写。

支持: Claude Codex Code(CC)

🥈 80 白银

使用我的智能体安装

将此请求复制给你的智能体，其中包含权威 Skill 页面和清单。

智能体请求

Review the Skillstore skill "api-design" from https://skillstore.io/skills/supercent-io-api-design.md and its manifest at https://skillstore.io/api/skills/supercent-io-api-design/manifest. Verify the artifact. You may proceed after verification, subject to the environment's own policy.

你的智能体仍应展示其计划，并按安全策略请求必要确认。

Agent 可读资源

当 AI Agent、爬虫或脚本需要干净上下文，而不是读取完整页面时，请使用这些链接。

Markdown 详情 GET /skills/supercent-io-api-design.md 已签名 manifest GET /api/skills/supercent-io-api-design/manifest 已签名 lockfile GET /api/skills/supercent-io-api-design/lockfile

测试它

正在使用“api-design”。为账户资料和角色设计用户管理 API。

预期结果:

用户、角色和成员关系的资源映射。
包含方法、状态码和验证说明的端点描述。
一致的错误响应模型和分页策略。

正在使用“api-design”。在前端集成之前审查产品目录 API。

预期结果:

命名、过滤、排序和缓存问题清单。
带有兼容性说明的推荐端点变更。
可能阻碍前端或合作伙伴团队的文档缺口。

正在使用“api-design”。决定分析仪表板应使用 REST 还是 GraphQL。

预期结果:

查询灵活性、缓存、架构演进和客户端复杂性的比较。
包含风险和迁移考虑因素的推荐架构。

安全审计

安全

v4 • 2026/7/7 打开版本化报告

All static findings are false positives from Markdown API examples, HTTP status labels, and public documentation links. I found no executable scripts, no runtime network calls, and no prompt injection text in the reviewed files. No semantic security findings were identified.

已扫描文件

360

分析行数

复核项

已忽略误报

风险因素

⚙️ 外部命令 (50)

🌐 网络访问 (5)

SKILL.md:184 SKILL.md:323 SKILL.md:324 SKILL.md:325 SKILL.md:326

最新一次完成的静态与语义审计未检测到已确认的安全发现。这并不能证明该 Skill 没有副作用。

审计者: codex 查看审计历史 →

分享与引用此报告

分享版本化评估报告、中性徽章、嵌入卡片和引用。Skillstore 只报告证据，不判断该 Skill 是否安全。

打开版本化报告

复制报告链接

https://skillstore.io/skills/supercent-io-api-design/audits/4?utm_source=security_passport&utm_medium=share&utm_campaign=versioned_report

Markdown 徽章

[![Skillstore security assessment](https://skillstore.io/badges/skills/supercent-io-api-design/security.svg)](https://skillstore.io/skills/supercent-io-api-design?utm_source=security_passport_badge)

HTML 徽章

<a href="https://skillstore.io/skills/supercent-io-api-design?utm_source=security_passport_badge"><img src="https://skillstore.io/badges/skills/supercent-io-api-design/security.svg" alt="Skillstore security assessment" loading="lazy"></a>

嵌入卡片

<iframe src="https://skillstore.io/embed/skills/supercent-io-api-design.html" title="Skillstore Security Assessment" sandbox="allow-popups allow-popups-to-escape-sandbox" loading="lazy" referrerpolicy="no-referrer" width="420" height="180"></iframe>

学术引用 (APA · BibTeX · CFF)

APA 引用

supercent-io. (2026). api-design security audit report (audit version 4) [Author version 1.0.0]. Skillstore. https://skillstore.io/skills/supercent-io-api-design/audits/4

BibTeX 引用

@techreport{supercent-io-supercent-io-api-design-2026,
  author = {supercent-io},
  title = {api-design security audit report (audit version 4)},
  institution = {Skillstore},
  year = {2026},
  number = {4},
  url = {https://skillstore.io/skills/supercent-io-api-design/audits/4},
  note = {Author version 1.0.0}
}

CITATION.cff

cff-version: 1.2.0
message: "If you use this Skill, cite its author and this versioned security audit report."
title: "api-design security audit report (audit version 4)"
version: "1.0.0"
type: report
authors:
  - name: "supercent-io"
date-released: "2026-07-07"
url: "https://skillstore.io/skills/supercent-io-api-design/audits/4"
identifiers:
  - type: other
    value: "skillstore:supercent-io-api-design:audit:4"
    description: "Skillstore immutable audit report identifier"

比较变体

2 个可安装变体

每位作者的技能都保持为独立的可安装项。推荐变体按 Skillstore 证据排序。

为什么此变体排名第一

Skillstore 评分最高

作者 / 来源 Skillstore 评分证据置信度 Skillstore 使用量已更新

supercent-io 推荐当前

supercent-io-api-design

Skillstore 评分 80

证据置信度高

Skillstore 使用量 22

已更新

2026-09-09

Benny9193

benny9193-api-design

Skillstore 评分 78

证据置信度高

Skillstore 使用量 13

已更新

2026-09-09

Skillstore 评分

评分依据证据置信度: 高

架构

100

可维护性

内容

社区

规范符合性

你能构建什么

规划新的服务 API

在实现开始之前定义资源、端点、状态码和响应结构。

审查现有 API 契约

找出当前 API 设计中的命名、分页、错误和版本控制不一致问题。

准备开发者文档

将端点需求转化为清晰的 OpenAPI 导向文档和集成示例。

试试这些提示

创建基本 REST 端点

为 {resource} 资源设计 REST 端点。包括方法、路径、状态码以及简单的请求和响应说明。

添加分页和过滤

为 {resource} 设计列表端点。包括分页、过滤、排序、字段选择和示例错误情况。

起草 OpenAPI 契约

为 {service} 创建 OpenAPI 导向的大纲。包括端点、架构、身份验证、错误和版本控制指导。

比较 REST 和 GraphQL

评估 {domain} 的 REST 和 GraphQL 设计。推荐一种方法，并说明数据结构、缓存、身份验证和版本控制方面的权衡。

最佳实践

在命名端点之前，先明确资源、关系和授权规则。
在各服务之间保持响应、错误、分页和版本控制模式一致。
将架构和示例与端点决策一起记录，使契约保持可审查。

避免

在没有一致资源模型的情况下，在路径中混用动词和名词。
为每个端点添加自定义错误结构，而不使用共享代码和字段。
仅仅为了掩盖不清晰的资源边界或授权规则而选择 GraphQL。

常见问题

此技能会生成生产级 API 代码吗？

不会。它指导 API 设计和文档编写，但实现仍然取决于具体项目。

它能帮助编写 OpenAPI 文档吗？

可以。它概述 OpenAPI 3.0 结构、架构、路径、响应和身份验证部分。

它支持 GraphQL 设计吗？

支持。它包含 GraphQL 架构指导，并帮助比较 GraphQL 与 REST。

它能审查现有端点吗？

可以。它可以评估命名、一致性、分页、错误、身份验证和版本控制选择。

它会进行实时网络调用吗？

不会。该技能提供文档指导，不会调用外部 API。

哪些工具可以使用此技能？

报告列出支持 Claude、Codex 和 Claude Code。

开发者详情

作者

supercent-io

许可证

Apache-2.0

作者版本

v1.0.0

Skillstore 修订

仓库

https://github.com/supercent-io/skills-template/tree/main/.agent-skills/api-design/

引用

f93e9bb0daca99badb6a7e574b97737155d57cb3

维护新鲜度

2026/7/18

使用量

15 次下载 · 104 次浏览

文件结构

📄 SKILL.md

📄 SKILL.toon