playbooks

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

docs-sync skill

/.codex/skills/docs-sync

This skill analyzes main branch doc coverage to identify gaps and propose updates for English docs only, with a readiness to report and seek approval.

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

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

Files (2)
SKILL.md
4.4 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 (docs/src/content/docs/**) and never touch translated docs under docs/src/content/docs/ja, ko, or 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 "Options"`, `rg "process.env"`, `rg "export"`).
   - 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.
   - For MCP SDK (`modelcontextprotocol/typescript-sdk`) or Vercel AI SDK (`@ai-sdk/*`) topics, optionally use Deepwiki MCP for quick lookups, and still treat the SDK source code as the source of truth.

3. Doc-first pass: review existing pages
   - Walk each relevant page under `docs/src/content/docs` (excluding `docs/src/content/docs/openai`).
   - Identify missing mentions of important, supported options (opt-in flags, env vars), customization points, or new features from `packages/`.
   - 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/src/content/docs`.
   - Determine the best page/section for each feature based on existing patterns and package boundaries.
   - Identify features that lack any doc page or have a page but no corresponding content.
   - Note when a structural adjustment would improve discoverability.

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/src/content/docs/**`.
   - Exclude `docs/src/content/docs/openai` from review and updates.
   - Do **not** edit `docs/src/content/docs/ja`, `docs/src/content/docs/ko`, or `docs/src/content/docs/zh`.
   - Keep changes aligned with the existing docs style and navigation.
   - Place any code snippets under `examples/docs/<doc-filename>/` so the directory name matches the target doc file, mirroring existing patterns.
   - Verify doc code snippets build successfully with `pnpm -F docs-code build-check` and fix issues before handoff.

## 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 audits the repository's main-branch implementation and configuration to find missing, incorrect, or outdated English documentation under docs/src/content/docs/**. It compares code and config against the docs, produces a prioritized Docs Sync Report with evidence and proposed edits, and asks for approval before making any changes. It never touches translated docs (ja, ko, zh) or the docs/src/content/docs/openai directory.

How this skill works

The skill builds a feature inventory from the selected scope (full main branch or diff vs main) by scanning public exports, config options, env vars, CLI commands, and runtime behavior. It performs a doc-first pass across docs/src/content/docs, then a code-first pass mapping uncovered features to appropriate pages. Findings are compiled into a structured Docs Sync Report with evidence, suggested locations, and concise edit summaries. If you approve, the skill applies edits only to English docs and verifies snippet builds before handoff.

When to use it

  • Audit documentation coverage after a release or major feature merge to main
  • Sync docs with in-flight branch changes by analyzing diffs vs main
  • Identify and fix incorrect defaults, names, or behaviors documented in docs
  • Propose structural documentation changes to improve discoverability
  • Prepare a focused list of doc edits before opening a documentation PR

Best practices

  • Confirm analysis scope (current branch vs main) before starting
  • Treat source code as the source of truth; cite file paths and symbols as evidence
  • Limit edits to English docs under docs/src/content/docs/** and exclude openai and translated folders
  • Place example code under examples/docs/<doc-filename>/ to mirror existing patterns
  • Run pnpm -F docs-code build-check to validate doc snippet builds before committing

Example use cases

  • A new TypeScript package export was added but lacks a docs page — produce a report and suggested page placement
  • Configuration option names or defaults changed in main — list outdated doc lines and proposed fixes
  • A feature was added on a feature branch — provide a diff-focused doc checklist to sync only relevant pages
  • Detect overloaded pages that should be split and propose a new docs structure with rationale
  • Validate that environment variables and CLI flags referenced in docs match the codebase

FAQ

Will you edit translated docs?

No. Edits are limited to English files under docs/src/content/docs/**. Translated folders (ja, ko, zh) are never modified.

Do you change code or config?

No. The skill only inspects code and configuration to produce evidence-backed doc changes; it does not modify source code or configuration files.

What happens after the report?

I will ask for your approval. If approved, I apply edits to English docs, place examples under examples/docs/<doc-filename>/, and run build checks before finalizing edits.