api-design-principles

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.

1.13x

Quality

73%

Does it follow best practices?

Impact

94%

1.13x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./tests/ext_conformance/artifacts/agents-wshobson/backend-development/skills/api-design-principles/SKILL.md

The canonical home for this skill is api-design-principles in wshobson/agents

Quality

Content

65%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 body is highly actionable with comprehensive executable templates, but it is over-long, explains basics Claude already knows, lacks a sequenced design-review workflow with validation checkpoints, and ships broken bundle references alongside heavy inlining.

Suggestions

Move the full GraphQL schema, resolver, and DataLoader code blocks into the referenced template files and keep SKILL.md as an overview with short illustrative snippets, so the body earns a leaner token budget.

Delete or create the three missing referenced files (references/api-versioning-strategies.md, assets/graphql-schema-template.graphql, scripts/openapi-generator.py) so every Resources entry resolves to a real file.

Cut the 'Core Concepts' explanations of basic REST/GraphQL mechanics (HTTP method semantics, what queries/mutations are) and replace them with a short sequenced design-review workflow that ends in validating the design against assets/api-design-checklist.md.

Dimension	Reasoning	Score
Conciseness	The body is mostly actionable code, but the 'Core Concepts' section explains basics Claude already knows (HTTP method semantics, 'queries for reading data, mutations for modifying data', 'resources are nouns not verbs') and repeats the 'delight developers / stand the test of time' fluff from the description.	3 / 5
Actionability	Provides copy-paste-ready executable code across the common cases — FastAPI pagination/filtering, error responses, HATEOAS links, a full GraphQL schema, resolvers, and DataLoader — covering the breadth of real API design tasks.	5 / 5
Workflow Clarity	The content is organized by topic (concepts → patterns → best practices → pitfalls) rather than as a sequenced workflow, and there are no explicit validation checkpoints (e.g., 'review the design against the checklist before implementing') for what is ultimately a review/design task.	3 / 5
Progressive Disclosure	There is section structure and a Resources list, but large blocks that belong in reference files (full GraphQL schema, resolver/DataLoader implementations) are inlined, and 3 of the 7 referenced bundle files do not exist (api-versioning-strategies.md, graphql-schema-template.graphql, scripts/openapi-generator.py).	3 / 5
	Total	14 / 20 Passed

Description

82%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 well-formed: it states both what the skill does and when to use it with explicit trigger phrases, and occupies a distinct niche. Its main weakness is mildly abstract, buzzword-tinged capability language rather than crisp concrete actions.

Dimension	Reasoning	Score
Specificity	Names the domain ('REST and GraphQL API design principles') and a couple of actions ('build intuitive, scalable, and maintainable APIs'), but the actions are abstract rather than concrete like 'extract text, fill forms'; 'delight developers' is buzzword fluff that does not add a concrete capability.	3 / 5
Completeness	Explicitly answers both what ('Master REST and GraphQL API design principles to build... APIs') and when ('Use when designing new APIs, reviewing API specifications, or establishing API design standards') with concrete trigger phrases, matching the top anchor.	5 / 5
Trigger Term Quality	Includes natural trigger phrases users would say ('designing new APIs', 'reviewing API specifications', 'establishing API design standards') plus REST and GraphQL, but misses common synonyms like 'OpenAPI', 'Swagger', 'API spec', or 'endpoints'.	4 / 5
Distinctiveness Conflict Risk	Targets a clear niche (REST and GraphQL API design) with distinct triggers that are unlikely to fire for unrelated skills, giving minimal conflict risk.	5 / 5
	Total	17 / 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 (529 lines); consider splitting into references/ and linking	Warning
referenced_paths_exist	Referenced path issues: 3 missing	Warning

	Total	14 / 16 Passed

Repository: Dicklesworthstone/pi_agent_rust
Path: tests/ext_conformance/artifacts/agents-wshobson/backend-development/skills/api-design-principles/SKILL.md
Commit: 6453c0b

Reviewed: about 9 hours 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.