agent-docs-api-openapi

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

1.06x

Quality

Does it follow best practices?

Impact

99%

1.06x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.agents/skills/agent-docs-api-openapi/SKILL.md

Quality

Discovery

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This is an extremely weak description that provides virtually no useful information for skill selection. It reads as a boilerplate invocation instruction rather than a functional description. It fails on every dimension by not describing capabilities, triggers, or use cases.

Suggestions

Add concrete actions describing what the skill does, e.g., 'Generates, validates, and transforms OpenAPI/Swagger specification files for API documentation.'

Add an explicit 'Use when...' clause with natural trigger terms, e.g., 'Use when the user asks about OpenAPI specs, Swagger files, API documentation, REST API schemas, or .yaml/.json API definitions.'

Remove the invocation instruction ('invoke with $agent-docs-api-openapi') from the description and replace it with functional content that helps Claude decide when to select this skill.

Dimension	Reasoning	Score
Specificity	The description contains no concrete actions whatsoever. 'Agent skill for docs-api-openapi' is entirely vague and does not describe what the skill actually does.	1 / 3
Completeness	Neither 'what does this do' nor 'when should Claude use it' is answered. The description only states it's an 'agent skill' and how to invoke it, providing no functional or contextual information.	1 / 3
Trigger Term Quality	The only potentially relevant terms are 'docs-api-openapi' which is a technical identifier, not a natural keyword a user would say. There are no natural trigger terms like 'API documentation', 'OpenAPI spec', 'swagger', etc.	1 / 3
Distinctiveness Conflict Risk	While the name 'docs-api-openapi' hints at a niche, the description itself is so vague that Claude cannot distinguish when to use it versus any other docs or API-related skill.	1 / 3
	Total	4 / 12 Passed

Implementation

14%

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

This skill is dominated by an extremely verbose YAML frontmatter that provides no actionable value to Claude, while the actual body content consists of generic best practices and a basic OpenAPI template that Claude already knows. The skill lacks a clear workflow, validation steps, and any progressive disclosure structure. It reads more like a role description than an actionable skill.

Suggestions

Remove or drastically reduce the YAML frontmatter metadata (triggers, hooks, optimization, communication settings) which consume tokens without adding actionable guidance.

Replace the generic 'best practices' list with a concrete step-by-step workflow: e.g., 1) Scan route files, 2) Extract endpoints, 3) Generate spec, 4) Validate with a linter, 5) Fix errors and re-validate.

Add validation checkpoints such as using `swagger-cli validate openapi.yaml` or equivalent to verify generated specs, with error recovery instructions.

Include a realistic, complete example showing how to document a specific endpoint (e.g., a POST /users endpoint with request body, validation errors, auth headers) rather than a minimal skeleton template.

Dimension	Reasoning	Score
Conciseness	The content is heavily padded with verbose YAML frontmatter that serves no actionable purpose for Claude (triggers, hooks, optimization settings, communication style, etc.). The actual body content explains basic concepts Claude already knows (what OpenAPI is, basic best practices like 'use descriptive summaries') and the YAML example is a generic template that adds little value.	1 / 3
Actionability	The YAML template provides a semi-concrete starting point, but the guidance is mostly generic best practices rather than specific, executable instructions. The 'best practices' and 'key responsibilities' sections describe rather than instruct, and the example is a bare skeleton without enough detail to be truly copy-paste ready for real API documentation tasks.	2 / 3
Workflow Clarity	There is no clear multi-step workflow for creating or updating API documentation. The 'key responsibilities' list tasks but doesn't sequence them. There are no validation checkpoints (e.g., validating the generated OpenAPI spec against the specification), no error recovery steps, and no feedback loops for ensuring correctness.	1 / 3
Progressive Disclosure	The content is a monolithic block mixing metadata, responsibilities, best practices, and a template all in one file with no references to external resources. There's no separation of quick-start vs. advanced content, and no links to detailed guides for specific topics like security schemes or complex schema definitions.	1 / 3
	Total	5 / 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: ruvnet/ruflo
Commit: ccb062f

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.