agent-docs-api-openapi
Agent skill for docs-api-openapi - invoke with $agent-docs-api-openapi
Install with Tessl CLI
npx tessl i github:ruvnet/claude-flow --skill agent-docs-api-openapi35
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
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 critically deficient across all dimensions. It functions more as a label than a description, providing only a name and invocation command without any information about capabilities, use cases, or trigger conditions. Claude would have no basis for selecting this skill appropriately from a list of available skills.
Suggestions
Add concrete actions describing what the skill does (e.g., 'Generates API documentation from OpenAPI/Swagger specifications, validates schemas, and creates client examples').
Include a 'Use when...' clause with natural trigger terms (e.g., 'Use when the user mentions OpenAPI, Swagger, API docs, REST API documentation, or .yaml/.json API specs').
Remove the invocation syntax from the description and replace with functional content that helps Claude understand when to select this skill.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description contains no concrete actions whatsoever. 'Agent skill for docs-api-openapi' is completely abstract and doesn't describe what the skill actually does. | 1 / 3 |
Completeness | Missing both 'what does this do' and 'when should Claude use it'. The description only provides an invocation command, not any functional information or usage guidance. | 1 / 3 |
Trigger Term Quality | Contains only technical jargon ('docs-api-openapi', '$agent-docs-api-openapi') that users would not naturally say. No natural keywords like 'API documentation', 'OpenAPI spec', or 'swagger' are present. | 1 / 3 |
Distinctiveness Conflict Risk | While the name 'docs-api-openapi' hints at a specific domain, the description is so vague it provides no clear niche. Without knowing what it does, it's impossible to distinguish from other API or documentation skills. | 1 / 3 |
Total | 4 / 12 Passed |
Implementation
37%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill provides a basic OpenAPI template and lists best practices, but lacks actionable workflows for actually creating documentation from existing code. It describes what good API docs should contain rather than providing concrete steps and validation checkpoints for producing them. The extensive YAML frontmatter consumes significant tokens without adding instructional value to the body content.
Suggestions
Add a clear step-by-step workflow: 1) Analyze existing routes, 2) Extract endpoint signatures, 3) Generate OpenAPI spec, 4) Validate with a linter, 5) Fix errors and re-validate
Include concrete examples showing how to document a specific endpoint type (e.g., CRUD operations) with copy-paste ready YAML snippets
Add validation checkpoint: specify how to validate the generated OpenAPI spec (e.g., using swagger-cli or openapi-generator validate)
Remove the 'Key responsibilities' section - Claude knows what API documentation involves; replace with specific patterns for common documentation challenges
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content includes some unnecessary explanation (e.g., 'You are an OpenAPI Documentation Specialist') and the 'Key responsibilities' section states obvious tasks Claude already knows. The YAML structure example is useful but could be more compact. | 2 / 3 |
Actionability | Provides a concrete OpenAPI structure example which is helpful, but the guidance is mostly descriptive ('use descriptive summaries', 'include example requests') rather than showing specific executable patterns or copy-paste ready templates for common scenarios. | 2 / 3 |
Workflow Clarity | No clear workflow sequence for creating or updating API documentation. Missing validation steps for OpenAPI spec correctness, no feedback loops for error recovery, and no explicit process for analyzing existing code to generate documentation. | 1 / 3 |
Progressive Disclosure | Content is reasonably organized with sections, but everything is inline in a single file. For a documentation skill of this scope, references to separate files for schema examples, common patterns, or validation procedures would improve navigation. | 2 / 3 |
Total | 7 / 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.
- 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.