Skip to content

Commit d79bd98

Browse files
seratchseratch
authored
misc: add docs-sync skill (#2306)
1 parent f3f69c2 commit d79bd98

2 files changed

Lines changed: 132 additions & 0 deletions

File tree

‎.codex/skills/docs-sync/SKILL.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
name: docs-sync
3+
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.
4+
---
5+
6+
# Docs Sync
7+
8+
## Overview
9+
10+
Identify doc coverage gaps and inaccuracies by comparing main branch features and configuration options against the current docs structure, then propose targeted improvements.
11+
12+
## Workflow
13+
14+
1. Confirm scope and base branch
15+
- Identify the current branch and default branch (usually `main`).
16+
- Prefer analyzing the current branch to keep work aligned with in-flight changes.
17+
- If the current branch is not `main`, analyze only the diff vs `main` to scope doc updates.
18+
- Avoid switching branches if it would disrupt local changes; use `git show main:<path>` or `git worktree add` when needed.
19+
20+
2. Build a feature inventory from the selected scope
21+
- If on `main`: inventory the full surface area and review docs comprehensively.
22+
- If not on `main`: inventory only changes vs `main` (feature additions/changes/removals).
23+
- Focus on user-facing behavior: public exports, configuration options, environment variables, CLI commands, default values, and documented runtime behaviors.
24+
- Capture evidence for each item (file path + symbol/setting).
25+
- Use targeted search to find option types and feature flags (for example: `rg "Settings"`, `rg "Config"`, `rg "os.environ"`, `rg "OPENAI_"`).
26+
- 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.
27+
28+
3. Doc-first pass: review existing pages
29+
- Walk each relevant page under `docs/` (excluding `docs/ja`, `docs/ko`, and `docs/zh`).
30+
- Identify missing mentions of important, supported options (opt-in flags, env vars), customization points, or new features from `src/agents/` and `examples/`.
31+
- Propose additions where users would reasonably expect to find them on that page.
32+
33+
4. Code-first pass: map features to docs
34+
- Review the current docs information architecture under `docs/` and `mkdocs.yml`.
35+
- Determine the best page/section for each feature based on existing patterns and the API reference structure under `docs/ref`.
36+
- Identify features that lack any doc page or have a page but no corresponding content.
37+
- Note when a structural adjustment would improve discoverability.
38+
- 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.
39+
40+
5. Detect gaps and inaccuracies
41+
- **Missing**: features/configs present in main but absent in docs.
42+
- **Incorrect/outdated**: names, defaults, or behaviors that diverge from main.
43+
- **Structural issues** (optional): pages overloaded, missing overviews, or mis-grouped topics.
44+
45+
6. Produce a Docs Sync Report and ask for approval
46+
- Provide a clear report with evidence, suggested doc locations, and proposed edits.
47+
- Ask the user whether to proceed with doc updates.
48+
49+
7. If approved, apply changes (English only)
50+
- Edit only English docs in `docs/**`.
51+
- Do **not** edit `docs/ja`, `docs/ko`, or `docs/zh`.
52+
- Keep changes aligned with the existing docs style and navigation.
53+
- Update `mkdocs.yml` when adding or renaming pages.
54+
- Build docs with `make build-docs` after edits to verify the docs site still builds.
55+
56+
## Output format
57+
58+
Use this template when reporting findings:
59+
60+
Docs Sync Report
61+
62+
- Doc-first findings
63+
- Page + missing content -> evidence + suggested insertion point
64+
- Code-first gaps
65+
- Feature + evidence -> suggested doc page/section (or missing page)
66+
- Incorrect or outdated docs
67+
- Doc file + issue + correct info + evidence
68+
- Structural suggestions (optional)
69+
- Proposed change + rationale
70+
- Proposed edits
71+
- Doc file -> concise change summary
72+
- Questions for the user
73+
74+
## References
75+
76+
- `references/doc-coverage-checklist.md`

‎.codex/skills/docs-sync/references/doc-coverage-checklist.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Doc Coverage Checklist
2+
3+
Use this checklist to scan the selected scope (main = comprehensive, or current-branch diff) and validate documentation coverage.
4+
5+
## Feature inventory targets
6+
7+
- Public exports: classes, functions, types, and module entry points.
8+
- Configuration options: `*Settings` types, default config objects, and builder patterns.
9+
- Environment variables or runtime flags.
10+
- CLI commands, scripts, and example entry points that define supported usage.
11+
- User-facing behaviors: retry, timeouts, streaming, errors, logging, telemetry, and data handling.
12+
- Deprecations, removals, or renamed settings.
13+
14+
## Doc-first pass (page-by-page)
15+
16+
- Review each relevant English page (excluding `docs/ja`, `docs/ko`, and `docs/zh`).
17+
- Look for missing opt-in flags, env vars, or customization options that the page implies.
18+
- Add new features that belong on that page based on user intent and navigation.
19+
20+
## Code-first pass (feature inventory)
21+
22+
- Map features to the closest existing page based on the docs navigation in `mkdocs.yml`.
23+
- Prefer updating existing pages over creating new ones unless the topic is clearly new.
24+
- Use conceptual pages for cross-cutting concerns (auth, errors, streaming, tracing, tools).
25+
- Keep quick-start flows minimal; move advanced details into deeper pages.
26+
27+
## Evidence capture
28+
29+
- Record the main-branch file path and symbol/setting name.
30+
- Note defaults or behavior-critical details for accuracy checks.
31+
- Avoid large code dumps; a short identifier is enough.
32+
33+
## Red flags for outdated or incorrect docs
34+
35+
- Option names/types no longer exist or differ from code.
36+
- Default values or allowed ranges do not match implementation.
37+
- Features removed in code but still documented.
38+
- New behaviors introduced without corresponding docs updates.
39+
40+
## When to propose structural changes
41+
42+
- A page mixes unrelated audiences (quick-start + deep reference) without clear separation.
43+
- Multiple pages duplicate the same concept without cross-links.
44+
- New feature areas have no obvious home in the nav structure.
45+
46+
## Diff mode guidance (current branch vs main)
47+
48+
- Focus only on changed behavior: new exports/options, modified defaults, removed features, or renamed settings.
49+
- Use `git diff main...HEAD` (or equivalent) to constrain analysis.
50+
- Document removals explicitly so docs can be pruned if needed.
51+
52+
## Patch guidance
53+
54+
- Keep edits scoped and aligned with existing tone and format.
55+
- Update cross-links when moving or renaming sections.
56+
- Leave translated docs untouched; English-only updates.

0 commit comments

Comments
 (0)