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.

Quality

90%

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

81%Weight 40%Scale 1-5

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

A well-structured, highly actionable instruction skill: concrete commands, exact file paths, clear multi-mode scope logic, and a real validation feedback loop. Its main weaknesses are the duplicated and internally inconsistent trailing-slash guidance and the absence of a sample openapi.yml entry to concretize the edit conventions.

Suggestions

Consolidate the trailing-slash guidance into the Path Naming Convention section only, and remove the blanket 'Add trailing slashes' bullet in Step 5, since it contradicts the 'match the Flask route exactly' rule.

Add a short example YAML path entry (with tags, operationId, parameters, responses, $ref) to ground the 'follow existing conventions' instruction in Step 5.

Trim the repeated 'check views.py imports' hint from Step 3 since Resource Locations already establishes it.

Dimension	Reasoning	Score
Conciseness	The body is lean and imperative throughout, but trailing-slash guidance is duplicated: 'Add trailing slashes to match Flask routes (e.g., /agreements/ not /agreements)' at line 98 conflicts with 'some paths have trailing slashes and some don't... must match the Flask route exactly' at line 107, and Step 3 repeats the views.py-import tip already given in Resource Locations.	4 / 5
Actionability	Concrete executable commands ('git diff main...HEAD --name-only', './backend/validate_openapi.sh'), exact file paths, and field-level YAML conventions (tags, operationId, parameters, responses, <int:id> -> {id}) make the guidance mostly executable, though no example YAML path entry is shown to anchor the 'existing conventions' instruction.	4 / 5
Workflow Clarity	A three-mode scope dispatch (specific endpoint / --branch / --all) feeds a clearly sequenced 5-step sync procedure, and the Validation section provides an explicit validate-fix-retry feedback loop with error classification (fix YAML immediately, ask about Spectral/Redocly warnings, must-fix Swagger errors) — fully satisfying the batch-operation feedback-loop requirement.	5 / 5
Progressive Disclosure	No bundle files exist, and the ~120-line single file is appropriately self-contained with clear section headers, but the duplicated trailing-slash/path-naming content (lines 98 vs 101-107) and inline repetition of lookup hints indicate minor organization gaps.	4 / 5
	Total	17 / 20 Passed

Description

100%Weight 40%Scale 1-5

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

An exemplary description: third-person voice, concrete named files and actions, comprehensive natural trigger terms, and an explicit 'Use whenever...' clause covering both routine and drift-check scenarios. No weaknesses identified.

Dimension	Reasoning	Score
Specificity	'Sync, update, and validate the OpenAPI specification (backend/openapi.yml) against the Flask API routes' plus 'checking for drift between the code and the spec' lists multiple concrete, comprehensive actions with specific file targets — matching the anchor-5 example's breadth.	5 / 5
Completeness	It explicitly answers what (sync/update/validate the spec against Flask routes, with the exact file named) and when ('Use whenever endpoints have been added, changed, or removed, or when the user mentions API docs, swagger, OpenAPI...') — mirroring the anchor-5 example structure exactly.	5 / 5
Trigger Term Quality	Natural user phrasings are comprehensively covered: 'API docs', 'swagger', 'OpenAPI', 'endpoint documentation', 'update the spec', plus route/resource-class and drift vocabulary — synonym coverage matches the anchor-5 example.	5 / 5
Distinctiveness Conflict Risk	The OpenAPI/Flask spec-sync niche with repo-specific file paths (backend/openapi.yml, routes) is highly distinct, and its triggers (swagger, update the spec, drift) are unlikely to fire for unrelated skills.	5 / 5
	Total	20 / 20 Passed

Validation

87%

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 — 14 / 16 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	14 / 16 Passed

Repository: HHS/OPRE-OPS
Path: .claude/skills/sync-openapi/SKILL.md
Commit: b61c72b

Reviewed: 19 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.