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

39%

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 ./plugins/AI-Agents-Safe-Coding-Skills-claude/skills/api-design-principles/SKILL.md

The canonical home for this skill is api-design-principles in rmyndharis/antigravity-skills

Quality

Content

38%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 has clean structure and a sensible high-level workflow, but it is only abstractly actionable and its progressive disclosure is broken: it points to a non-existent playbook while leaving the real reference and asset files orphaned.

Suggestions

Fix the reference path: point to the actual bundle files (references/rest-best-practices.md, references/graphql-schema-design.md, assets/api-design-checklist.md, assets/rest-api-template.py) instead of the missing `resources/implementation-playbook.md`.

Add concrete specifics to each instruction step — e.g. naming conventions, error format, pagination style, auth scheme — or inline a short worked example rather than deferring entirely to a referenced file.

Add a validation feedback loop in the workflow (validate spec against examples → fix inconsistencies → re-validate) and remove the duplicate Resources entry / repeated fluff intro.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean (short trigger lists, brief 4-step instructions), but it repeats the marketing-fluff intro sentence and cites `resources/implementation-playbook.md` twice — padding that could be trimmed.	3 / 5
Actionability	The four instructions are high-level hints ('Define consumers, use cases, and constraints', 'Choose API style and model resources or types') with no concrete specifics, examples, or commands, and the detailed guidance is deferred to a referenced file.	2 / 5
Workflow Clarity	A clear 4-step sequence is present and step 4 names validation ('Validate with examples and review for consistency'), but there are no explicit validation checkpoints or a validate-fix-retry feedback loop, so checkpoints remain implicit.	3 / 5
Progressive Disclosure	Although the sections are well-organized, the sole reference `resources/implementation-playbook.md` does not exist in the bundle, and the four real bundle files (rest-best-practices.md, graphql-schema-design.md, api-design-checklist.md, rest-api-template.py) are never surfaced, so navigation is effectively broken.	2 / 5
	Total	10 / 20 Passed

Description

40%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 reads as marketing copy: it names a clear niche but offers no concrete actions and no 'Use when' trigger guidance, leaving both the what and the when underspecified.

Suggestions

Replace abstract fluff ('delight developers', 'stand the test of time') with concrete actions such as 'model resources and types, define versioning and pagination, specify error and auth strategies'.

Add an explicit trigger clause, e.g. 'Use when designing or refactoring REST or GraphQL APIs, reviewing API specs, or migrating between API paradigms'.

Include natural synonyms users would say (endpoints, OpenAPI, schema, versioning) to broaden trigger coverage.

Dimension	Reasoning	Score
Specificity	The description names the domain (REST and GraphQL API design) but the only 'action' is the generic 'Master ... principles to build ... APIs', padded with marketing fluff like 'delight developers' and 'stand the test of time' rather than concrete actions.	2 / 5
Completeness	The 'what' is vague (build intuitive/scalable/maintainable APIs) and the 'when' is entirely missing — there is no 'Use when...' clause or equivalent explicit trigger guidance, so it sits at the vague-what/no-when anchor.	2 / 5
Trigger Term Quality	'REST', 'GraphQL', and 'API design' are natural terms a user would say, but common variations and synonyms like 'endpoints', 'versioning', 'OpenAPI', or 'schema' are absent.	3 / 5
Distinctiveness Conflict Risk	REST and GraphQL API design is a clear, mostly distinct niche with only minor overlap risk against adjacent documentation or code-review skills; it is not score 5 because no explicit trigger phrases sharpen the boundary.	4 / 5
	Total	11 / 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: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: plugins/AI-Agents-Safe-Coding-Skills-claude/skills/api-design-principles/SKILL.md
Commit: 900c504

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