CtrlK
CommunityDocumentationLog inGet started
Tessl Logo

api-design-principles

tessl i github:wshobson/agents --skill 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.

Review Score

64%

Validation Score

13/16

Implementation Score

50%

Activation Score

67%

SKILL.md
Review
Evals

Generated

Validation

Total

13/16

Score

Passed
CriteriaScore

skill_md_line_count

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

metadata_version

'metadata' field is not a dictionary

license_field

'license' field is missing

Implementation

Suggestions 4

Score

50%

Overall Assessment

This skill provides excellent, executable code examples for REST and GraphQL API design patterns, but suffers from significant verbosity by explaining concepts Claude already knows (HTTP methods, GraphQL basics, what pagination is). The content reads more like a comprehensive tutorial than a concise skill reference, and lacks a clear workflow for actually designing an API from start to finish.

Suggestions

  • Remove the 'Core Concepts' section entirely - Claude knows HTTP methods, GraphQL basics, and versioning strategies. Jump directly to the patterns.
  • Cut the 'When to Use This Skill' section - this duplicates the description and wastes tokens on obvious use cases.
  • Add a clear workflow section: 'API Design Process' with numbered steps like '1. Define resources → 2. Design endpoints → 3. Define error responses → 4. Add pagination → 5. Document with OpenAPI'
  • Move the detailed code examples to referenced files (e.g., 'See assets/rest-patterns.py') and keep only minimal examples inline.
DimensionScoreReasoning

Conciseness

1/3

Extremely verbose with extensive explanations of concepts Claude already knows (REST methods, GraphQL basics, HTTP status codes). The 'When to Use This Skill' and 'Core Concepts' sections explain fundamentals that don't need explanation. Could be reduced by 60-70%.

Actionability

3/3

Provides fully executable Python code examples with FastAPI, Pydantic models, GraphQL resolvers, and DataLoaders. Code is copy-paste ready with proper imports and complete implementations.

Workflow Clarity

2/3

Patterns are presented as isolated examples rather than a clear workflow for designing an API. No explicit sequence for 'how to design an API from scratch' with validation checkpoints. The content is more reference material than guided process.

Progressive Disclosure

2/3

References external files at the end (references/, assets/, scripts/) which is good, but the main content is a monolithic wall of text with everything inline. The core concepts and patterns sections could be split into separate files with just summaries here.

Activation

Suggestions 2

Score

67%

Overall Assessment

The description has a solid structure with an explicit 'Use when' clause that clearly defines trigger scenarios. However, it relies on marketing-style language ('delight developers') rather than concrete capabilities, and could benefit from more specific trigger terms that users naturally use when discussing API design.

Suggestions

  • Replace vague qualifiers ('intuitive, scalable, maintainable', 'delight developers') with specific actions like 'define endpoints, structure request/response schemas, handle versioning, design error responses'
  • Add more natural trigger terms users would say: 'endpoints', 'routes', 'OpenAPI', 'swagger', 'API documentation', 'request/response format', 'HTTP methods'
DimensionScoreReasoning

Specificity

2/3

Names the domain (REST and GraphQL API design) and mentions some actions (designing, reviewing, establishing standards), but uses vague qualifiers like 'intuitive, scalable, and maintainable' and 'delight developers' which are abstract rather than concrete capabilities.

Completeness

3/3

Clearly answers both what (API design principles for REST and GraphQL) and when (designing new APIs, reviewing specifications, establishing standards) with an explicit 'Use when' clause containing specific triggers.

Trigger Term Quality

2/3

Includes relevant keywords like 'REST', 'GraphQL', 'API design', 'API specifications', but misses common variations users might say such as 'endpoints', 'routes', 'schema', 'OpenAPI', 'swagger', or 'API documentation'.

Distinctiveness Conflict Risk

2/3

Reasonably specific to API design but could overlap with general coding skills, backend development skills, or documentation skills. The REST/GraphQL focus helps but 'API specifications' and 'design standards' are somewhat broad.

Repository
github.com/wshobson/agents
Last updated
Created

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.

Claim skill