route-to-openapi

Generates RESTful API documentation (OpenAPI 3.0 / Swagger spec) by scanning route definitions in code for Flask, FastAPI, Express, Gin, and other frameworks. Trigger when users ask about API documentation, OpenAPI, Swagger, endpoint docs, generating docs from code, or extracting endpoints.

Quality

93%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

87%

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

The content is concise, actionable, and well-structured with a clean single-script bundle reference. Its only weakness is workflow clarity: the batch generation process provides no validation or verification step for the produced spec.

Suggestions

Add a verification checkpoint after generation, e.g. validate the output with a spec validator or confirm it loads in Swagger UI/Redoc, to satisfy the batch-operation feedback-loop expectation.

Show how to handle detection failures (e.g., unsupported framework or no routes found) so Claude knows what to do when auto-detection yields nothing.

Note a fallback or manual review step when the generated spec is incomplete (missing request bodies or response models), guiding Claude to prompt the user for clarification.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence: no basic-concept explanations, dense reference tables, and copy-paste Quick Start commands, with every section earning its place.	3 / 3
Actionability	Provides fully executable commands (e.g., 'python scripts/generate_api_doc.py ./src --format yaml --output api-spec.yaml') with a concrete parameters table and a realistic output example, all copy-paste ready.	3 / 3
Workflow Clarity	The single-action workflow is unambiguous, but this batch operation (scanning a source directory, writing a spec file) lacks any validation/verification checkpoint for the generated output, which caps the score per the batch-operation guideline.	2 / 3
Progressive Disclosure	Well-organized into clear sections with a single one-level-deep bundle reference (scripts/generate_api_doc.py, verified to exist) that is cleanly signaled in the Quick Start; no deeply nested references.	3 / 3
	Total	11 / 12 Passed

Description

100%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is concise, specific, and complete: it states concrete actions, names supported frameworks, and provides an explicit trigger clause covering natural user phrasings. It clearly occupies a distinct niche with low conflict risk.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions ('Generates RESTful API documentation', 'scanning route definitions in code') and enumerates specific frameworks (Flask, FastAPI, Express, Gin), matching the highest anchor.	3 / 3
Completeness	Clearly answers both 'what' (generates OpenAPI specs by scanning route definitions) and 'when' (explicit 'Trigger when users ask about...' guidance), satisfying the highest anchor.	3 / 3
Trigger Term Quality	An explicit 'Trigger when users ask about API documentation, OpenAPI, Swagger, endpoint docs, generating docs from code, or extracting endpoints' clause provides broad coverage of natural terms users would say.	3 / 3
Distinctiveness Conflict Risk	Targets a clear niche (OpenAPI generation from framework route definitions) with distinct triggers unlikely to fire for unrelated skills.	3 / 3
	Total	12 / 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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: zebbern/claude-code-guide
Path: skills/route-to-openapi/SKILL.md
Commit: af7d491

Reviewed: about 8 hours 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.