agent-docs-api-openapi
Agent skill for docs-api-openapi - invoke with $agent-docs-api-openapi
40
7%
Does it follow best practices?
Impact
99%
1.06xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.agents/skills/agent-docs-api-openapi/SKILL.mdQuality
Discovery
0%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 concrete workflow, validation steps, specific examples of good documentation patterns, and any progressive disclosure structure. It reads more like a role description than an actionable skill.
Suggestions
Remove or drastically reduce the YAML frontmatter and focus the body on specific, non-obvious guidance — e.g., patterns for documenting complex auth flows, pagination, or error hierarchies that go beyond what Claude already knows.
Add a clear multi-step workflow with validation: e.g., 1) Analyze existing routes, 2) Generate spec, 3) Validate with a linter command, 4) Fix errors, 5) Verify completeness checklist.
Replace the generic OpenAPI template with concrete before/after examples showing how to transform a poorly documented endpoint into a well-documented one, including specific edge cases.
Add progressive disclosure by splitting advanced topics (security schemes, pagination patterns, error response standards) into referenced files or clearly delineated sections.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The massive YAML frontmatter consumes most of the file with configuration that isn't actionable instruction. The body content explains basic concepts Claude already knows (what OpenAPI is, what 'best practices' are) and lists generic responsibilities rather than providing specific, novel guidance. The template YAML structure is something Claude already knows well. | 1 / 3 |
Actionability | The YAML template provides a concrete starting structure, but it's a basic skeleton Claude could generate from memory. The 'best practices' and 'documentation elements' sections are bullet-point lists of vague directives ('Use descriptive summaries', 'Include example requests') rather than specific, executable instructions with concrete examples of good vs bad documentation. | 2 / 3 |
Workflow Clarity | There is no clear multi-step workflow for creating or updating API documentation. The 'key responsibilities' are listed without sequencing. There are no validation checkpoints (e.g., validating the generated OpenAPI spec against the schema), no error recovery steps, and no feedback loops for ensuring correctness of the generated documentation. | 1 / 3 |
Progressive Disclosure | The content is a monolithic file with no references to supporting documents. The enormous YAML frontmatter and the body content are all in one place with no clear navigation structure. There are no links to detailed guides for complex topics like security schemes, schema design patterns, or advanced OpenAPI features. | 1 / 3 |
Total | 5 / 12 Passed |
Validation
100%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
9d4a9ea
- Reviewed
Table of Contents
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.