Document tooling in Notion

The docs team's internal tooling documentation is five Notion pages under Docs Team. This skill routes a change to the one page that owns it, then edits that page without tripping the known Notion failure modes.

Requires the Notion MCP server (notion-fetch, notion-update-page).

Rule one: one home per topic

Every topic lives on exactly one page. Duplicates drift, and drift is worse than a long page. Before writing anything, search the other four pages for the topic. If it already appears somewhere, update it there instead of adding a second copy.

Step 1. Route the topic

Most new tooling lands on Docs automation and agents (a workflow, script, agent, skill, or MCP server) or Local setup and quality gates (anything a contributor runs on their own machine or that gates a PR).

The changelog system is not owned by these pages. LangSmith release notes owns fragments, the fragment schema, and both pipelines. Link to it; do not re-explain it. These pages keep only the runbook: deployment IDs, HTTP routes, required environment variables, and recovery paths.

Step 2. Check whether it belongs in Notion at all

Do not write a Notion page for something the repo already documents where people find it. Deliberately excluded: IDE_SETUP.md, .github/brand-guidelines.md, .github/pull_request_template.md, .github/CONTRIBUTING.md, the issue templates, and the navigation map, which lives only in AGENTS.md because the Notion copy went stale once already.

Skills are the same: a skill is its own authoritative reference. Name it on the Notion page, say what it covers and the one or two facts a reader needs in order to decide whether to open it, and stop there.

Untracked tooling is not team infrastructure. Anything under a gitignored path is personal tooling and does not go on these pages.

Step 3. Write it

Follow the docs-team-voice skill. Do not restate its rules here. The three that get missed most often on Notion pages: no first person, no spaced em dashes, and definition lists written as - **Term**: Explanation. with the colon outside the bold and a period at the end.

Open a section with a one-sentence statement of what the thing is, then what it enables, then the procedure. Close a substantial page with ## See also.

Step 4. Edit safely

Fetch the page with notion-fetch before every edit. Then use notion-update-page with command: "update_content" and narrow content_updates pairs rather than rewriting the page.

Five failure modes, each of which has already cost a debugging cycle:

• old_str must match the stored indentation exactly. Tables are stored with no leading tabs; callouts do use tabs. A mismatch fails with an indentation hint.
• Never use replace_content on a page holding an uploaded image. The fetched image URL is a short-lived signed S3 link, and rewriting the page body can break the image.
• A timed-out or async update may already have applied. Updates default to allow_async: true. Fetch the page and verify before retrying anything that appeared to fail, otherwise the retry duplicates the block.
• Bold that contains inline code mid-sentence renders as stray asterisks. Bold wrapping code entirely is fine. Reword so the two do not collide.
• In-page anchor links do not resolve. Notion addresses blocks by ID, not by heading slug. Reference sections by name in prose.

Step 5. Add a row to the Detailed list

The parent page embeds a Detailed list database (collection://3ce80852-7b17-8004-8735-000bc758a8cd) holding one row per piece of tooling. Prose on a page is where someone reads about a thing; this database is where they find that it exists at all. It is easy to miss, because the parent page renders it as a single inline block.

Every new workflow, script, skill, agent, MCP server, or git hook gets a row. The schema is Title, Description, Docs page (the URL of the page that explains it), Source (the repo paths it lives at), and Type, a select over GH Actions (scheduled), GH Actions (PR/CI), Fleet agent, Deep agent, External bot, Skill, MCP server, Manual script, and Git hook.

Query it with notion-query-data-sources before adding, so a rename becomes an update rather than a duplicate row. Renaming or moving a file means updating Source here too, not only in the prose: four rows still pointed at a skills directory that had been renamed months earlier, and every one of them read as plausible.

Step 6. Close the loop

Update the parent page's page table when a page's scope changes, and repoint any ## See also entry that is now wrong. Report which page was edited and what was deliberately left out, so the routing decision is reviewable.