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

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.
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.
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.
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.
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.
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.
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
```

docs-sync

NPX Install

Tags

SKILL.md Content

Docs Sync

Overview

Workflow

Output format

References