update-api-docs

Update the API reference documentation by downloading the latest OpenAPI spec from production and regenerating the Docusaurus API docs

Quality

70%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/update-api-docs/SKILL.md

Quality

Content

72%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A highly actionable, well-organized skill body with concrete commands and paths. Its main weaknesses are a broken step numbering sequence, an optional rather than enforced verification step, and a slightly heavy inline config block.

Suggestions

Fix the step numbering (it jumps from 2 to 5) so the sequence is unbroken.

Make the verification step a required checkpoint after regeneration rather than an optional preview.

Consider moving the full Docusaurus config block into a referenced file or trimming it to the essential fields.

Dimension	Reasoning	Score
Conciseness	The body is mostly lean and action-oriented, but the inline "Related Configuration" block and some redundancy in commit/troubleshooting sections could be tightened to save tokens.	2 / 3
Actionability	It gives copy-paste-ready commands (pnpm update-api-docs, npm run clean-api-docs -- agenta) and exact file paths, leaving no ambiguity about what to run.	3 / 3
Workflow Clarity	Steps are listed but numbering jumps from 2 to 5, and the verification step is optional rather than a real checkpoint for this batch regeneration, leaving a validation gap.	2 / 3
Progressive Disclosure	No bundle files exist, and the single self-contained SKILL.md is organized into clear sections (Overview, File Locations, Steps, Troubleshooting, Related Configuration) with easy navigation.	3 / 3
	Total	10 / 12 Passed

Description

67%

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 specific, distinct description that names concrete actions in a clear niche, but it omits explicit "when to use" trigger guidance and relies on somewhat technical terms. Adding a Use-when clause with natural phrasing would lift the weaker dimensions.

Suggestions

Append an explicit trigger clause, e.g. "Use when updating or regenerating the API docs from the OpenAPI spec."

Include natural user phrasings such as "refresh the API docs" or "update API reference" alongside the technical terms.

Keep the concrete actions but lead with the user-facing outcome ("Update the API docs") before the implementation detail.

Dimension	Reasoning	Score
Specificity	The description lists multiple concrete actions — "downloading the latest OpenAPI spec from production" and "regenerating the Docusaurus API docs" — tied to a specific domain (API reference documentation).	3 / 3
Completeness	It clearly answers what the skill does, but lacks any "Use when..." or equivalent explicit trigger guidance, which caps completeness at 2 per the rubric.	2 / 3
Trigger Term Quality	It surfaces relevant terms like "API reference documentation", "OpenAPI spec", and "Docusaurus API docs", but leans technical and omits common natural variations (e.g. "update/refresh the API docs").	2 / 3
Distinctiveness Conflict Risk	The OpenAPI-spec-to-Docusaurus regeneration niche is narrow and distinct, making it unlikely to trigger for unrelated skills.	3 / 3
	Total	10 / 12 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: Agenta-AI/agenta
Path: .claude/skills/update-api-docs/SKILL.md
Commit: 93872a6

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.