feat: Added openapi-format skills

Author: thim81

.gitignore

@@ -3,3 +3,4 @@ node_modules
 
 .idea
 .tmp
+.agents

readme.md

@@ -26,6 +26,7 @@ With the newly added OpenAPI Overlay support, users can overlay changes onto exi
     + [Local Installation (recommended)](#local-installation-recommended)
     + [Global Installation](#global-installation)
     + [NPX usage](#npx-usage)
+    + [Codex skill usage](#codex-skill-usage)
 * [Command Line Interface](#command-line-interface)
 * [OpenAPI format CLI options](#openapi-format-cli-options)
 * [OpenAPI sort configuration options](#openapi-sort-configuration-options)
@@ -139,6 +140,20 @@ To execute the CLI without installing it via npm, use the npx method
 $ npx openapi-format your-openapi-file.yaml
 ```
 
+### Codex skill usage
+
+To install the `openapi-format` skill from this repository:
+
+```shell
+$ npx skills add https://github.com/thim81/openapi-format --skill openapi-format
+```
+
+Then use it in Codex by explicitly referencing the skill in your prompt, for example:
+
+```text
+Using $openapi-format, create a minimal filter config to remove internal endpoints and give me the CLI command.
+```
+
 ## Command Line Interface
 
 ```

skills/openapi-format/SKILL.md

@@ -0,0 +1,78 @@
+---
+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).
+
+2. 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.
+
+3. Keep config minimal.
+- Start from defaults.
+- Add only keys required for requested behavior.
+- Avoid writing exhaustive config unless requested.
+
+4. 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`.
+
+5. Respect processing order.
+- `generate -> filter -> overlay -> sort -> casing -> convertTo -> rename -> write/split/stdout`
+
+6. 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).

skills/openapi-format/references/command-recipes.md

@@ -0,0 +1,144 @@
+# Command recipes
+
+These are direct CLI recipes for common and advanced workflows.
+
+## Basic formatting
+
+```bash
+openapi-format openapi.yaml --output openapi.formatted.yaml
+```
+
+## Print to stdout as JSON
+
+```bash
+openapi-format openapi.yaml --json
+```
+
+## Print to stdout as YAML
+
+```bash
+openapi-format openapi.json --yaml
+```
+
+## Use a specific config file
+
+```bash
+openapi-format openapi.yaml --configFile config/format.yaml --output dist/openapi.yaml
+```
+
+## Use custom sort file
+
+```bash
+openapi-format openapi.yaml --sortFile config/sort.json --output dist/openapi.yaml
+```
+
+## Sort specific component groups alphabetically
+
+```bash
+openapi-format openapi.yaml --sortComponentsFile config/sort-components.json --output dist/openapi.yaml
+```
+
+## Sort schema properties within components
+
+```bash
+openapi-format openapi.yaml --sortComponentsProps --output dist/openapi.yaml
+```
+
+## Disable sort
+
+```bash
+openapi-format openapi.yaml --no-sort --output dist/openapi.yaml
+```
+
+## Disable bundling
+
+```bash
+openapi-format openapi.yaml --no-bundle --output dist/openapi.yaml
+```
+
+## Filter with filter file
+
+```bash
+openapi-format openapi.yaml --filterFile config/filter.yaml --output dist/openapi.filtered.yaml
+```
+
+## Apply casing rules
+
+```bash
+openapi-format openapi.yaml --casingFile config/casing.yaml --output dist/openapi.cased.yaml
+```
+
+## Generate operationIds
+
+```bash
+openapi-format openapi.yaml --generateFile config/generate.yaml --output dist/openapi.generated.yaml
+```
+
+## Apply overlay to input
+
+```bash
+openapi-format openapi.yaml --overlayFile config/overlay.yaml --output dist/openapi.overlay.yaml
+```
+
+## Apply overlay with `extends` as implicit input
+
+```bash
+openapi-format --overlayFile config/overlay.yaml --output dist/openapi.overlay.yaml
+```
+
+## Convert to OpenAPI 3.1
+
+```bash
+openapi-format openapi.yaml --convertTo 3.1 --output dist/openapi.3.1.yaml
+```
+
+## Convert to OpenAPI 3.2
+
+```bash
+openapi-format openapi.yaml --convertTo 3.2 --output dist/openapi.3.2.yaml
+```
+
+## Rename API title
+
+```bash
+openapi-format openapi.yaml --rename "Example API" --output dist/openapi.renamed.yaml
+```
+
+## Split into multi-file structure
+
+```bash
+openapi-format openapi.yaml --split --output dist/openapi/root.yaml
+```
+
+## Preserve YAML comments and set line width
+
+```bash
+openapi-format openapi.yaml --keepComments --lineWidth 120 --output dist/openapi.yaml
+```
+
+## Verbose diagnostics
+
+```bash
+openapi-format openapi.yaml --filterFile config/filter.yaml --output dist/openapi.yaml -vv
+```
+
+## Playground share link generation
+
+```bash
+openapi-format openapi.yaml --configFile config/format.yaml --playground
+```
+
+## Composite example: generate, filter, overlay, casing, convert, rename
+
+```bash
+openapi-format openapi.yaml \
+  --generateFile config/generate.yaml \
+  --filterFile config/filter.yaml \
+  --overlayFile config/overlay.yaml \
+  --casingFile config/casing.yaml \
+  --convertTo 3.2 \
+  --rename "Public API" \
+  --output dist/openapi.public.3.2.yaml
+```
+
+Expected processing order is fixed by CLI internals; flags do not reorder stages.