CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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.

53

Quality

67%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/api-design-principles/SKILL.md
SKILL.md
Quality
Evals
Security

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 skill body is lean and well-sectioned but hollow: the instructions are abstract headings with no concrete guidance, and its single pointer to detailed material targets a nonexistent path while all four real bundle files go unmentioned. Both actionability and progressive disclosure fail against the actual bundle structure.

Suggestions

Fix the broken reference: replace `resources/implementation-playbook.md` with pointers to the real bundle files (e.g., 'REST patterns: see references/rest-best-practices.md; GraphQL types: see references/graphql-schema-design.md; review checklist: see assets/api-design-checklist.md'), and list each file under Resources with a one-line description.

Ground the four instruction steps in concrete detail, e.g. 'Specify errors, versioning, pagination, and auth strategy — use the error-model and pagination patterns in references/rest-best-practices.md' or embed one concrete example (an error envelope or resource-naming rule) per step.

Delete the opening line that duplicates the frontmatter description, and state the playbook/bundle pointer once (either in Instructions or in Resources) to remove the duplication.

DimensionReasoningScore

Conciseness

The body is short and assumes Claude's intelligence (no concept explanations), but it repeats the frontmatter description almost verbatim in the opening line ('Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time') and the 'Use this skill when' bullets duplicate the description's triggers, plus the playbook reference is stated twice (Instructions and Resources). Anchor 3 ('mostly efficient but could be tightened') fits; not 4 because the duplication is systematic rather than a couple of stray instances, and not 2 because there is no padded concept explanation or filler beyond the duplication.

3 / 5

Actionability

The Instructions are pure abstractions: 'Define consumers, use cases, and constraints', 'Choose API style and model resources or types', 'Specify errors, versioning, pagination, and auth strategy' — no concrete commands, code, examples, or specific patterns; everything actionable is deferred to `resources/implementation-playbook.md`. This matches anchor 2 ('minimal concrete guidance; high-level hints but missing the specific steps to execute'); not 1 because a coherent high-level outline with named concerns (errors, versioning, pagination, auth) is present, and not 3 because there is no concrete or executable detail anywhere in the body.

2 / 5

Workflow Clarity

The four numbered steps form a recognizable design sequence, and step 4 ('Validate with examples and review for consistency') gestures at validation, but there are no checkpoints, criteria, or feedback loops for what to do when validation fails. Anchor 3 ('steps listed but validation gaps; checkpoints missing or implicit') is the best fit; not 4 because 'validate with examples' is too vague to count as a real checkpoint, and not 2 because the sequence is well-ordered with defined steps rather than gappy.

3 / 5

Progressive Disclosure

Scored against the actual bundle: the body's only reference, `resources/implementation-playbook.md`, does not exist (no resources/ directory), while the four real bundle files (references/rest-best-practices.md, references/graphql-schema-design.md, assets/api-design-checklist.md, assets/rest-api-template.py) are never mentioned, leaving the detail content undiscoverable. This matches anchor 2's broken navigation ('minimal structure... references are buried'); not 1 because SKILL.md itself has clear sections and intended one-level-deep references rather than a monolith or nested chain, and not 3 because navigation to the actual detail files is impossible, not merely unclear.

2 / 5

Total

10

/

20

Passed

Description

78%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 strong on completeness and trigger quality — it explicitly states what it does and gives three concrete use-when triggers — and it occupies a clear niche. Its main weakness is specificity: the capability statement leans on aspirational adjectives ('intuitive, scalable, maintainable', 'delight developers') rather than naming concrete design actions.

Suggestions

Replace aspirational fluff ('build intuitive, scalable, and maintainable APIs that delight developers') with concrete capabilities, e.g. 'Design REST resources and GraphQL schemas, define error models, versioning, pagination, and auth strategies'.

Add commonly used trigger synonyms such as 'endpoints', 'API schema', or 'API documentation' to broaden natural-term coverage.

DimensionReasoningScore

Specificity

Phrases like 'Master REST and GraphQL API design principles' and 'build intuitive, scalable, and maintainable APIs that delight developers' name the domain clearly, but the actions are generic-aspirational; 'delight developers' is buzzword fluff and no concrete capability (define resources, design error models, review specs) is spelled out. Anchor 3 ('names domain and 1-2 concrete actions, but not comprehensive') fits via the implied design/review actions; not 4 because no specific concrete actions are listed, and not 2 because the domain and implied actions exceed a bare 'Processes API files' level.

3 / 5

Completeness

Both questions are answered explicitly: the what ('Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs') and a concrete when clause ('Use when designing new APIs, reviewing API specifications, or establishing API design standards') with three specific trigger phrases. This matches anchor 5; not 4 because the when clause is already explicit and specific rather than in need of sharpening, and the what unambiguously states the skill's function.

5 / 5

Trigger Term Quality

Natural phrases a user would actually say are present: 'designing new APIs', 'reviewing API specifications', 'establishing API design standards', plus the domain terms 'REST' and 'GraphQL'. This matches anchor 4 ('good keyword coverage; a few natural terms missing') — common variations like 'endpoints', 'API schema', 'versioning', or 'developer documentation' are absent; not 5 because synonym/variation coverage is incomplete, and not 3 because the included triggers are genuinely natural rather than partial jargon.

4 / 5

Distinctiveness Conflict Risk

REST/GraphQL API design is a distinct niche, and triggers like 'reviewing API specifications' and 'establishing API design standards' are unlikely to fire for unrelated skills, though 'designing new APIs' could overlap with framework-specific or OpenAPI-spec skills. Anchor 4 ('mostly distinct; minor overlap risk with closely related skills') fits; not 5 because 'designing new APIs' is broad enough to contend with adjacent API-adjacent skills, and not 3 because the domain scoping is substantially tighter than 'works with API files'.

4 / 5

Total

16

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

rmyndharis/antigravity-skills

Path

skills/api-design-principles/SKILL.md

Reviewed

Table of Contents

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.