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
| Page | ID | Owns |
|---|---|---|
| Docs tooling and agents | 3ca808527b178153839bff0f2831914c |
Parent directory. Page table, "Owned elsewhere" list, quick-answers FAQ. |
| Docs tech stack | 30c808527b178073876af57f7d87d8ca |
The production site only: fencing, src versus build, build pipeline, navigation, integration docs. |
| Local setup and quality gates | 3c8808527b1781dcbaf5d04834a843bf |
mise and prek setup, the docs and mint CLIs, Vale, git hooks, broken-link triage, the CI matrix, preview deployments, publishing. |
| Docs automation and agents | 3c8808527b17815b81cbf92896b5c3ee |
Scheduled workflows and their cron times, the changelog agents, the #ask-docs intake agent, tracked skills, agent-instruction files, MCP servers. |
| Reference docs | 3c9808527b1781858ebbe92914b02970 |
The three LangSmith OpenAPI sources, reference.langchain.com, the @[ClassName] link map. |
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_strmust 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_contenton 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.