docs: align contributor guide and skills with JS updates (#2286)

seratch · web-flow · commit 19b7c0bbab31 · 2026-01-10T10:55:51.000+09:00
diff --git a/.codex/skills/code-change-verification/SKILL.md b/.codex/skills/code-change-verification/SKILL.md
@@ -0,0 +1,35 @@
+---
+name: code-change-verification
+description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents Python repository.
+---
+
+# Code Change Verification
+
+## Overview
+
+Ensure work is only marked complete after formatting, linting, type checking, and tests pass. Use this skill when changes affect runtime code, tests, or build/test configuration. You can skip it for docs-only or repository metadata unless a user asks for the full stack.
+
+## Quick start
+
+1. Keep this skill at `./.codex/skills/code-change-verification` so it loads automatically for the repository.
+2. macOS/Linux: `bash .codex/skills/code-change-verification/scripts/run.sh`.
+3. Windows: `powershell -ExecutionPolicy Bypass -File .codex/skills/code-change-verification/scripts/run.ps1`.
+4. If any command fails, fix the issue, rerun the script, and report the failing output.
+5. Confirm completion only when all commands succeed with no remaining issues.
+
+## Manual workflow
+
+- If dependencies are not installed or have changed, run `make sync` first to install dev requirements via `uv`.
+- Run from the repository root in this order: `make format`, `make lint`, `make mypy`, `make tests`.
+- Do not skip steps; stop and fix issues immediately when a command fails.
+- Re-run the full stack after applying fixes so the commands execute in the required order.
+
+## Resources
+
+### scripts/run.sh
+
+- Executes the full verification sequence with fail-fast semantics from the repository root. Prefer this entry point to ensure the required commands run in the correct order.
+
+### scripts/run.ps1
+
+- Windows-friendly wrapper that runs the same verification sequence with fail-fast semantics. Use from PowerShell with execution policy bypass if required by your environment.
diff --git a/.codex/skills/code-change-verification/scripts/run.ps1 b/.codex/skills/code-change-verification/scripts/run.ps1
@@ -25,7 +25,7 @@ function Invoke-MakeStep {
     & make $Step
 
     if ($LASTEXITCODE -ne 0) {
-        Write-Error "verify-changes: make $Step failed with exit code $LASTEXITCODE."
+        Write-Error "code-change-verification: make $Step failed with exit code $LASTEXITCODE."
         exit $LASTEXITCODE
     }
 }
@@ -35,4 +35,4 @@ Invoke-MakeStep -Step "lint"
 Invoke-MakeStep -Step "mypy"
 Invoke-MakeStep -Step "tests"
 
-Write-Host "verify-changes: all commands passed."
+Write-Host "code-change-verification: all commands passed."
diff --git a/.codex/skills/code-change-verification/scripts/run.sh b/.codex/skills/code-change-verification/scripts/run.sh
@@ -22,4 +22,4 @@ make mypy
 echo "Running make tests..."
 make tests
 
-echo "verify-changes: all commands passed."
+echo "code-change-verification: all commands passed."
diff --git a/.codex/skills/openai-knowledge/SKILL.md b/.codex/skills/openai-knowledge/SKILL.md
@@ -0,0 +1,44 @@
+---
+name: openai-knowledge
+description: Use when working with the OpenAI API (Responses API) or OpenAI platform features (tools, streaming, Realtime API, auth, models, rate limits, MCP) and you need authoritative, up-to-date documentation (schemas, examples, limits, edge cases). Prefer the OpenAI Developer Documentation MCP server tools when available; otherwise guide the user to enable `openaiDeveloperDocs`.
+---
+
+# OpenAI Knowledge
+
+## Overview
+
+Use the OpenAI Developer Documentation MCP server to search and fetch exact docs (markdown), then base your answer on that text instead of guessing.
+
+## Workflow
+
+### 1) Check whether the Docs MCP server is available
+
+If the `mcp__openaiDeveloperDocs__*` tools are available, use them.
+
+If you are unsure, run `codex mcp list` and check for `openaiDeveloperDocs`.
+
+### 2) Use MCP tools to pull exact docs
+
+- Search first, then fetch the specific page or pages.
+  - `mcp__openaiDeveloperDocs__search_openai_docs` → pick the best URL.
+  - `mcp__openaiDeveloperDocs__fetch_openai_doc` → retrieve the exact markdown (optionally with an `anchor`).
+- When you need endpoint schemas or parameters, use:
+  - `mcp__openaiDeveloperDocs__get_openapi_spec`
+  - `mcp__openaiDeveloperDocs__list_api_endpoints`
+
+Base your answer on the fetched text and quote or paraphrase it precisely. Do not invent flags, field names, defaults, or limits.
+
+### 3) If MCP is not configured, guide setup (do not change config unless asked)
+
+Provide one of these setup options, then ask the user to restart the Codex session so the tools load:
+
+- CLI:
+  - `codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp`
+- Config file (`~/.codex/config.toml`):
+  - Add:
+    ```toml
+    [mcp_servers.openaiDeveloperDocs]
+    url = "https://developers.openai.com/mcp"
+    ```
+
+Also point to: https://developers.openai.com/resources/docs-mcp#quickstart
diff --git a/.codex/skills/verify-changes/SKILL.md b/.codex/skills/verify-changes/SKILL.md
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,61 +1,186 @@
-Welcome to the OpenAI Agents SDK repository. This file contains the main points for new contributors.
+# Contributor Guide
 
-## Repository overview
+This guide helps new contributors get started with the OpenAI Agents Python repository. It covers repo structure, how to test your work, available utilities, and guidelines for commits and PRs.
 
-- **Source code**: `src/agents/` contains the implementation.
-- **Tests**: `tests/` with a short guide in `tests/README.md`.
-- **Examples**: under `examples/`.
-- **Documentation**: markdown pages live in `docs/` with `mkdocs.yml` controlling the site. Translated docs under `docs/ja`, `docs/ko`, and `docs/zh` are managed by an automated job; do not edit them manually.
-- **Utilities**: developer commands are defined in the `Makefile`.
-- **PR template**: `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md` describes the information every PR must include.
+**Location:** `AGENTS.md` at the repository root.
 
-## Agent requirements
+## Table of Contents
 
-- Always invoke `$verify-changes` before completing any work. The skill encapsulates the required formatting, linting, type-checking, and tests; follow `.codex/skills/verify-changes/SKILL.md` for how to run it.
+1. [Mandatory Skill Usage](#mandatory-skill-usage)
+2. [Overview](#overview)
+3. [Repo Structure & Important Files](#repo-structure--important-files)
+4. [Testing & Automated Checks](#testing--automated-checks)
+5. [Repo-Specific Utilities](#repo-specific-utilities)
+6. [Style, Linting & Type Checking](#style-linting--type-checking)
+7. [Development Workflow](#development-workflow)
+8. [Pull Request & Commit Guidelines](#pull-request--commit-guidelines)
+9. [Review Process & What Reviewers Look For](#review-process--what-reviewers-look-for)
+10. [Tips for Navigating the Repo](#tips-for-navigating-the-repo)
+11. [Prerequisites](#prerequisites)
 
-## Planning guidance
+## Mandatory Skill Usage
 
-- Before starting work, surface any potential backward compatibility risks in your implementation plan and confirm the approach when breaking changes could affect existing users.
+### `$code-change-verification`
 
-## Local workflow
+Run `$code-change-verification` before marking work complete when changes affect runtime code, tests, or build/test behavior.
 
-1. Run `$verify-changes` before handing off work; it formats, lints, type-checks, and runs the test suite (see `.codex/skills/verify-changes/SKILL.md` for the workflow).
-2. To run a single test, use `uv run pytest -s -k <test_name>`.
-3. Build the documentation when you touch docs: `make build-docs`.
+Run it when you change:
+- `src/agents/` (library code) or shared utilities.
+- `tests/` or add or modify snapshot tests.
+- `examples/`.
+- Build or test configuration such as `pyproject.toml`, `Makefile`, `mkdocs.yml`, `docs/scripts/`, or CI workflows.
 
-Coverage can be generated with `make coverage`.
+You can skip `$code-change-verification` for docs-only or repo-meta changes (for example, `docs/`, `.codex/`, `README.md`, `AGENTS.md`, `.github/`), unless a user explicitly asks to run the full verification stack.
 
-All python commands should be run via `uv run python ...`
+### `$openai-knowledge`
 
-## Snapshot tests
+When working on OpenAI API or OpenAI platform integrations in this repo (Responses API, tools, streaming, Realtime API, auth, models, rate limits, MCP, Agents SDK or ChatGPT Apps SDK), use `$openai-knowledge` to pull authoritative docs via the OpenAI Developer Docs MCP server (and guide setup if it is not configured).
 
-Some tests rely on inline snapshots. See `tests/README.md` for details on updating them:
+### Planning expectations
 
-```bash
-make snapshots-fix      # update existing snapshots
-make snapshots-create   # create new snapshots
-```
+Call out potential backward compatibility or public API risks early in your plan and confirm the approach before implementing changes that could impact users.
+
+## Overview
+
+The OpenAI Agents Python repository provides the Python Agents SDK, examples, and documentation built with MkDocs. Use `uv run python ...` for Python commands to ensure a consistent environment.
+
+## Repo Structure & Important Files
+
+- `src/agents/`: Core library implementation.
+- `tests/`: Test suite; see `tests/README.md` for snapshot guidance.
+- `examples/`: Sample projects showing SDK usage.
+- `docs/`: MkDocs documentation source; do not edit translated docs under `docs/ja`, `docs/ko`, or `docs/zh` (they are generated).
+- `docs/scripts/`: Documentation utilities, including translation and reference generation.
+- `mkdocs.yml`: Documentation site configuration.
+- `Makefile`: Common developer commands.
+- `pyproject.toml`, `uv.lock`: Python dependencies and tool configuration.
+- `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`: Pull request template to use when opening PRs.
+- `site/`: Built documentation output.
+
+## Testing & Automated Checks
 
-Run `make tests` again after updating snapshots to ensure they pass.
+Before submitting changes, ensure relevant checks pass and extend tests when you touch code.
 
-## Style notes
+When `$code-change-verification` applies, run it to execute the required verification stack from the repository root. Rerun the full stack after applying fixes.
 
-- Write comments as full sentences and end them with a period.
+### Unit tests and type checking
 
-## Pull request expectations
+- Run the full test suite:
+  ```bash
+  make tests
+  ```
+- Run a focused test:
+  ```bash
+  uv run pytest -s -k <pattern>
+  ```
+- Type checking:
+  ```bash
+  make mypy
+  ```
 
-PRs should use the template located at `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`. Provide a summary, test plan and issue number if applicable, then check that:
+### Snapshot tests
 
-- New tests are added when needed.
-- Documentation is updated.
-- `make lint` and `make format` have been run.
-- The full test suite passes.
+Some tests rely on inline snapshots; see `tests/README.md` for details. Re-run `make tests` after updating snapshots.
 
-Commit messages should be concise and written in the imperative mood. Small, focused commits are preferred.
+- Fix snapshots:
+  ```bash
+  make snapshots-fix
+  ```
+- Create new snapshots:
+  ```bash
+  make snapshots-create
+  ```
 
-## What reviewers look for
+### Coverage
+
+- Generate coverage (fails if coverage drops below threshold):
+  ```bash
+  make coverage
+  ```
+
+### Mandatory local run order
+
+When `$code-change-verification` applies, run the full sequence in order (or use the skill scripts):
+
+```bash
+make format
+make lint
+make mypy
+make tests
+```
 
-- Tests covering new behaviour.
-- Consistent style: code formatted with `uv run ruff format`, imports sorted, and type hints passing `uv run mypy .`.
-- Clear documentation for any public API changes.
-- Clean history and a helpful PR description.
+## Repo-Specific Utilities
+
+- Install or refresh development dependencies:
+  ```bash
+  make sync
+  ```
+- Run tests against Python 3.9 in an isolated environment:
+  ```bash
+  make old_version_tests
+  ```
+- Documentation workflows:
+  ```bash
+  make build-docs      # build docs after editing docs
+  make serve-docs      # preview docs locally
+  make build-full-docs # run translations and build
+  ```
+- Snapshot helpers:
+  ```bash
+  make snapshots-fix
+  make snapshots-create
+  ```
+
+## Style, Linting & Type Checking
+
+- Formatting and linting use `ruff`; run `make format` (applies fixes) and `make lint` (checks only).
+- Type hints must pass `make mypy`.
+- Write comments as full sentences ending with a period.
+- Imports are managed by Ruff and should stay sorted.
+
+## Development Workflow
+
+1. Sync with `main` and create a feature branch:
+   ```bash
+   git checkout -b feat/<short-description>
+   ```
+2. If dependencies changed or you are setting up the repo, run `make sync`.
+3. Implement changes and add or update tests alongside code updates.
+4. Highlight backward compatibility or API risks in your plan before implementing breaking or user-facing changes.
+5. Build docs when you touch documentation:
+   ```bash
+   make build-docs
+   ```
+6. When `$code-change-verification` applies, run it to execute the full verification stack before handoff.
+7. Commit with concise, imperative messages; keep commits small and focused, then open a pull request.
+8. When reporting code changes as complete, include what you changed plus a draft pull request title and description for your local changes; start the description with prose such as “This pull request resolves/updates/adds …” using a verb that matches the change (you can use bullets later), explain the change background (for bugs, clearly describe the bug, symptoms, or repro; for features, what is needed and why), any behavior changes or considerations to be aware of, and you do not need to mention tests you ran.
+
+## Pull Request & Commit Guidelines
+
+- Use the template at `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`; include a summary, test plan, and issue number if applicable.
+- Add tests for new behavior when feasible and update documentation for user-facing changes.
+- Run `make format`, `make lint`, `make mypy`, and `make tests` before marking work ready.
+- Commit messages should be concise and written in the imperative mood. Small, focused commits are preferred.
+
+## Review Process & What Reviewers Look For
+
+- ✅ Checks pass (`make format`, `make lint`, `make mypy`, `make tests`).
+- ✅ Tests cover new behavior and edge cases.
+- ✅ Code is readable, maintainable, and consistent with existing style.
+- ✅ Public APIs and user-facing behavior changes are documented.
+- ✅ Examples are updated if behavior changes.
+- ✅ History is clean with a clear PR description.
+
+## Tips for Navigating the Repo
+
+- Use `examples/` to see common SDK usage patterns.
+- Review `Makefile` for common commands and use `uv run` for Python invocations.
+- Explore `docs/` and `docs/scripts/` to understand the documentation pipeline.
+- Consult `tests/README.md` for test and snapshot workflows.
+- Check `mkdocs.yml` to understand how docs are organized.
+
+## Prerequisites
+
+- Python 3.9+.
+- `uv` installed for dependency management (`uv sync`) and `uv run` for Python commands.
+- `make` available to run repository tasks.
diff --git a/tests/README.md b/tests/README.md
@@ -21,5 +21,5 @@ make snapshots-fix
 ### Creating snapshots
 
 ```
-make snapshots-update
+make snapshots-create
 ```

Original file line number	Diff line number	Diff line change
`@@ -25,7 +25,7 @@ function Invoke-MakeStep {`
`25`	`25`	`& make $Step`
`26`	`26`
`27`	`27`	`if ($LASTEXITCODE -ne 0) {`
`28`		`- Write-Error "verify-changes: make $Step failed with exit code $LASTEXITCODE."`
	`28`	`+ Write-Error "code-change-verification: make $Step failed with exit code $LASTEXITCODE."`
`29`	`29`	`exit $LASTEXITCODE`
`30`	`30`	`}`
`31`	`31`	`}`
`@@ -35,4 +35,4 @@ Invoke-MakeStep -Step "lint"`
`35`	`35`	`Invoke-MakeStep -Step "mypy"`
`36`	`36`	`Invoke-MakeStep -Step "tests"`
`37`	`37`
`38`		`-Write-Host "verify-changes: all commands passed."`
	`38`	`+Write-Host "code-change-verification: all commands passed."`