AgentSkillsCN

openapi-format

配置并运行 OpenAPI/AsyncAPI 文档的 openapi-format CLI 工作流。适用于需要对字段进行排序、筛选操作/标签/标志/内容、更改大小写、生成 operationId、应用叠加层、转换 OpenAPI 版本（3.0/3.1 至 3.1/3.2）、重命名标题、拆分规范、捆绑引用，或以最小的配置覆盖，管理由 .openapiformatrc/--configFile 驱动的格式化流水线时使用。

SKILL.md
--- frontmatter
name: openapi-format
description: Configure and run openapi-format CLI workflows for OpenAPI/AsyncAPI documents. Use when you need to sort fields, filter operations/tags/flags/content, change casing, generate operationIds, apply overlays, convert OpenAPI versions (3.0/3.1 to 3.1/3.2), rename titles, split specs, bundle refs, or manage .openapiformatrc/--configFile driven formatting pipelines with minimal config overrides.

openapi-format

Follow this skill when a user asks to transform an OpenAPI document with the openapi-format CLI.

Core workflow

  1. •Identify the target outcome first.
  • •Determine exactly what should change: order, filtering, casing, generation, overlay, conversion, rename, output format, split.
  • •Determine input source (local file, remote URL, or overlay extends fallback).
  1. •Choose command shape.
  • •Prefer a single command with explicit input/output unless the user asks for stdout.
  • •Use --configFile for reusable workflows.
  • •Use .openapiformatrc for project defaults.
  1. •Keep config minimal.
  • •Start from defaults.
  • •Add only keys required for requested behavior.
  • •Avoid writing exhaustive config unless requested.
  1. •Apply correct precedence.
  • •Load .openapiformatrc only when --configFile is not supplied.
  • •Load and merge --configFile values.
  • •Apply CLI options last.
  • •Normalize --no-sort and --no-bundle into sort=false and bundle=false.
  1. •Respect processing order.
  • •generate -> filter -> overlay -> sort -> casing -> convertTo -> rename -> write/split/stdout
  1. •Produce the output safely.
  • •Use --output for file writes.
  • •If --split is true, require --output and treat it as split target root.
  • •Use --json or --yaml for stdout output formatting.

Decision rules

Filter semantics

  • •Treat methods, tags, operationIds, operations, flags, flagValues, responseContent, and requestContent as removal filters.
  • •Treat inverseMethods, inverseTags, inverseOperationIds, inverseFlags, inverseFlagValues, inverseResponseContent, and inverseRequestContent as keep filters.
  • •Use unusedComponents to remove unreferenced components recursively (iterative cleanup).
  • •Use stripFlags to delete marker fields after filtering.

Overlay behavior

  • •Accept --overlayFile with actions.
  • •If input file is omitted and overlay has extends, use extends as effective input.
  • •Resolve local extends relative to overlay file directory.

Sorting and components

  • •Default sorting comes from defaultSort.json.
  • •sortPathsBy controls path ordering (original, path, tags).
  • •--sortComponentsFile controls which component groups are alphabetized.
  • •--sortComponentsProps alphabetizes schema properties in components.schemas.*.properties.

Output constraints

  • •--split requires --output.
  • •--keepComments only affects YAML comment preservation.
  • •--lineWidth controls YAML line wrapping (-1 means unlimited).

Use references

Open only what is needed:

  • •references/feature-matrix.md for option behavior, defaults, and interactions.
  • •references/config-patterns.md for minimal config templates.
  • •references/command-recipes.md for runnable command patterns.
  • •references/troubleshooting.md for failure diagnosis and fixes.

Delivery checklist

  1. •Return the exact command(s) to run.
  2. •Return minimal config file contents if config files are needed.
  3. •Explain expected transformation result in plain terms.
  4. •Call out side effects (component pruning, split output tree, version conversion changes).
  5. •Highlight any assumptions (input path, output path, format, bundle behavior).