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

88%

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, actionable body with strong workflow sequencing and explicit validation feedback loops for a batch/destructive operation. The main weaknesses are minor repetition in the path-naming guidance and the absence of a complete example openapi.yml entry to model new paths on.

Suggestions

Consolidate the '<int:id>' to '{id}' and trailing-slash rules into one section; Step 5 currently repeats what 'Path Naming Convention' already states.

Add one complete example openapi.yml path entry (tags, operationId, parameters, responses with a $ref) so new paths can be modeled copy-paste rather than inferred from conventions.

Trim the 'How to Determine Scope' filter bullet list slightly — the six path globs could be collapsed into a single glob pattern note without losing actionability.

Dimension	Reasoning	Score
Conciseness	Mostly lean and actionable with concrete paths and commands, but the '<int:id>' to '{id}' mapping and trailing-slash guidance are repeated across Step 5 and the 'Path Naming Convention' section, so it sits at 'efficient; minor instances that could be trimmed' rather than the fully lean 5.	4 / 5
Actionability	Provides executable snippets (add_url_rule, as_view, git diff, validate_openapi.sh) and concrete file paths, but never shows a complete example openapi.yml path entry to model, leaving a minor gap versus the copy-paste-ready 5 anchor.	4 / 5
Workflow Clarity	Sequences a five-step endpoint-sync process with an explicit validation checkpoint ('run the validation script', './backend/validate_openapi.sh') and a feedback loop (fix YAML syntax, ask about warnings, fix Swagger CLI errors), satisfying the destructive/batch validation requirement at the top anchor.	5 / 5
Progressive Disclosure	No bundle files exist and the content is organized into clear, navigable sections (Resource Locations, How to Determine Scope, How to Sync, Validation, Important Notes) with no nested references; at ~120 lines it exceeds the simple-skill threshold, so it lands at 'good structure; minor organization gaps' rather than the perfectly-split 5.	4 / 5
	Total	17 / 20 Passed

Description

95%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.

A strong, specific description with clear what/when structure, rich natural trigger terms including synonyms, and a well-defined niche. It only stops short of a perfect specificity score because the action list, while concrete, is limited to three verbs rather than a comprehensive enumeration.

Dimension	Reasoning	Score
Specificity	Names the domain (OpenAPI spec vs Flask routes) and three concrete actions ('Sync, update, and validate'), matching the 'several specific actions; minor gaps' anchor rather than the comprehensive multi-action coverage of a 5.	4 / 5
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 API docs... Also use when checking for drift') with concrete trigger phrases, matching the top anchor exactly.	5 / 5
Trigger Term Quality	Comprehensive natural-term coverage including synonyms and a quoted user phrase — 'API docs, swagger, OpenAPI, endpoint documentation, "update the spec"' plus 'drift between the code and the spec' — matching the anchor requiring synonyms and common variations.	5 / 5
Distinctiveness Conflict Risk	Targets a narrow niche (keeping backend/openapi.yml synced to Flask routes) with distinct triggers (swagger, OpenAPI, 'update the spec', drift) and minimal overlap with other skills; third-person voice used throughout with no pronoun penalty.	5 / 5
	Total	19 / 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: 0b4078c

Reviewed: 12 minutes 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.