update-api-docs

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

Quality

72%

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 ./.agents/skills/update-api-docs/SKILL.md

Quality

Content

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

The skill body is highly actionable with ready-to-run commands and a helpful file-location table, and it is reasonably concise and well-structured. Its main weakness is workflow clarity: a production-sourced, doc-regenerating batch operation lacks explicit validation checkpoints and has a broken step-numbering sequence.

Suggestions

Add an explicit validation checkpoint after regeneration (e.g., diff the new openapi.json, confirm .api.mdx files were produced, and verify the build) rather than an optional dev-server preview.

Fix the step-numbering sequence, which jumps from 2 to 5 with no steps 3 or 4.

Trim the Overview's restated workflow and consider moving the full docusaurus.config.ts snippet into a referenced file to improve conciseness and progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient with copy-paste commands and a file-location table, but the Overview section restates the workflow steps that are then fully expanded under Steps, a minor redundancy that could be trimmed; fits 'efficient, minor over-explanation'.	4 / 5
Actionability	Concrete executable commands ('pnpm update-api-docs', 'npm run clean-api-docs -- agenta', 'npm run gen-api-docs -- agenta') with variants cover the common cases and are copy-paste ready, matching the top anchor.	5 / 5
Workflow Clarity	Steps are listed but this is a destructive/batch operation (replacing openapi.json from production and regenerating all API docs) whose only verification is an optional dev-server preview, so per the destructive/batch cap workflow clarity cannot exceed 3; step numbering also jumps 1, 2, 5, indicating sequence gaps.	3 / 5
Progressive Disclosure	Content is well organized into clear sections (Overview, File Locations, Steps, Commit Guidelines, Troubleshooting, Related Configuration) with no nested references; the inlined docusaurus.config.ts block is a minor organization gap that keeps it from a 5.	4 / 5
	Total	16 / 20 Passed

Description

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

The description clearly states what the skill does with two concrete actions, but omits any 'when to use it' trigger guidance, which caps both completeness and trigger quality. It is reasonably specific and distinct but would benefit from a Use-when clause.

Suggestions

Add an explicit 'Use when...' clause naming natural triggers (e.g., 'Use when updating the API reference, refreshing the OpenAPI spec, or regenerating Docusaurus API docs').

Include common synonyms users say, such as 'OpenAPI', 'swagger', or 'API reference', to broaden natural keyword coverage.

Mention the file extension or artifact names (e.g., '.api.mdx', 'openapi.json') to improve trigger-term comprehensiveness.

Dimension	Reasoning	Score
Specificity	Quotes 'downloading the latest OpenAPI spec from production and regenerating the Docusaurus API docs' name the domain plus two concrete actions, matching the '1-2 concrete actions but not comprehensive' anchor; not 4 because only two actions are listed.	3 / 5
Completeness	The 'what' is clear (download spec, regenerate docs) but there is no 'Use when...' or equivalent trigger clause, so per the missing-trigger guidance completeness is capped at 3.	3 / 5
Trigger Term Quality	Terms like 'OpenAPI spec', 'API reference documentation', and 'Docusaurus API docs' are relevant but the description lacks natural user-spoken synonyms and variations, fitting 'some relevant keywords but missing common variations'.	3 / 5
Distinctiveness Conflict Risk	The OpenAPI/Docusaurus regeneration niche is mostly distinct with minor overlap risk against closely related docs skills, but the absence of an explicit trigger phrase keeps it from a 5.	4 / 5
	Total	13 / 20 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: .agents/skills/update-api-docs/SKILL.md
Commit: 7a975fb

Reviewed: 3 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.