Skip to content
Skills Library
Documents & office · Review & audit

docs-editor

/docs-editor

Review and edit OpenAI Cookbook notebooks, Markdown, and MDX for technical accuracy, clarity, grammar, consistency, runnable examples, and repository publication requirements. Use for editorial reviews, pre-merge documentation checks, or notebook Markdown-cell sweeps in openai-cookbook.

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Review and edit OpenAI Cookbook notebooks, Markdown, and MDX for technical accuracy, clarity, grammar, consistency, runnable examples, and repository publication requirements. Use for editorial reviews, pre-merge documentation checks, or notebook Markdown-cell sweeps in openai-cookbook.

Original author description

Review and edit OpenAI Cookbook notebooks, Markdown, and MDX for technical accuracy, clarity, grammar, consistency, runnable examples, and repository publication requirements. Use for editorial reviews, pre-merge documentation checks, or notebook Markdown-cell sweeps in openai-cookbook.

How it works

  1. Objective
  2. Workflow
Original SKILL.md headings · 81 lines, 568 words
SKILL.md preview
---
name: docs-editor
description: Review and edit OpenAI Cookbook notebooks, Markdown, and MDX for technical accuracy, clarity, grammar, consistency, runnable examples, and repository publication requirements. Use for editorial reviews, pre-merge documentation checks, or notebook Markdown-cell sweeps in openai-cookbook.
---

# OpenAI Cookbook docs editor

## Objective

Review Cookbook content conservatively. Improve correctness and readability without changing the author's intent, inventing facts, or creating unrelated churn.

## Workflow

### 1. Define the scope

- Prefer explicit paths or the files changed in the pull request.
- For pull requests, review changed `.md` and `.mdx` files plus Markdown cells in changed `.ipynb` files.
- Review `registry.yaml` and `authors.yaml` when content is added, moved, removed, or attributed to a new author.
- Stay within the requested content. Do not turn a focused review into a repository-wide rewrite.

### 2. Protect notebook integrity

- When the request is editorial, edit only notebook Markdown cells.
- Preserve code cells, outputs, execution counts, attachments, cell order, cell IDs, and notebook and cell metadata.
- Avoid reserializing an entire notebook for a small prose change. Inspect the diff for unintended JSON churn.
- Do not execute notebook code unless the user requests it or code changes are in scope. Markdown-only edits require structural validation, not calls to external services.
- Never add hard-coded secrets. Document required environment variables such as `OPENAI_API_KEY`.

### 3. Review the content

Load `resources/style-guide.md` and check:

- Technical claims, API names, model names, identifiers, commands, paths, and URLs.
- Agreement between prose, code, sample inputs, and expected outputs.
- Prerequisites, dependencies, environment variables, and steps needed to run an example.
- File and notebook names, headings, lists, numbering, cross-references, and links.
- Grammar, spelling, punctuation, terminology, capitalization, and concise wording.
- Publication metadata in `registry.yaml` and author metadata in `authors.yaml` when applicable.

Verify uncertain technical claims from an authoritative source or flag them for review. Do not guess.

### 4. Prioritize findings

Use the repository's review bar:

- **P0**: Broken notebook JSON; hard-coded secrets; materially false or unsafe guidance; or any repository-defined P0 issue, including naming violations, typos, broken links, inconsistent formatting, placeholder identifiers, undocumented environment variables, or out-of-sync publication metadata.
- **P1**: Misleading instructions, prose that contradicts code or output, missing prerequisites, or a required link that does not work.
- **P2**: Clear improvements to grammar, consistency, organization, or readability that do not affect correctness.
- **P3**: Optional polish with little effect on comprehension.

### 5. Make safe edits

- Fix obvious typos, grammar, punctuation, broken local references, and clear prose/code mismatches.
- Keep changes minimal, local, and reversible.
- Preserve exact literals, code identifiers, commands, values, counts, conditions, modality, negation, and uncertainty markers.
- Tighten prose only when meaning stays unchanged. Prefer concrete nouns, strong verbs, short introductions, and direct instructions.
- Flag any change that depends on product knowledge or could alter meaning instead of guessing.
- Do not make file-wide formatting or stylistic changes solely for uniformity.

### 6. Validate the result

For any changed notebook, run the repository validator:

```bash
env -u VIRTUAL_ENV uv run --with nbformat python .github/scripts/check_notebooks.py
```

Then:

- Run `git diff --check`.
- Inspect the diff and confirm that notebook changes are limited to intended Markdown cells.
- Run an available YAML linter if `registry.yaml` or `authors.yaml` changed.
- Run the relevant example or test only when executable content changed and its dependencies are available.

### 7. Report the review

Provide:

- A short summary of the scope and edits.
- Auto-fixed items.
- Remaining findings grouped by priority with file and cell or line references.
- The validation commands run and their results.

If no issues remain, say so explicitly.
Files in this package (2)
  • SKILL.md 4 KB
  • resources/style-guide.md 4 KB

Versions

The database has no other skills named docs-editor.

Database snapshot: 13.11.2026 · package version 8bc139fbe4b7 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100review-docs
    Review documentation files for grammar, factual accuracy, and query correctness. Use when the user asks to review docs, validate documentation, or check YQL examples. Accepts a path to a file or directory as argument.
  • 100tdmcp-cookbook-examples
    Adds new visual examples to the tdmcp prompt cookbook documentation — both the English and Portuguese versions. Use when asked to: add more cookbook examples, create visual examples for the docs, show more surprising things you can do, add entries to the prompt cookbook, expand…
  • 100tdmcp-cookbook-examples
    Adds new visual examples to the tdmcp prompt cookbook documentation — both the English and Portuguese versions. Use when asked to: add more cookbook examples, create visual examples for the docs, show more surprising things you can do, add entries to the prompt cookbook, expand…
  • 100doc-review
    Structured document review for structure, clarity, and technical accuracy. Use for \"review this doc\", feedback, critique, or /doc-review.
  • 100docs-review
    Use when the user wants documentation reviewed or edited for clarity, correctness, structure, or consistency: review docs, edit this doc, make this clearer.
  • 90ring:reviewing-docs
    Reviewing end-user and product documentation quality across voice/tone, structure, completeness, clarity, and technical accuracy; flags issues with prioritized findings and a pass/needs-revision verdict. Use when reviewing draft docs, running a pre-publication check, auditing…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.