Skip to content
Skills Library
Programming · Review & audit

check-api-compat

/check-api-compat

Determine the correct behavior of vLLM's OpenAI-compatible or Anthropic-compatible API by checking the official upstream spec, instead of guessing from vLLM's own code. Use for any bug, issue, PR, review, or question touching /v1/chat/completions, /v1/completions, /v1/responses, /v1/embeddings, /v1/messages, or their request/response models — including "is this a bug or intended", "what should this field default to", "does upstream allow this", and any change that adds, removes, or renames a field on those models. Do not use for vLLM-internal APIs (engine, scheduler, LLM class) or for endpoint

Repository
vllm ↗
Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Determine the correct behavior of vLLM's OpenAI-compatible or Anthropic-compatible API by checking the official upstream spec, instead of guessing from vLLM's own code. Use for any bug, issue, PR, review, or question touching /v1/chat/completions, /v1/completions, /v1/responses, /v1/embeddings, /v1/messages, or their request/response models — including "is this a bug or intended", "what should this field default to", "does upstream allow this", and any change that adds, removes, or renames a field on those models. Do not use for vLLM-internal APIs (engine, scheduler, LLM class) or for endpoint

Triggers from the description

is this a bug or intendedwhat should this field default todoes upstream allow this
Original author description

Determine the correct behavior of vLLM's OpenAI-compatible or Anthropic-compatible API by checking the official upstream spec, instead of guessing from vLLM's own code. Use for any bug, issue, PR, review, or question touching /v1/chat/completions, /v1/completions, /v1/responses, /v1/embeddings, /v1/messages, or their request/response models — including "is this a bug or intended", "what should this field default to", "does upstream allow this", and any change that adds, removes, or renames a field on those models. Do not use for vLLM-internal APIs (engine, scheduler, LLM class) or for endpoint

How it works

  1. 1. Pin down the question
  2. 2. Read vLLM's implementation
  3. 3. Fetch the upstream spec
  4. 4. Compare on all four axes
  5. 5. Classify before calling it a bug
  6. 6. Report
Original SKILL.md headings · 109 lines, 695 words
SKILL.md preview
---
name: check-api-compat
description: Determine the correct behavior of vLLM's OpenAI-compatible or Anthropic-compatible API by checking the official upstream spec, instead of guessing from vLLM's own code. Use for any bug, issue, PR, review, or question touching /v1/chat/completions, /v1/completions, /v1/responses, /v1/embeddings, /v1/messages, or their request/response models — including "is this a bug or intended", "what should this field default to", "does upstream allow this", and any change that adds, removes, or renames a field on those models. Do not use for vLLM-internal APIs (engine, scheduler, LLM class) or for endpoints with no upstream counterpart.
---

# Checking vLLM API compatibility against the upstream spec

vLLM's OpenAI and Anthropic server surfaces are *reimplementations* of someone
else's spec. vLLM's own code, tests, and docstrings are not evidence of correct
behavior — they are the thing under test. Establish what upstream says first,
then compare.

Never answer "what should this field do" from memory. Field names, types, and
especially defaults drift between spec versions.

## 1. Pin down the question

Name three things before looking anything up:

- **Which surface** — OpenAI-compatible or Anthropic-compatible. They are separate
  code paths in vLLM and separate specs.
- **Which endpoint**, by path.
- **Which field or behavior** — a request field, a response field, a streaming
  event shape, an error code, or a status code.

## 2. Read vLLM's implementation

In a vLLM checkout, the request/response models live beside each endpoint:

| surface | path |
| --- | --- |
| OpenAI chat | `vllm/entrypoints/openai/chat_completion/` |
| OpenAI completions | `vllm/entrypoints/openai/completion/` |
| OpenAI responses | `vllm/entrypoints/openai/responses/` |
| OpenAI embeddings | `vllm/entrypoints/pooling/embed/` |
| OpenAI shared base models, errors, usage | `vllm/entrypoints/serve/engine/protocol.py` |
| Anthropic messages | `vllm/entrypoints/anthropic/` |
| audio | `vllm/entrypoints/speech_to_text/*/protocol.py` |

Each directory holds `protocol.py` (the Pydantic models), `serving.py` (behavior),
and `api_router.py` (routing and status codes). Read the field declaration *and*
the code that consumes it — a field can be declared faithfully and then ignored,
which is still an incompatibility.

## 3. Fetch the upstream spec

Prefer a source that can actually be read as text, in this order.

### OpenAI

1. The OpenAPI spec — authoritative, machine-readable, and fetches cleanly:
   `https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml`
2. The installed `openai` Python SDK's typed params, which track the spec closely.
   Locate them with `python -c "import openai,os;print(os.path.dirname(openai.__file__))"`,
   then read e.g. `types/chat/completion_create_params.py`,
   `types/chat/chat_completion.py`, `types/chat/chat_completion_chunk.py`,
   `types/responses/`. Note the SDK version — an old SDK is an old spec.
3. The prose reference at `https://platform.openai.com/docs/api-reference/...`
   for semantics the types do not carry. It is script-heavy and often fetches
   poorly; treat a failed fetch as a fetch failure, not as absence of a field.

### Anthropic

1. `https://docs.claude.com/en/api/messages` and
   `https://docs.claude.com/en/api/messages-streaming` — these render as clean
   text and are the primary source for both fields and streaming event order.
2. The installed `anthropic` SDK's `types/message_create_params.py`,
   `types/message.py`, `types/raw_message_stream_event.py`.

Say which source and which version answered the question, so the finding can be
re-checked later.

## 4. Compare on all four axes

A field is compatible only when **name**, **type**, **default**, and **semantics**
all match. Most real bugs hide in the last two: a field that exists with the right
type but the wrong default, or one that is accepted and silently dropped.

Also check, when relevant:

- **Streaming** — chunk shape, the order of events, and the terminal event
  (`data: [DONE]` for Chat Completions and Completions; `response.completed`,
  `response.failed`, or `response.incomplete` with no `[DONE]` for Responses;
  `message_stop` for Anthropic).
- **Errors** — HTTP status *and* the error body's `type`/`code` strings.
- **Omitted vs null** — upstream often distinguishes an absent field from an
  explicit `null`. Pydantic defaults erase that distinction unless the model is
  written to preserve it.

## 5. Classify before calling it a bug

Three outcomes, and they are not the same:

- **Matches upstream** — no action.
- **vLLM extension** — a field upstream has no name for at all (`vllm_xargs`,
  `chat_template_kwargs`, sampling knobs like `min_p`). These are intentional and
  allowed. Do not report them as violations. Check per surface: `top_k` is an
  extension on OpenAI but a real upstream field on Anthropic Messages.
- **Incompatibility** — a field that *shares a name with upstream* but differs in
  type, default, or behavior, or an upstream field that is missing, ignored, or
  malformed. This is the reportable case.

An unsupported-but-declared field is its own subcase: decide whether vLLM rejects
it explicitly or accepts and ignores it, and report which, since silently ignoring
a documented field is the more damaging failure.

## 6. Report

State: the endpoint and field, what upstream specifies (with the source), what
vLLM does (with `file:line`), which of the three outcomes it is, and the smallest
fix. When behavior turns on a spec detail that is easy to disbelieve, quote the
upstream line rather than paraphrasing it.
Files in this package (2)
  • SKILL.md 6 KB
  • agents/openai.yaml 1 KB

Versions

The database has no other skills named check-api-compat.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 3627ae793583 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100vllm
    Complete vLLM v0.19.0 Python API reference for high-throughput LLM inference: offline batch generation, chat, embeddings, classification, structured outputs, LoRA adapters, multimodal inputs, and OpenAI-compatible server. Triggers on: vLLM questions, Python LLM serving, GPU…
  • 100vllm-xpu-run
    Serve a Hugging Face safetensors model on an Intel GPU with upstream vLLM-XPU's OpenAI-compatible API, or check whether a model or architecture is currently documented on XPU. Covers live support lookup, image choice, container launch, known serve-flag requirements, model-impl…
  • 96vllm-compare-reqs
    Use this skill to compare vllm requirements files between versions
  • 100minicpm5-deploy-vllm
    Serve MiniCPM5-1B or MiniCPM5-2B via vLLM as an OpenAI-compatible HTTP server. Use when the user wants high-throughput production serving on NVIDIA GPU, asks for "vLLM", "OpenAI server", "REST API for MiniCPM5", or "production deployment".
  • 90tt-vllm-serving-review
    Reviews the vLLM and tt-inference-server serving path — generator_vllm.py contracts, plugin registration, the tt_data_parallel ambiguity, and TT-fork branch and config conventions. Use when reviewing changes to generator_vllm.py, vLLM plugin registration, or serving configuration.
  • 95pinme-llm
    Use this skill when a PinMe project (Worker TypeScript) needs to call OpenRouter-backed LLM APIs, including models, chat/completions, streaming, or OpenRouter web search. Guides AI to generate correct Worker TS code.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.