agent-docs-api-openapi
Agent skill for docs-api-openapi - invoke with $agent-docs-api-openapi
35
0%
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 description is essentially a label and invocation command with no substantive content. It fails on every dimension: it does not describe what the skill does, when to use it, or provide any natural trigger terms. It would be nearly impossible for Claude to correctly select this skill from a pool of available skills.
Suggestions
Add concrete actions describing what this skill does (e.g., 'Queries the docs API OpenAPI specification to retrieve endpoint definitions, parameter schemas, and response formats').
Add an explicit 'Use when...' clause with natural trigger terms (e.g., 'Use when the user asks about API documentation, endpoint specs, OpenAPI schemas, or needs to look up API reference details').
Include common user-facing keywords and file types (e.g., 'OpenAPI spec', 'Swagger', 'API docs', 'REST endpoints', '.yaml', '.json') to improve trigger term coverage.
| 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', and 'openapi', but these are embedded in a hyphenated identifier rather than presented as natural keywords a user would say. There are no natural trigger terms. | 1 / 3 |
Distinctiveness Conflict Risk | The description is so vague that it could overlap with any API documentation, OpenAPI spec, or docs-related skill. There is nothing to distinguish it from other similar tools. | 1 / 3 |
Total | 4 / 12 Passed |
Implementation
0%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 body content. The actual instructions consist of generic best practices and a basic OpenAPI template that Claude already knows. It lacks concrete workflows, validation steps, executable examples, and any meaningful progressive disclosure structure.
Suggestions
Remove or drastically reduce the YAML frontmatter and focus the body on actionable, step-by-step workflows for common tasks (e.g., 'Given a set of route files, generate an OpenAPI spec by: 1. Scan routes, 2. Extract parameters, 3. Build spec, 4. Validate with...').
Add concrete, executable examples showing how to analyze source code and produce specific OpenAPI output, rather than a generic template skeleton.
Include explicit validation steps (e.g., using a spec validator tool or manual checks) with error recovery guidance to ensure generated specs are valid OpenAPI 3.0.
Move the OpenAPI template and any reference material to a separate file and link to it from a concise overview in the main skill body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is dominated by an enormous YAML frontmatter block (triggers, hooks, metadata, integration, optimization, etc.) that provides no actionable value to Claude. The actual body content explains basic concepts Claude already knows (what OpenAPI is, basic YAML structure) and lists generic best practices that are common knowledge. | 1 / 3 |
Actionability | The body provides only a generic OpenAPI template skeleton and vague best practices like 'use descriptive summaries' and 'include example requests and responses.' There are no concrete, executable workflows—no specific commands, no real examples of transforming source code into OpenAPI specs, and no copy-paste-ready patterns for common documentation tasks. | 1 / 3 |
Workflow Clarity | There is no clear multi-step workflow for creating or updating API documentation. The 'key responsibilities' are a list of goals, not sequenced steps. There are no validation checkpoints (e.g., validating the generated spec with a linter), no error recovery guidance, and no feedback loops. | 1 / 3 |
Progressive Disclosure | The content is a monolithic block mixing a massive frontmatter with a shallow body. There are no references to external files for advanced topics, no navigation structure, and the inline OpenAPI template could be a separate reference file. The frontmatter itself contains shell scripts in hooks that are not referenced or organized meaningfully. | 1 / 3 |
Total | 4 / 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
f547cec
- 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.