api-design

REST API设计模式，包括资源命名、状态码、分页、过滤、错误响应、版本控制和生产API的速率限制。

Quality

75%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./docs/zh-CN/skills/api-design/SKILL.md

Quality

Content

78%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is highly actionable with concrete executable examples across three languages and a useful pre-publish checklist, and it avoids over-explaining known concepts. Its main weakness is progressive disclosure: everything is inlined in one long file with no bundle references to offload detail.

Suggestions

Split the implementation-pattern code (TypeScript/Python/Go) and the rate-limit/versioning reference into separate files under references/ and link to them from SKILL.md, keeping the overview lean.

Add explicit "see X.md" navigation links at the start of each major section so the in-depth material is one level deep and clearly signaled.

Trim the response-wrapper-variants and pagination tradeoff prose slightly to tighten conciseness toward the lean anchor.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean reference material (tables, code blocks, URL/SQL examples) that assumes Claude knows REST/HTTP rather than explaining those concepts, with only minor trims possible; it is voluminous but not padded.	4 / 5
Actionability	It provides copy-paste-ready executable code in TypeScript, Python, and Go plus concrete URL patterns, SQL, and headers covering the common cases, matching the fully-executable anchor.	5 / 5
Workflow Clarity	A clear pre-publish checklist and a sequenced versioning/deprecation strategy provide most checkpoints, but there is no explicit validate→fix→retry feedback loop, leaving it just below the full-checkpoint anchor; no destructive/batch cap applies since this is a design reference skill.	4 / 5
Progressive Disclosure	There are no bundle files (references/scripts/assets absent) and the entire ~520-line body is inlined with section headers but no external file references, so content that could live in separate files is monolithic with only some structural organization.	3 / 5
	Total	16 / 20 Passed

Description

71%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is specific and domain-rich with comprehensive coverage of REST API design topics, but it omits any explicit "when to use" trigger guidance, which is the main weakness. It uses appropriate third-person voice and is concise rather than padded.

Suggestions

Append an explicit trigger clause, e.g. "Use when designing new REST API endpoints, reviewing API contracts, or adding pagination/error-handling/versioning features" so both what and when are answered.

Add a few natural synonyms (e.g. "rate limiting", "API endpoints", "HTTP") to broaden trigger-term coverage for users phrasing requests in English.

Keep the enumerated topic list but pair it with the trigger guidance to lift completeness from 3 toward 4-5.

Dimension	Reasoning	Score
Specificity	Enumerates multiple concrete actions — "资源命名、状态码、分页、过滤、错误响应、版本控制和生产API的速率限制" — giving comprehensive coverage of REST API design concerns, matching the anchor for listing multiple specific concrete actions.	5 / 5
Completeness	The "what" is clear (REST API design patterns and its enumerated subtopics) but there is no "Use when..." or equivalent explicit trigger guidance, which per the judging guidelines caps completeness at 3.	3 / 5
Trigger Term Quality	Natural terms like "REST API设计模式", "状态码", "分页", "过滤", "速率限制" cover the domain well, but synonyms and file/format extensions are limited, so it falls just below the comprehensive-coverage anchor.	4 / 5
Distinctiveness Conflict Risk	The REST API design niche is specific with low overlap risk, but trigger phrasing is not distinctive enough to fully rule out adjacency with general backend/web skills, placing it between the mostly-distinct and minimal-conflict anchors.	4 / 5
	Total	16 / 20 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (524 lines); consider splitting into references/ and linking	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: xu-xiang/everything-claude-code-zh
Path: docs/zh-CN/skills/api-design/SKILL.md
Commit: dfbf946

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.