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

70%

Does it follow best practices?

Impact

94%

1.13x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

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

Quality

Content

65%

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 strong concrete code examples but is bloated for an overview and duplicates reference material that should live in the bundle files. Navigation is weakened by dangling resource paths and the absence of a sequenced, validated workflow.

Suggestions

Move the full GraphQL schema, resolver, and DataLoader code blocks into the references/assets files and replace them in SKILL.md with concise summaries plus inline links, so the overview stays lean.

Add a short sequenced workflow with validation checkpoints — e.g., draft schema -> review against assets/api-design-checklist.md -> fix -> re-check — to turn the patterns into a guided process.

Fix the Resources section by removing or creating the non-existent paths (references/api-versioning-strategies.md, assets/graphql-schema-template.graphql, scripts/openapi-generator.py) and link each entry inline from the relevant section.

Dimension	Reasoning	Score
Conciseness	The ~520-line body is mostly efficient but carries large reference-grade code blocks (full GraphQL schemas, resolvers, DataLoaders) and restates basics like HTTP method semantics that belong in the reference files rather than the overview.	2 / 3
Actionability	Provides substantial executable, copy-paste-ready code with real imports across FastAPI endpoints, Pydantic models, GraphQL schema definitions, resolvers, and DataLoaders — fully concrete and actionable.	3 / 3
Workflow Clarity	Content is organized by patterns and best practices rather than a sequenced process, with no explicit validation checkpoints or feedback loops (e.g., review-against-checklist then iterate), which caps workflow clarity at 2 for a design/review skill.	2 / 3
Progressive Disclosure	Real bundle files exist and are listed, but the Resources section references three non-existent paths (api-versioning-strategies.md, graphql-schema-template.graphql, scripts/openapi-generator.py) and reference-grade content is duplicated inline rather than offloaded with clear inline links.	2 / 3
	Total	9 / 12 Passed

Description

75%

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 clearly communicates its purpose and triggers, with strong completeness and distinctiveness. It is held back only by abstract actions and missing natural trigger-term variations.

Dimension	Reasoning	Score
Specificity	Names the REST/GraphQL domain and broad actions ("designing," "reviewing," "establishing standards") but does not list multiple concrete actions, matching the anchor that names a domain and some actions without being comprehensive.	2 / 3
Completeness	Explicitly answers both what ("Master REST and GraphQL API design principles...") and when ("Use when designing new APIs, reviewing API specifications, or establishing API design standards"), matching the highest anchor.	3 / 3
Trigger Term Quality	Includes relevant triggers ("designing new APIs," "reviewing API specifications") but misses common variations a user would naturally say, such as "API spec," "endpoint design," or bare "REST/GraphQL."	2 / 3
Distinctiveness Conflict Risk	Scoped tightly to REST and GraphQL API design with triggers tied specifically to API design tasks, giving it a clear niche unlikely to fire for unrelated skills.	3 / 3
	Total	10 / 12 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
Commit: 92e5884

Reviewed: 2 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.