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

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

77%

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

A strong, actionable workflow with clear sequencing and validation feedback loops for a fragile batch operation. Its main weakness is monolithic structure with repeated guidance, which could be tightened and split into a reference file.

Suggestions

Consolidate the repeated 'check views.py imports first' reminder (Resource Locations, Step 2, Step 3, Path Naming Convention) into a single authoritative statement to reduce token cost.

Move the per-endpoint sync detail (Steps 1-5) and the Path Naming Convention into a one-level-deep reference file (e.g. references/syncing-an-endpoint.md), leaving the SKILL.md body as an overview with signaled pointers to improve progressive disclosure.

Add a brief drift-detection command or example for the Full Sync mode's 'Potentially stale' comparison, since detecting implementation changes currently relies on unstated heuristics.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and free of conceptual padding, but the 'check views.py imports first' guidance is repeated across Resource Locations, Step 2, Step 3, and the Path Naming Convention, which could be consolidated.	2 / 3
Actionability	Provides executable code snippets (add_url_rule, as_view), concrete commands (git diff main...HEAD --name-only, ./backend/validate_openapi.sh), specific file paths, and explicit conversion rules (<int:id> -> {id}) — copy-paste ready.	3 / 3
Workflow Clarity	Sequenced into three scope modes plus a 5-step procedure, with an explicit Validation section containing a fix-explain-must-fix error-recovery loop appropriate for an 8200-line file edit.	3 / 3
Progressive Disclosure	Well-organized into clear sections, but with no bundle files the skill is monolithic — per-endpoint sync detail and path-convention reference material stay inline rather than being offloaded to one-level-deep reference files.	2 / 3
	Total	10 / 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.

An exemplary description: concrete actions, natural trigger terms covering common phrasings, explicit what-and-when guidance, and a well-scoped niche that minimizes conflict risk. No meaningful improvements needed.

Dimension	Reasoning	Score
Specificity	Names three concrete actions — 'Sync, update, and validate the OpenAPI specification' — tied to a specific artifact (backend/openapi.yml), matching the multiple-concrete-actions anchor.	3 / 3
Completeness	Explicitly answers both what ('Sync, update, and validate the OpenAPI specification against the Flask API routes') and when ('Use whenever endpoints have been added, changed, or removed, or when the user mentions...'), with detailed explicit triggers.	3 / 3
Trigger Term Quality	Covers natural user phrasings including 'API docs, swagger, OpenAPI, endpoint documentation, "update the spec"' plus drift-checking triggers, giving good coverage of terms users would actually say.	3 / 3
Distinctiveness Conflict Risk	Scoped to a specific file (backend/openapi.yml) and framework (Flask routes), giving it a clear niche unlikely to trigger for unrelated skills.	3 / 3
	Total	12 / 12 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
Commit: 908aa71

Reviewed: 5 days 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.