home / skills / openai / openai-agents-python / docs-sync

docs-sync skill

safe

/.codex/skills/docs-sync

This skill audits docs coverage against main branch features and configuration, suggests updates, and reports changes before approving edits.

npx playbooks add skill openai/openai-agents-python --skill docs-sync

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

4.2 KB

---
name: docs-sync
description: Analyze main branch implementation and configuration to find missing, incorrect, or outdated documentation in docs/. Use when asked to audit doc coverage, sync docs with code, or propose doc updates/structure changes. Only update English docs under docs/** and never touch translated docs under docs/ja, docs/ko, or docs/zh. Provide a report and ask for approval before editing docs.
---

# Docs Sync

## Overview

Identify doc coverage gaps and inaccuracies by comparing main branch features and configuration options against the current docs structure, then propose targeted improvements.

## Workflow

1. Confirm scope and base branch
   - Identify the current branch and default branch (usually `main`).
   - Prefer analyzing the current branch to keep work aligned with in-flight changes.
   - If the current branch is not `main`, analyze only the diff vs `main` to scope doc updates.
   - Avoid switching branches if it would disrupt local changes; use `git show main:<path>` or `git worktree add` when needed.

2. Build a feature inventory from the selected scope
   - If on `main`: inventory the full surface area and review docs comprehensively.
   - If not on `main`: inventory only changes vs `main` (feature additions/changes/removals).
   - Focus on user-facing behavior: public exports, configuration options, environment variables, CLI commands, default values, and documented runtime behaviors.
   - Capture evidence for each item (file path + symbol/setting).
   - Use targeted search to find option types and feature flags (for example: `rg "Settings"`, `rg "Config"`, `rg "os.environ"`, `rg "OPENAI_"`).
   - When the topic involves OpenAI platform features, invoke `$openai-knowledge` to pull current details from the OpenAI Developer Docs MCP server instead of guessing, while treating the SDK source code as the source of truth when discrepancies appear.

3. Doc-first pass: review existing pages
   - Walk each relevant page under `docs/` (excluding `docs/ja`, `docs/ko`, and `docs/zh`).
   - Identify missing mentions of important, supported options (opt-in flags, env vars), customization points, or new features from `src/agents/` and `examples/`.
   - Propose additions where users would reasonably expect to find them on that page.

4. Code-first pass: map features to docs
   - Review the current docs information architecture under `docs/` and `mkdocs.yml`.
   - Determine the best page/section for each feature based on existing patterns and the API reference structure under `docs/ref`.
   - Identify features that lack any doc page or have a page but no corresponding content.
   - Note when a structural adjustment would improve discoverability.
   - When improving `docs/ref/*` pages, treat the corresponding docstrings/comments in `src/` as the source of truth. Prefer updating those code comments so regenerated reference docs stay correct, instead of hand-editing the generated pages.

5. Detect gaps and inaccuracies
   - **Missing**: features/configs present in main but absent in docs.
   - **Incorrect/outdated**: names, defaults, or behaviors that diverge from main.
   - **Structural issues** (optional): pages overloaded, missing overviews, or mis-grouped topics.

6. Produce a Docs Sync Report and ask for approval
   - Provide a clear report with evidence, suggested doc locations, and proposed edits.
   - Ask the user whether to proceed with doc updates.

7. If approved, apply changes (English only)
   - Edit only English docs in `docs/**`.
   - Do **not** edit `docs/ja`, `docs/ko`, or `docs/zh`.
   - Keep changes aligned with the existing docs style and navigation.
   - Update `mkdocs.yml` when adding or renaming pages.
   - Build docs with `make build-docs` after edits to verify the docs site still builds.

## Output format

Use this template when reporting findings:

Docs Sync Report

- Doc-first findings
  - Page + missing content -> evidence + suggested insertion point
- Code-first gaps
  - Feature + evidence -> suggested doc page/section (or missing page)
- Incorrect or outdated docs
  - Doc file + issue + correct info + evidence
- Structural suggestions (optional)
  - Proposed change + rationale
- Proposed edits
  - Doc file -> concise change summary
- Questions for the user

## References

- `references/doc-coverage-checklist.md`

Overview

This skill analyzes the main branch implementation and configuration to find missing, incorrect, or outdated English documentation under docs/. It compares code and config to the docs structure, produces a prioritized Docs Sync Report, and asks for approval before applying changes. It never edits translated docs under docs/ja, docs/ko, or docs/zh.

How this skill works

The skill inventories user-facing surface area (public exports, CLI, config options, env vars, defaults) from the selected branch or the diff vs main. It walks existing docs/pages, maps code features to the docs structure, and flags missing, incorrect, or misgrouped content with file-level evidence. After producing a report with suggested locations and edits, it requests approval before making English-only updates and verifies the docs build.

When to use it

You need an audit of docs coverage vs current implementation on main or a feature branch.
Preparing a release and want to ensure docs reflect new config options or CLI changes.
Onboarding new contributors and ensuring docs match public APIs and examples.
Proposing structural changes to improve docs discoverability and navigation.
Validating that generated reference docs match docstrings in source code.

Best practices

Analyze the current branch first; if not on main, scope work to the diff vs main.
Capture evidence for each gap: code path, symbol, or config file and line where applicable.
Propose doc edits tied to specific pages and insertion points, not vague suggestions.
Prefer updating source docstrings for API/reference fixes so generated docs remain correct.
Always ask for user approval before modifying English docs; never touch translated docs.

Example use cases

Audit docs to find undocumented configuration flags introduced in a recent PR.
Sync CLI help output and examples with the docs when command options changed.
Detect and fix mismatched default values between code and docs prior to release.
Suggest reorganizing docs/ref sections to improve discoverability of agent APIs.
Produce a change-ready patch with mkdocs.yml updates and a build verification step.

FAQ

Will this skill edit translated docs?

No. It only edits English docs under docs/** and explicitly avoids docs/ja, docs/ko, and docs/zh.

How does it decide where to put new content?

It maps features to existing patterns in docs/ and docs/ref, prefers pages with matching scope, and recommends structural adjustments when discoverability would improve.

Does it change code or docstrings?

It recommends updating docstrings for reference changes but only edits English docs after user approval; it does not alter source code without explicit direction.