Code Change Verification

A required verification workflow for code, test, and build changes in the OpenAI Agents Python repository.

Code Change Verification is an individual skill from OpenAI’s official open-source openai-agents-python repository. Its direct primary source is https://github.com/openai/openai-agents-python/tree/main/.agents/skills/code-change-verification. The skill describes a final verification workflow for changes that affect runtime code, tests, or build and test configuration. Rather than judging a change from a local snapshot alone, the workflow guides the user through formatting, linting, type checking, and tests. This creates an auditable technical gate before work is declared complete.

Purpose and audience

According to the provider, the skill should be used as a complete final gate only after a clean implementation review. During development, focused tests and narrowly targeted static checks are more useful because they provide fast feedback. The broad stack belongs at the end of a stable change. The skill fits teams that want to protect Python SDK changes reproducibly and need a clear statement about whether the expected quality checks passed. It does not replace product acceptance, security analysis, or a review of whether the change actually solves the right requirement.

The intended sequence

The official instructions provide a script for macOS and Linux that runs from the repository root. In the normal order it invokes make format, make lint, make typecheck, and make tests, stopping at the first failure. Formatting may modify files, while linting, type checking, and tests expose problems. For Codex in a sandbox, the source names an environment that removes the OpenAI key from the process and enables the intended sandbox test mode. Other local environments should run the script with their appropriate non-privileged environment. Windows uses the supplied PowerShell wrapper.

Failure handling and evidence

When a command fails, the issue should be fixed and the complete workflow rerun. A previously successful partial step does not prove that later checks will pass. The workflow streams output so a reviewer can inspect the concrete cause. Before starting the complete stack, the source recommends checking for other repository-wide tests, type checks, builds, examples runners, or integration commands already active on the host. Visible contention is a reason to continue review or preparation and check again later, not to introduce a repository lock, host-wide mutex, or sentinel file.

Security and boundaries

The skill does not authorize elevated permissions. It should run inside the normal workspace sandbox and must not be retried with broader host access after a failure. Tests can still depend on local packages, platform behavior, or missing system dependencies. According to the provider, specially marked native macOS sandbox tests may run on a trusted GitHub-hosted runner; when that runner is unavailable, the missing coverage must be reported openly. No verification stack proves complete security. Do not store API keys, tokens, personal data, or confidential test content in verification logs or example files. Local tests also do not mean that connected model calls are processed locally.

Practical interpretation

The value of this skill is its explicit end-to-end gate: a change is complete only after all required stages pass and no remaining issues are present. For an unstable change, the full run can be premature; focused tests are the better intermediate step. This description was checked against the official skill file and official OpenAI Agents documentation on September 9, 2026. The repository is open source and licensed under Apache-2.0 according to the provider. Always verify current scripts, dependencies, and platform notes in the primary source.

Installation instructions

Step 1: What the Code Change Verification skill is

The Code Change Verification skill comes from OpenAI's official openai-agents-python repository, where it lives in the agent skills directory used by the OpenAI Agents SDK for Python. According to the provider, the skill ensures that work is only marked complete once formatting, linting, type checking, and tests have all passed. It applies to changes that affect runtime code, tests, or build/test configuration, but can be skipped for docs-only or repository-metadata-only changes unless the full check stack is explicitly requested. The skill explicitly presents itself as a final gate that runs after review has already happened, and it only becomes active once the preceding review step has concluded on a stable diff.

Step 2: The verification flow in detail

According to the documentation, the actual check is executed via a startup script, with different invocations depending on the operating system: on macOS/Linux there is a specific invocation for use inside a Codex sandbox environment and a more general invocation for other environments, while Windows uses a PowerShell script. On macOS and Linux, the script runs the four steps make format, make lint, make typecheck, and make tests sequentially and stops at the first failure, while parallelism within individual steps, such as multiple test workers, remains unchanged. The Bash script streams each command's output directly and unaltered, while the Windows wrapper runs the lint, typecheck, and test steps in parallel with periodic heartbeat updates. If a command fails, the underlying issue must be fixed and the script rerun; only once every command succeeds with no remaining issues is the change considered fully verified.

Step 3: When the full check kicks in

A notable feature of the skill is its tiered approach to resource usage. According to the documentation, during an ongoing, iterative review only focused individual tests and a narrowly targeted static check for the specific typing boundary affected should be used; the complete, repository-wide check run with make typecheck and the remaining steps is deliberately deferred until review is clean. Immediately before starting the complete check chain, available read-only process or task indicators should be used to check whether another repository-wide test, typecheck, build, or integration run is already active on the same host. If such concrete resource contention is detected, other, less resource-intensive work should continue instead, with a later re-check, without creating a repository lock, a host-wide mutex, or a sentinel file.

Step 4: Prerequisites and setup

For the skill to load automatically, according to the documentation it must be placed in the .agents/skills/code-change-verification directory within the respective repository. It also requires a working Makefile with the format, lint, typecheck, and tests targets, since the script wrappers ultimately just call these Make targets in sequence. For use inside a Codex sandbox on macOS or Linux, a specific environment-variable invocation is also intended, which among other things sets an alternative Python package index to keep network access within the sandbox under control.

Security, limitations, and best practices

According to the documentation, verification runs and any child processes they start must remain strictly within the normal Codex sandbox; the verification wrapper must not request elevated sandbox permissions, nor should it retry with elevated privileges, which prevents an automated verification run from unintentionally exceeding its intended access rights. The limitation of the skill is that it does not itself perform any qualitative assessment of the code; it functions purely as execution and stop logic around already-existing tools such as formatters, linters, type checkers, and test runners. If one of those underlying tools is poorly configured, that gap carries through unchanged into the verification. For projects without a unified Makefile providing the four named targets, the skill is not directly usable in its current form and would first need to be adapted to fit the project's own build toolchain.

Free
Provider
OpenAI
License
Apache-2.0
Last reviewed
09.09.2026

Repository and documentation

Categories

Compatible with

Codex