Name: agent-docs-api-openapi
Rating: 38.4 (1 reviews)
Author: ruvnet

Blog Docs Log in Get started

agent-docs-api-openapi

Agent skill for docs-api-openapi - invoke with $agent-docs-api-openapi

Quality

35%

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/agent-docs-api-openapi/SKILL.md

The canonical home for this skill is agent-docs-api-openapi in ruvnet/claude-flow

Quality

Content

42%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 body pairs a sizeable inlined legacy config block (token waste) with a compact but largely abstract instructional section. Its one concrete artifact, the OpenAPI template, is syntactically broken, and no validation workflow is given for spec authoring.

Suggestions

Move the legacy agent-definition YAML into a separate bundled file (or delete it) and keep SKILL.md as a lean overview, fixing the template syntax ('https://', '/endpoint', 'application/json') so it is copy-paste executable.

Add a short sequenced workflow with a validation checkpoint, e.g. '1. Gather endpoints 2. Draft spec 3. Validate with a linter 4. Only then write openapi.yaml'.

Trim generic best-practice lines Claude already knows and keep only non-obvious guidance (e.g., project-specific $ref conventions or required tags).

Dimension	Reasoning	Score
Conciseness	The ~115-line inlined legacy agent-definition YAML is heavy padding Claude does not need to execute the task, and several best-practice lines ('Use descriptive summaries', 'Follow OpenAPI 3.0 specification strictly') restate what Claude already knows — noticeably verbose with padded sections.	2 / 5
Actionability	A concrete OpenAPI structure template is provided, but it contains broken syntax ('https:/$api.example.com', '$endpoint', 'application$json') so it is not copy-paste executable, and the surrounding guidance is abstract directives — some concrete guidance but incomplete.	3 / 5
Workflow Clarity	The numbered responsibilities read as parallel aspects rather than a sequenced process, and there is no validation/verification step (e.g., linting the spec); spec authoring can overwrite existing files, so the missing-validation cap of 3 applies.	3 / 5
Progressive Disclosure	No bundle files exist and the instructional content is sectioned with headers, but the large legacy YAML config block is inlined material that belongs in a separate file — some structure with content-that-could-be-separate kept inline.	3 / 5
	Total	11 / 20 Passed

Description

28%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 is a bare label plus invocation syntax: it names the OpenAPI-docs niche but conveys no concrete capabilities, no natural trigger phrases, and no 'use when' guidance. It is distinguishable only by its domain name, not by articulated triggers.

Suggestions

Replace the label with concrete actions, e.g. 'Creates and maintains OpenAPI 3.0/Swagger specifications for REST APIs'.

Add an explicit trigger clause: 'Use when the user asks to create, update, or validate OpenAPI/Swagger docs, or mentions endpoints, schemas, or .yaml/.json API specs'.

Drop the 'invoke with $agent-docs-api-openapi' invocation instruction from the description — it is a mechanism, not a capability or use condition.

Dimension	Reasoning	Score
Specificity	The description names a domain ('docs-api-openapi') but states no concrete action — only 'Agent skill for docs-api-openapi' plus an invocation instruction — fitting 'names the domain but actions are minimal or generic' rather than the entirely-vague anchor 1.	2 / 5
Completeness	It offers only a vague 'what' ('Agent skill for docs-api-openapi') and no real 'when' — 'invoke with $agent-docs-api-openapi' is a mechanism, not a use condition — matching the anchor for 'vague what and no when' rather than anchor 1's total absence.	2 / 5
Trigger Term Quality	It exposes the technical identifier 'docs-api-openapi'/'$agent-docs-api-openapi' and 'invoke'; the words 'openapi'/'api'/'docs' are semi-natural, but there are no natural trigger phrases a user would actually say, so it sits between 'no natural keywords' and 'one or two generic keywords'.	2 / 5
Distinctiveness Conflict Risk	OpenAPI documentation is a reasonably distinct niche, but the bare description provides no distinct trigger phrases and could still overlap with generic API/docs skills, fitting 'somewhat specific but could still overlap with similar skills'.	3 / 5
	Total	9 / 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: ruvnet/ruflo
Path: .agents/skills/agent-docs-api-openapi/SKILL.md
Commit: fa13ee4

Reviewed: about 8 hours 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.