sync-openapi
Sync, update, and validate the OpenAPI specification (backend/openapi.yml) against the Flask API routes. Use whenever endpoints have been added, changed, or removed, or when the user mentions API docs, swagger, OpenAPI, endpoint documentation, "update the spec", or has just added/modified a route or resource class. Also use when checking for drift between the code and the spec.
71
88%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
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.
This is an excellent skill description that clearly defines its purpose, provides comprehensive trigger terms, and explicitly states both what it does and when to use it. The inclusion of the specific file path (backend/openapi.yml) and technology stack (Flask) adds precision, and the variety of natural trigger terms ensures reliable skill selection.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Sync, update, and validate the OpenAPI specification' against Flask API routes, with the specific file path (backend/openapi.yml) included. | 3 / 3 |
Completeness | Clearly answers both what ('Sync, update, and validate the OpenAPI specification against Flask API routes') and when ('Use whenever endpoints have been added, changed, or removed, or when the user mentions API docs, swagger, OpenAPI...') with explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms users would say: 'API docs', 'swagger', 'OpenAPI', 'endpoint documentation', 'update the spec', 'added/modified a route or resource class', 'drift between the code and the spec'. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with a clear niche: OpenAPI spec synchronization for a specific Flask backend file. The combination of OpenAPI/swagger terminology with Flask routes makes it unlikely to conflict with other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, project-specific skill that provides clear, actionable guidance for syncing an OpenAPI spec with Flask routes. Its main strengths are the well-defined scoping mechanism ($ARGUMENTS interpretation), concrete file paths and commands, and a clear validation feedback loop. Minor weaknesses include some verbosity in explaining code-reading steps that Claude could handle implicitly, and the content could benefit from splitting detailed reference material into separate files.
Suggestions
Consider trimming the 5-step 'How to Sync an Endpoint' section — steps like 'Read the Route Definition' and 'Find the View Function' could be condensed since Claude can navigate code files without detailed instructions on how to read imports.
For progressive disclosure, consider extracting the detailed scope interpretation (--branch, --all, specific endpoint) into a separate reference file, keeping only a brief summary in the main SKILL.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is mostly efficient and project-specific, but some sections are slightly verbose — e.g., the step-by-step 'How to Sync an Endpoint' section explains things like reading route definitions and view functions that Claude could infer from the codebase structure. The resource locations section and scope interpretation are valuable and well-targeted. | 2 / 3 |
Actionability | The skill provides concrete file paths, specific commands (git diff, validate_openapi.sh), exact code patterns to look for (add_url_rule, as_view), and clear mapping rules (Flask <int:id> to OpenAPI {id}). The guidance is specific enough to be directly executable. | 3 / 3 |
Workflow Clarity | The workflow is clearly sequenced across three distinct scopes (specific endpoint, branch, full sync), each with explicit steps. The validation section includes a feedback loop: run validation, fix errors, distinguish between must-fix structural errors and optional warnings. The 5-step sync process is well-ordered with clear checkpoints. | 3 / 3 |
Progressive Disclosure | The content is well-organized with clear headers and logical sections, but at ~150 lines it's a moderately long single file with no references to supporting documents. The detailed sync steps and scope interpretation could potentially be split into referenced files, though the current inline structure is still navigable. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Repository
- HHS/OPRE-OPS
- Commit
e2a9461
- 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.