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.

Quality

68%

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_all/api-design-principles/SKILL.md
SKILL.md
Quality
Evals
Security

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 contains genuinely useful, largely executable REST/GraphQL design patterns, but it violates progressive disclosure severely: it inlines a full design guide while pointing to seven bundle files that do not exist, and it spends much of its length on concepts and boilerplate Claude already knows. Converting it into a lean overview with a sequenced design workflow and real companion files would address its core weaknesses.

Suggestions

Either create the seven referenced bundle files (references/, assets/, scripts/) or remove the dangling Resources section; currently every cited path is broken.

Cut the SKILL.md body to a lean overview: move the full pattern implementations into the reference/asset files and drop basic-concept explanations (HTTP method semantics, HATEOAS primer) that Claude already knows.

Replace the pattern catalog with a sequenced design workflow — e.g., identify resources → define schema → choose versioning strategy → validate against a checklist — with an explicit validation checkpoint step referencing a real checklist file.

DimensionReasoningScore

Conciseness

At 527 lines the body inlines large amounts of material Claude already knows — HTTP method semantics ('GET: Retrieve resources (idempotent, safe)'), a HATEOAS primer, full pagination/resolver/DataLoader implementations — plus aspirational padding ('APIs that delight developers and stand the test of time'). This matches anchor 2 (noticeably verbose, several unnecessary explanations); not 1 because the prose is structured rather than padded, and not 3 because the bloat is pervasive, not a few trimmable spots.

2 / 5

Actionability

Mostly executable, concrete guidance: complete FastAPI pagination and error-handling endpoints, a full GraphQL schema, ariadne resolvers, and DataLoader classes. Minor gaps keep it below anchor 5 — undefined helpers (fetch_users, build_query, encode_cursor, hash_password, paginate_orders), missing imports (Any, ValidationError), and a bare @app.get('/api/users/{user_id}') example without its route decorator context.

4 / 5

Workflow Clarity

The body is a pattern catalog, not a workflow: sections are organized by topic, but there is no sequenced design process (e.g., identify resources → define schema → version → validate against checklist) and no validation checkpoints. The one artifact that would act as a checkpoint (assets/api-design-checklist.md) is referenced but missing. This matches anchor 3 (content present but checkpoints/sequence missing); not 2 because the section structure is coherent and navigable.

3 / 5

Progressive Disclosure

The Resources section cites seven bundle files (references/rest-best-practices.md, assets/rest-api-template.py, scripts/openapi-generator.py, etc.), but no references/, assets/, or scripts/ directories exist — every reference is dangling. Meanwhile ~450 lines of pattern content that clearly belongs in those files is inlined in SKILL.md itself. This matches anchor 2 (content that belongs in separate files is inlined, references broken); not 1 because section headers provide real navigation, and not 3 because the references are not merely under-signaled — they are nonexistent.

2 / 5

Total

11

/

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.

A well-formed description with an explicit 'Use when' trigger clause covering three concrete scenarios and a clearly scoped REST/GraphQL niche. Its main weakness is that the capability statement itself is aspirational fluff ('delight developers') rather than concrete actions, and it omits common trigger synonyms like 'endpoints' or 'OpenAPI'.

DimensionReasoningScore

Specificity

The description names the domain clearly ('REST and GraphQL API design principles') but the stated actions are generic — 'build intuitive, scalable, and maintainable APIs that delight developers' conveys no concrete capability (no 'design resource endpoints', 'define schemas', 'generate OpenAPI specs'). It matches anchor 3 (domain plus 1-2 weak concrete actions) rather than 4, which requires several specific actions.

3 / 5

Completeness

Explicitly answers both what ('Master REST and GraphQL API design principles to build... APIs') and when ('Use when designing new APIs, reviewing API specifications, or establishing API design standards') with three concrete trigger phrases. This matches anchor 5; the when-clause is specific and explicit, not the weaker form described by anchor 4.

5 / 5

Trigger Term Quality

Includes natural phrases users would say — 'REST', 'GraphQL', 'API design', 'designing new APIs', 'reviewing API specifications', 'establishing API design standards'. Good coverage, but common variations like 'endpoints', 'API schema', 'OpenAPI/Swagger', or 'versioning' are missing, matching anchor 4 rather than 5.

4 / 5

Distinctiveness Conflict Risk

A clear niche (REST/GraphQL API design) with distinct triggers, but 'reviewing API specifications' and 'establishing API design standards' overlap with code-review and documentation-related skills. Mostly distinct with minor overlap risk — anchor 4 rather than 5.

4 / 5

Total

16

/

20

Passed

Validation

87%

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

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (528 lines); consider splitting into references/ and linking

Warning

referenced_paths_exist

Referenced path issues: 7 missing

Warning

Total

14

/

16

Passed

Repository

Microck/ordinary-claude-skills

Path

skills_all/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.