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 fails on every dimension. It provides no information about what the skill does, when it should be used, or what user requests should trigger it. It reads as a placeholder rather than a functional description.

Suggestions

Add concrete actions the skill performs, e.g., 'Generates, validates, and queries OpenAPI/Swagger specifications for API documentation.'

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

Remove the invocation instruction ('invoke with $agent-docs-api-openapi') from the description, as it wastes space that should be used for capability and trigger information.

Dimension	Reasoning	Score
Specificity	The description provides 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, with no functional or contextual information.	1 / 3
Trigger Term Quality	The only terms present are 'docs-api-openapi' and the invocation command, which are technical jargon rather than natural keywords a user would say. No natural trigger terms like 'API documentation', 'OpenAPI spec', or 'swagger' are included.	1 / 3
Distinctiveness Conflict Risk	The description is so vague that it's impossible to distinguish it from any other API or documentation-related skill. There are no distinct triggers or clear niche defined.	1 / 3
	Total	4 / 12 Passed

Implementation

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

This skill is almost entirely YAML frontmatter configuration with very little actionable instructional content. The body consists of generic best practices and a basic OpenAPI template that Claude already knows, providing no novel or specific guidance. It lacks concrete workflows, validation steps, executable examples, and any meaningful structure for progressive disclosure.

Suggestions

Remove or drastically reduce the YAML frontmatter and replace the body with a concrete, step-by-step workflow: 1) Discover API routes using Grep/Glob, 2) Extract endpoint signatures, 3) Generate OpenAPI spec, 4) Validate the output.

Add specific, executable examples showing how to use the allowed tools (Read, Grep, Glob) to analyze source code and extract API endpoint information, rather than listing generic OpenAPI best practices.

Include validation checkpoints - e.g., after generating the spec, verify required fields are present, check that all referenced schemas exist in components, and validate YAML syntax.

Replace the generic OpenAPI template with project-specific patterns or examples that demonstrate non-obvious conventions, edge cases, or organization-specific requirements that Claude wouldn't already know.

Dimension	Reasoning	Score
Conciseness	The vast majority of the file is YAML frontmatter configuration that provides no actionable value to Claude (triggers, hooks, optimization settings, communication style, etc.). The actual body content explains basic concepts Claude already knows (what OpenAPI is, generic best practices like 'use descriptive summaries') and the YAML example is a generic template that adds little beyond what Claude already understands about OpenAPI 3.0.	1 / 3
Actionability	The content provides only vague, high-level guidance ('Document all endpoints with descriptions and examples', 'Use $ref for reusable components') without concrete, executable steps. The YAML template is a generic skeleton rather than a specific, actionable workflow. There are no concrete commands, no specific tools usage patterns, and no real examples of how to analyze existing code and produce documentation.	1 / 3
Workflow Clarity	There is no clear multi-step workflow for actually creating API documentation. The content lists responsibilities and best practices as bullet points but never sequences them into a process. There are no validation steps (e.g., validating the generated OpenAPI spec), no error recovery guidance, and no checkpoints despite this being a task that involves analyzing code and producing structured output.	1 / 3
Progressive Disclosure	The content is a monolithic block with no references to supporting files and no bundle files exist. The massive YAML frontmatter dominates the file while the actual instructional content is thin and poorly organized. There's no separation between quick-start guidance and advanced topics, and no external references for detailed schema patterns or complex examples.	1 / 3
	Total	4 / 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/claude-flow
Commit: 2b9e2de

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.