api

Add or modify API endpoints using TypeSpec. Use when adding new API routes, modifying request/response types, or changing the OpenAPI spec.

Quality

78%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/api/SKILL.md

Quality

Content

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

A thorough, well-organized skill body that provides concrete executable guidance and a clear sequenced workflow grounded in OpenMeter-specific conventions. The main weaknesses are placeholder-templated code rather than a fully worked concrete example and the absence of an explicit error-recovery feedback loop in the workflow.

Suggestions

Add an explicit fix-and-retry feedback loop after `make gen-api`/`make generate` (e.g. 'if generation fails, fix the TypeSpec and re-run until it completes clean') to lift workflow clarity.

Include one fully-worked concrete handler example with real names (e.g. a complete `meters` domain) instead of only `<Resource>`/`<domain>` placeholder templates, so the guidance is copy-paste ready.

Bundle the referenced `rules/*.md` files alongside the skill (or note they live in-repo) so the one-level-deep references in the rule index can be verified as real files.

Dimension	Reasoning	Score
Conciseness	The body is dense with project-specific knowledge Claude would not know (Konnect drift rules, wrapper conventions, error-mapping tables) with no basic-concept padding, but the inline List handler template is long; minor trimming possible, so it sits just below the every-token-earns-its-place anchor at 5.	4 / 5
Actionability	Concrete commands ("make gen-api", "make generate") and full Go templates cover common cases, but the `<Resource>`/`<domain>` placeholders require substitution rather than being copy-paste ready, keeping it below the fully-executable anchor at 5.	4 / 5
Workflow Clarity	A clear five-step sequence with real checkpoints (diff openmeter.tsp konnect.tsp, "Check that it completes without errors", Step 5 review) is present, but there is no explicit fix-and-retry feedback loop for generation or handler failures, so it does not reach the error-recovery anchor at 5.	4 / 5
Progressive Disclosure	The rule index table provides well-signaled one-level-deep references and sectioning is clean, but the referenced `rules/` directory is not present in the bundle to verify and the large handler code template is inlined rather than split out, leaving minor organization gaps below the top anchor.	4 / 5
	Total	16 / 20 Passed

Description

82%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, well-structured description that clearly states both capability and trigger conditions in third person with concrete natural keywords. The only gap is a slightly thin action list and the absence of the .tsp file extension as a trigger term.

Dimension	Reasoning	Score
Specificity	Quotes "Add or modify API endpoints using TypeSpec" — names the domain plus two concrete actions (add, modify), but does not enumerate a comprehensive set of operations, matching the 1-2-actions anchor rather than the several-actions anchor at 4.	3 / 5
Completeness	Explicitly answers both what ("Add or modify API endpoints using TypeSpec") and when ("Use when adding new API routes, modifying request/response types, or changing the OpenAPI spec") with concrete trigger phrases, matching the top anchor.	5 / 5
Trigger Term Quality	Natural terms "API endpoints", "API routes", "request/response types", "OpenAPI spec" give good coverage with synonyms (endpoints/routes), but no file extension like ".tsp" is present, leaving it just short of the comprehensive-synonym-plus-extension anchor at 5.	4 / 5
Distinctiveness Conflict Risk	The TypeSpec/OpenMeter API niche with distinct triggers ("API routes", "OpenAPI spec") is clearly distinguishable from other skills with minimal overlap risk, matching the clear-niche anchor.	5 / 5
	Total	17 / 20 Passed

Validation

87%

Warnings & errors only

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

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
relative_links	Relative link issues: 2 missing	Warning

	Total	14 / 16 Passed

Repository: openmeterio/openmeter
Path: .agents/skills/api/SKILL.md
Commit: 03a90ec

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

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.