building-graphql-server
Build production-ready GraphQL servers with schema design, resolvers, and subscriptions. Use when building GraphQL APIs with schemas and resolvers. Trigger with phrases like "build GraphQL API", "create GraphQL server", or "setup GraphQL".
71
66%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/api-development/graphql-server-builder/skills/building-graphql-server/SKILL.mdQuality
Discovery
89%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a solid skill description that clearly identifies its niche (GraphQL servers), provides explicit trigger guidance, and is unlikely to conflict with other skills. Its main weakness is that the capability list could be more comprehensive—'production-ready' is somewhat vague, and additional concrete actions (e.g., authentication, error handling, data loaders) would strengthen specificity.
Suggestions
Expand the concrete actions list beyond 'schema design, resolvers, and subscriptions' to include more specific capabilities like 'type definitions, mutations, data loaders, authentication middleware, and error handling' to improve specificity.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (GraphQL servers) and lists some actions (schema design, resolvers, subscriptions), but 'production-ready' is somewhat vague and the list of concrete actions is not comprehensive—missing things like middleware, authentication, pagination, error handling, etc. | 2 / 3 |
Completeness | Clearly answers both 'what' (build production-ready GraphQL servers with schema design, resolvers, and subscriptions) and 'when' (explicit 'Use when' clause and 'Trigger with phrases like' clause providing concrete trigger guidance). | 3 / 3 |
Trigger Term Quality | Includes natural trigger phrases users would say: 'build GraphQL API', 'create GraphQL server', 'setup GraphQL', plus keywords like 'schemas', 'resolvers', and 'subscriptions'. Good coverage of how users would naturally phrase requests. | 3 / 3 |
Distinctiveness Conflict Risk | GraphQL is a distinct technology niche with specific terminology (schemas, resolvers, subscriptions). Unlikely to conflict with REST API skills or general backend skills due to the explicit GraphQL focus. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
42%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill is well-organized with good progressive disclosure and a clear structure, but critically lacks actionable, executable content. The instructions read as a high-level project plan rather than concrete guidance Claude can follow—there are zero code examples, no commands to run, and no executable snippets. The error handling table is a useful addition, but the overall content would benefit enormously from concrete code examples in the main file.
Suggestions
Add executable code examples for at least the core steps: a minimal schema definition in SDL, a resolver with DataLoader integration, and a subscription setup—these should be copy-paste ready, not prose descriptions.
Include concrete commands for key operations (e.g., `npx graphql-codegen --config codegen.yml`, `npx ts-node src/server.ts`) rather than just describing what tools to use.
Add validation checkpoints in the workflow, such as 'Run `npx graphql-codegen` and verify generated types compile' after schema design, or 'Test with a sample query in GraphiQL before adding authorization'.
Convert the Examples section from prose scenario descriptions into actual code snippets showing a minimal working schema + resolver pair for at least one scenario.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is reasonably structured but includes some unnecessary verbosity—the overview restates what the title already conveys, the prerequisites section explains things Claude would know, and the examples section describes scenarios without providing executable code. Some tightening is possible. | 2 / 3 |
Actionability | Despite listing 9 steps, the instructions are entirely abstract descriptions with no executable code, no concrete commands, and no copy-paste-ready examples. Every step describes what to do conceptually rather than showing how with actual code. The examples section also only provides prose descriptions of scenarios rather than concrete implementations. | 1 / 3 |
Workflow Clarity | The 9 steps provide a reasonable sequence for building a GraphQL server, but there are no validation checkpoints, no feedback loops for error recovery, and no explicit verification steps between stages. For a complex multi-step process involving schema design, code generation, and deployment, the lack of validation gates is a significant gap. | 2 / 3 |
Progressive Disclosure | The skill effectively uses one-level-deep references to external files (implementation.md, errors.md, examples.md) and clearly signals where detailed content lives. The main file serves as an overview with well-organized sections and clear navigation to supplementary materials. | 3 / 3 |
Total | 8 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Commit
3e83543
- 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.