api-design-principles

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.

Quality

47%

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 ./skills/api-design-principles/SKILL.md

Quality

Content

46%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 skill is well-structured and token-efficient with clear use/don't-use boundaries, but its guidance is high-level and delegates all concrete detail to a referenced playbook that does not exist, leaving the real bundle files orphaned. Workflow steps lack an error-recovery loop.

Suggestions

Fix the broken reference: point to the actual bundle files, e.g. 'See references/rest-best-practices.md and references/graphql-schema-design.md for patterns; assets/api-design-checklist.md for a review checklist.'

Inline at least one concrete example (e.g. a sample REST resource URL scheme or a GraphQL type snippet) so the body is actionable even before following a reference.

Add an explicit validation feedback loop to the workflow: 'If validation fails, revise the design and re-validate before proceeding.'

Dimension	Reasoning	Score
Conciseness	The body is lean with no padding and no basic-concept explanations, but it restates the frontmatter description verbatim at the top and repeats the same `resources/implementation-playbook.md` reference in both the Instructions and Resources sections — minor trimmable redundancy that keeps it just below a 5.	4 / 5
Actionability	The four instructions are high-level hints ('Define consumers, use cases, and constraints', 'Choose API style and model resources') with no concrete code, commands, or examples, and the detailed patterns/templates are deferred to a `resources/implementation-playbook.md` file that does not exist in the bundle.	2 / 5
Workflow Clarity	A coherent four-step sequence is present and ends with a validation step ('Validate with examples and review for consistency'), but there is no error-recovery feedback loop (what to do when validation fails) and the checkpoints are implicit rather than spelled out.	3 / 5
Progressive Disclosure	The body twice signals a `resources/implementation-playbook.md` reference that is a broken path (no such file exists), while the real bundle files (references/graphql-schema-design.md, references/rest-best-practices.md, assets/api-design-checklist.md, assets/rest-api-template.py) are never mentioned — navigation is broken and actual materials are undiscoverable.	2 / 5
	Total	11 / 20 Passed

Description

48%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 names a clear domain but leans on abstract aspirational language ('intuitive, scalable, maintainable, delight developers') rather than concrete capabilities, and it omits any 'when to use' trigger guidance. It is distinct enough but mid-pack on specificity and completeness.

Suggestions

Replace abstract outcome adjectives with concrete actions, e.g. 'Design REST resources and GraphQL schemas, define versioning/pagination/error strategies, and review API specs for consistency.'

Add an explicit trigger clause: 'Use when designing or refactoring REST/GraphQL APIs, establishing API standards, or reviewing API specifications.'

Include common synonyms users say ('endpoints', 'API specs', 'API contracts') to improve trigger-term coverage.

Dimension	Reasoning	Score
Specificity	The description names the domain ('REST and GraphQL API design principles') but the only 'action' is the abstract goal 'to build intuitive, scalable, and maintainable APIs' — these are adjectives of outcome, not concrete actions like designing endpoints or versioning.	2 / 5
Completeness	A clear 'what' is present (master API design principles to build good APIs) but the 'when' is entirely missing — there is no 'Use when...' clause or equivalent, so completeness is capped at 3 per the judging guideline.	3 / 5
Trigger Term Quality	'REST', 'GraphQL', and 'API design' are natural terms a user might say, but coverage stops there — no synonyms, no trigger phrasing, and no mention of 'endpoints' or 'API specs' that users also commonly say.	3 / 5
Distinctiveness Conflict Risk	'REST and GraphQL API design' carves a reasonably specific niche that is mostly distinguishable from other skills, with only minor overlap risk against generic API/build skills.	4 / 5
	Total	12 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: sickn33/agentic-awesome-skills
Path: skills/api-design-principles/SKILL.md
Commit: b1aebac

Reviewed: ~18 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.