agent-docs-api-openapi
Agent skill for docs-api-openapi - invoke with $agent-docs-api-openapi
43
11%
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 essentially only provides an invocation command and a skill identifier name. It completely lacks any explanation of what the skill does, what actions it performs, or when it should be selected. It would be nearly impossible for Claude to correctly choose this skill from a list of available skills.
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 as it wastes space that should be used for capability and trigger information.
| 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 | The description fails to answer both 'what does this do' and 'when should Claude use it'. It only provides an invocation command, with no explanation of capabilities or usage triggers. | 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 specific domain, the description is so vague that it provides no meaningful differentiation. It could conflict with any API, documentation, or OpenAPI-related skill. | 1 / 3 |
Total | 4 / 12 Passed |
Implementation
22%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is heavily bloated by an extensive YAML frontmatter block that contains non-actionable configuration metadata. The body content consists mostly of generic best practices Claude already knows and a basic OpenAPI template skeleton. It lacks a clear workflow with validation steps, concrete examples of documenting real endpoints, and any progressive disclosure to deeper reference materials.
Suggestions
Remove or drastically reduce the YAML frontmatter metadata that doesn't serve as actionable instruction (hooks, optimization, triggers, etc.) and focus the body on concrete guidance.
Add a step-by-step workflow for creating API documentation: e.g., 1) Scan route files, 2) Extract endpoints, 3) Generate spec, 4) Validate with a linter, 5) Fix errors and re-validate.
Replace generic best-practice bullets with specific, executable examples showing how to document a realistic endpoint including error responses, auth headers, and schema references.
Add validation/verification steps such as using an OpenAPI linter to check the generated spec before considering the task complete.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is dominated by an enormous YAML frontmatter block (triggers, hooks, constraints, optimization settings, etc.) that is not actionable instruction content. The actual body is padded with generic best practices Claude already knows ('Use descriptive summaries', 'Follow OpenAPI 3.0 specification strictly') and explains basic concepts rather than providing novel, specific guidance. | 1 / 3 |
Actionability | The YAML template provides a concrete starting structure for an OpenAPI spec, which is somewhat useful. However, the guidance is mostly generic best-practice bullet points rather than executable, copy-paste-ready instructions for specific documentation tasks. The template is a basic skeleton rather than a worked example with realistic content. | 2 / 3 |
Workflow Clarity | The 'Key responsibilities' list describes what to do but not how or in what order. There is no sequenced workflow for creating or updating API documentation, no validation steps (e.g., linting the OpenAPI spec), and no feedback loops for catching errors in the generated YAML. | 1 / 3 |
Progressive Disclosure | The content has some section structure (responsibilities, best practices, structure, elements), but it's a flat list without references to deeper materials. The massive frontmatter clutters the file. The 'Documentation elements' section at the end is just a bullet list with no elaboration or links to detailed guides. | 2 / 3 |
Total | 6 / 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/ruflo
- Commit
398f7c2
- 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.