CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

update-openapi

Sync the OpenAPI specs in public/openapi*.json with the actual MCP tool surface defined in src/<provider>/server.ts. Diffs tools against operationIds, scaffolds new operation entries from each tool's Zod parameter schema, flags missing or stale entries, and updates descriptions that drifted. Used to keep the ChatGPT Custom Actions surface in sync with the MCP tools — these specs are how the REST clients discover what tools exist, so drift causes silent breakage downstream. Use this skill whenever the user wants to update, regenerate, sync, or audit OpenAPI specs after adding or modifying MCP tools, or invokes `/update-openapi [provider]`.

Quality

96%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

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

This is a strong, well-engineered skill body: an explicitly sequenced 9-step workflow with real validation checkpoints, fully concrete guidance, and a textbook one-level-deep reference split. The only weakness is mild redundancy — the intro duplicates the description and the stale-operation rule is stated three times across the body and reference.

Suggestions

Cut the opening paragraph's restatement of the description and keep only the non-obvious part (the mapping is a judgment call; no blind regeneration) to save ~2 lines.

State the 'never auto-delete stale operations' rule once (step 4) and let steps 6 and scaffold-rules.md reference it in a few words instead of restating the rationale.

DimensionReasoningScore

Conciseness

The body is efficient and assumes competence (no explaining what OpenAPI or Zod is), but the opening paragraph re-states the frontmatter description almost verbatim, and the 'never auto-delete stale operations' rule is repeated in step 4, step 6, and again in references/scaffold-rules.md. Mostly lean with a few instances of duplication that could be trimmed — the anchor-4 fit, not anchor 5's 'every token earns its place'.

4 / 5

Actionability

Guidance is fully executable for an instruction-only skill: exact file paths and collection fields ('name', 'annotations.readOnlyHint', 'parameters'), a concrete verification command ('jq . public/openapi-<file>.json > /dev/null'), verbatim diff/report templates, and precise scaffold response rules (200/400/401 with '$ref Error'). Nothing is left as vague direction.

5 / 5

Workflow Clarity

A 9-step sequenced procedure with explicit validation checkpoints: step 6 prints the diff and requires user confirmation before any write, and step 8 validates JSON with jq plus an operationId-vs-tool-count invariant with defined exceptions. The destructive/batch cap doesn't apply since validation is present, and flagged TODOs/stale operations form a feedback loop into the report.

5 / 5

Progressive Disclosure

The body is a clear overview and procedure, with the bulky lookup tables (HTTP method table, path conventions, Zod → OpenAPI translation) correctly split into references/scaffold-rules.md — verified to exist and contain exactly what the body signals ('HTTP-method table, path conventions, Zod → OpenAPI translation'). References are one level deep, clearly signaled at point of use, and documented in the File layout section.

5 / 5

Total

19

/

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.

The description is exemplary: it states concrete capabilities in third person, explains the downstream stakes ('drift causes silent breakage') without fluff, and gives explicit trigger guidance covering verb synonyms, context, and the slash command. It reads like the top anchor examples in both completeness and specificity.

DimensionReasoningScore

Specificity

The description lists the full concrete action surface — 'Diffs tools against operationIds, scaffolds new operation entries from each tool's Zod parameter schema, flags missing or stale entries, and updates descriptions that drifted' — with no vague filler. This matches the comprehensive multiple-concrete-actions anchor, not the level below, which allows minor coverage gaps.

5 / 5

Completeness

Both 'what' (diff, scaffold, flag, patch descriptions) and 'when' ('Use this skill whenever the user wants to update, regenerate, sync, or audit OpenAPI specs after adding or modifying MCP tools, or invokes /update-openapi') are explicit, with concrete trigger phrases — a direct match to the top anchor.

5 / 5

Trigger Term Quality

Natural verb synonyms users would say ('update, regenerate, sync, or audit OpenAPI specs') plus concrete artifacts ('public/openapi*.json', '/update-openapi [provider]') give comprehensive keyword coverage. Not 4: no commonly used natural phrasing for this task is missing.

5 / 5

Distinctiveness Conflict Risk

A clear niche (OpenAPI spec ↔ MCP tool sync) with a distinct slash-command trigger and specific file paths; overlap with adjacent skills like add-mcp-tool is explicitly scoped to 'after adding or modifying MCP tools'. Minimal conflict risk.

5 / 5

Total

20

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

Total

15

/

16

Passed

Repository

boarlabsxyz/awesome-mcp

Path

.claude/skills/update-openapi/SKILL.md

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.