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

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

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 body is concise and well-structured with useful trigger guidance, but its core instruction is abstract high-level steps with no concrete patterns or examples, and its progressive disclosure is broken: it references a non-existent playbook while the real bundle files go unlinked.

Suggestions

Replace the abstract four-step list with concrete, actionable guidance — e.g. specific resource-naming rules, versioning strategies, and a worked endpoint example — or point to the real bundle files that contain them.

Fix the broken reference: link 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 nonexistent resources/implementation-playbook.md.

Add an explicit, concrete validation checkpoint in the workflow (e.g. 'Run through the api-design-checklist.md and confirm each endpoint has versioning, pagination, and error contract') rather than the vague 'review for consistency'.

Dimension	Reasoning	Score
Conciseness	The body is lean (~30 lines) with well-organized Use/Do-not-use/Instructions sections and no over-explanation of concepts Claude already knows; the only trimmable fluff is the repeated aspirational tagline duplicated from the frontmatter.	4 / 5
Actionability	The four numbered steps are high-level hints ('Define consumers, use cases, and constraints', 'Choose API style and model resources or types') with no concrete patterns, examples, or specifics, and the only detailed reference points to a file that does not exist in the bundle.	2 / 5
Workflow Clarity	A clear four-step sequence is present and step 4 mentions validation ('Validate with examples and review for consistency'), but the checkpoint is vague and implicit rather than a concrete, executable validation step.	3 / 5
Progressive Disclosure	The body twice references `resources/implementation-playbook.md`, which is not present in the bundle, while the actual files in references/ (graphql-schema-design.md, rest-best-practices.md) and assets/ (api-design-checklist.md, rest-api-template.py) are never linked, leaving the overview pointing at a dead path and ignoring real detail material.	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 clearly names its domain and is reasonably distinct, but it leans on buzzword-heavy aspirational language ('delight developers', 'stand the test of time') and omits any explicit 'Use when' trigger guidance, which caps completeness. Voice is second-person imperative, lowering specificity.

Suggestions

Rewrite in third person and lead with concrete capabilities, e.g. 'Designs REST and GraphQL APIs: resource modeling, versioning, pagination, error handling, and auth strategy.'

Add an explicit 'Use when...' clause with natural triggers like 'Use when designing or refactoring REST/GraphQL APIs, reviewing API specs, or setting team API standards.'

Trim aspirational fluff ('delight developers', 'stand the test of time') and add concrete synonyms (endpoints, OpenAPI, schema) for better trigger coverage.

Dimension	Reasoning	Score
Specificity	Names the domain ('REST and GraphQL API design principles') but the actions are generic aspirational phrasing ('build intuitive, scalable, and maintainable APIs that delight developers') rather than concrete capabilities; the imperative 'Master' is second-person voice, triggering the -1 specificity penalty from a base of 3.	2 / 5
Completeness	It states a clear 'what' (master REST/GraphQL API design principles) but provides no 'Use when...' clause or equivalent explicit trigger guidance, so completeness is capped at 3 per the rubric guideline.	3 / 5
Trigger Term Quality	'REST', 'GraphQL', and 'API design' are natural terms a user would say, but common variations and synonyms like 'endpoints', 'OpenAPI', 'schema', or 'API spec' are missing.	3 / 5
Distinctiveness Conflict Risk	The REST + GraphQL API design niche is mostly distinct from other skills, with only minor overlap risk against generic API or framework-specific skills, though no explicit distinct triggers are given.	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: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: plugins/AI-Agents-Safe-Coding-Skills/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.