CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

webiny-api-architect

The hub skill for all API/backend architecture in Webiny. Covers architecture overview, Services vs UseCases, feature naming and organization, feature structure templates, DI decision tree, anti-patterns, createFeature, createAbstraction, container registration, domain errors, entity and value object patterns, naming conventions, scoping rules, and code conventions. Use this skill for ANY backend API work — it references sub-skills for deep implementation details.

Quality

79%

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/user-skills/api/api-architect/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

71%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.

An unusually actionable reference skill: complete executable code, decision tables, templates, and a checklist cover the common cases thoroughly. The weaknesses are token efficiency (key rules repeated 3-5 times across sections) and progressive disclosure (an ~800-line monolith that inlines the deep implementation detail its own description delegates to sub-skills, with no bundle files).

Suggestions

State the "domain values are value objects, not helper functions" rule once authoritatively (e.g., in the Value Objects section) and reference it from Anti-Patterns, Code Conventions, the Checklist, and Key Rules instead of restating it in each place.

Move deep implementation detail — the full ServiceProvider implementation and the three value-object code examples — into the referenced sub-skills (webiny-use-case-pattern, webiny-full-stack-architect) and keep one-line summaries with inline pointers, matching the description's promise to defer deep details to sub-skills.

Consolidate duplicated guidance: scoping rules appear in Services vs UseCases, the Scoping Rules table, and Key Rules; the no-process.env rule appears in Reading API BuildParams and Key Rules — keep one canonical section each.

DimensionReasoningScore

Conciseness

Nearly all content is project-specific and non-inferable (createFeature/createAbstraction/DI conventions), with no padding explaining concepts Claude already knows, but the same rules are repeated multiple times: the "value objects, not helper functions" rule appears five times (Anti-Patterns, Value Objects RULE, Code Conventions, Checklist, Key Rules), scoping rules three times, and ServiceProvider and no-process.env guidance twice each. This fits "Mostly efficient but includes some unnecessary explanation or could be tightened" rather than 2, since the redundancy is deliberate emphasis of non-obvious project rules rather than explanation of known concepts.

3 / 5

Actionability

The body provides complete, copy-paste-ready TypeScript for the common cases: abstraction definitions with namespaces, feature.ts registration, the Extension.ts entry point, domain errors with codes, typed error unions, value objects, index.ts exports, and BuildParams injection, plus a DI decision table, directory templates, and a 13-item checklist. This matches "Fully executable; copy-paste ready code or commands; specific examples cover the common cases"; the few ellipsis fragments appear only in intentional WRONG/CORRECT anti-pattern contrasts, and GraphQL schema code is appropriately delegated to a named sub-skill.

5 / 5

Workflow Clarity

Sequence and checkpoints are explicit: ordering rules ("Register the CMS model first", "Register features with Feature.register(container)"), a DI decision tree, When-keyed feature templates, and a 13-item build checklist acting as verification checkpoints. It falls short of anchor 5 because there is no explicit verification step (e.g., building or testing that the feature loads) and no error-recovery feedback loop, but this is a reference/pattern skill, not a destructive or batch operation, so no cap applies.

4 / 5

Progressive Disclosure

No bundle files exist (no references/, scripts/, or assets/), and the body is a single ~800-line file that inlines deep implementation detail — the full ServiceProvider implementation and three complete value-object code examples — despite the description stating sub-skills hold "deep implementation details". Section structure is strong (clear headers, TL;DR, tables, intra-document anchors) so it is above anchor 2, but sub-skill references are only two parenthetical notes plus an end-of-file Related Skills list rather than clearly signaled pointers where the deep detail lives, fitting anchor 3 ("content that should be separate is inline").

3 / 5

Total

15

/

20

Passed

Description

80%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 strong description that is specific, domain-bound, and explicitly states both what it covers and when to use it. Its main weaknesses are a broad rather than trigger-phrase-specific "when" clause and a few missing natural keywords (GraphQL, CMS, extension).

DimensionReasoningScore

Specificity

The description enumerates fourteen concrete, domain-specific topics ("Services vs UseCases, feature naming and organization, feature structure templates, DI decision tree, anti-patterns, createFeature, createAbstraction, container registration, domain errors, entity and value object patterns"), giving comprehensive coverage of the skill's scope. This matches the anchor "Lists multiple specific concrete actions; comprehensive coverage" rather than 4, since no meaningful coverage gaps are apparent.

5 / 5

Completeness

Both parts are explicitly present: the "what" is the detailed topic list ("Covers architecture overview, Services vs UseCases, ..."), and the "when" is "Use this skill for ANY backend API work". However, the when-clause is broad rather than concrete trigger phrases (e.g., "when creating an API extension or adding a GraphQL mutation"), matching anchor 4 ("'when' could be more explicit or specific") rather than anchor 5.

4 / 5

Trigger Term Quality

Terms like "API/backend architecture", "Webiny", "backend API work", "Services vs UseCases", and "DI decision tree" align well with what a user doing Webiny backend work would naturally say. A few natural terms are missing (e.g., GraphQL, CMS, extension, endpoint), so it falls short of the anchor-5 standard of comprehensive coverage including synonyms and extensions.

4 / 5

Distinctiveness Conflict Risk

"The hub skill for all API/backend architecture in Webiny" carves out a clear niche with minimal conflict risk against unrelated skills. The deliberate broad trigger "ANY backend API work" plus the hub-over-sub-skills design creates minor overlap risk with closely related skills in the same family (webiny-use-case-pattern, webiny-api-permissions), fitting anchor 4 rather than 5.

4 / 5

Total

17

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

skill_md_line_count

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

Warning

Total

15

/

16

Passed

Repository

webiny/webiny-js

Path

skills/user-skills/api/api-architect/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.