docs-edit

Edit an existing docs page or PR

The failure this skill prevents: an agent asked to "fix the wording on PR 1234" cuts a fresh branch, commits there, and opens a second pull request against a teammate's work. Land edits on the branch that already exists.

Step 1. Check out the PR's own branch

When the request names a PR, by number or URL, work on that PR's head branch.

gh pr view <n> --json number,title,headRefName,baseRefName,author,isCrossRepository,files
git status --porcelain          # must be clean; stop and ask if it is not
git fetch origin <headRefName>
git checkout <headRefName>      # tracks origin/<headRefName>

Use plain git checkout <branch>. Do not use git checkout -b or --no-track: each produces a net-new branch, and committing there opens a second PR against someone else's work.

A worktree on the PR's own branch is fine, and safer when other sessions share the main checkout. Pass the existing branch name, never -b:

git fetch origin <headRefName>
git worktree add <dir> <headRefName>   # tracks origin/<headRefName>

This fails if the branch is already checked out in another worktree. Use that worktree instead of forcing a second one.

mise trusts config files by path, so each new worktree's .mise.toml starts out untrusted. The Vale pre-commit hook runs through mise exec, and the first commit fails with Config files in <dir>/.mise.toml are not trusted. Run mise trust once in the worktree, then commit again. To stop this for good, add the main checkout to trusted_config_paths in ~/.config/mise/config.toml. It trusts every worktree created inside the checkout, such as .claude/worktrees/*, but not sibling directories.

A local branch whose name merely mentions the PR is not the same branch. Confirm that git rev-parse HEAD matches the headRefOid from gh pr view before editing, and that the branch has an upstream:

git rev-parse --abbrev-ref @{upstream}   # fails when the branch tracks nothing

Cut a new branch only when the edits are your own and no open PR exists to land them on, or when the user asks for one. Branch from the latest origin/main, never from a stale local main.

Cross-repository PRs

When isCrossRepository is true, the branch lives on a fork. Use gh pr checkout <n>, which configures the fork remote, and confirm push access before committing. Without it, the edits are stranded locally.

Step 2. Read the real diff

gh pr diff <n>

Prefer this over git diff main...HEAD. A stale local main silently inflates that diff with unrelated commits, and a branch that already merged main once inflates it further. To compare against the live base instead, fetch first and use git diff origin/main...HEAD.

Step 3. Edit

AGENTS.md holds the rules that apply to every edit: the style guide, frontmatter, syntax, and the navigation map. Two that matter most here:

Match the conventions of the file you are editing. Do not restructure, combine, or split pages unless asked.
Never fabricate examples, field names, UI labels, or policy details. Verify each factual claim against the source it describes, and state plainly what you could not verify.

For voice and sentence rhythm while drafting, use the docs-team-voice skill. For adding, moving, renaming, or deleting a page, including navigation and redirects, use add-docs-page. When the edit is really a question of which page the content belongs on, use docs-restructure.

Verify claims against source, not against other docs

A sibling docs page is not a source. It is another claim, written by someone who may have been guessing too, and two docs pages that agree can both be wrong. Check the implementation:

gh api -X GET search/code -f q='LANGSMITH_GATEWAY repo:langchain-ai/langchain' \
    --jq '.total_count, (.items[]?|.path)'
gh api repos/langchain-ai/langchain/contents/<path> --jq .content | base64 -d

Python and TypeScript live in separate repositories and drift apart, so a table with a Python column and a TypeScript column needs both checked: langchain-ai/langchain, langchain-ai/langchainjs, and for some providers a dedicated repository such as langchain-ai/langchain-google. A package's CHANGELOG.md gives the version a feature landed in, which is what a minimum version column needs.

State plainly what you could not verify. "I could not confirm the Baseten row; no gateway references in either candidate repository" is a useful review note. Silently keeping an unverified claim is not.

Read the pages around the one you are editing

A page is one of several that cover the same feature. Others reach it from another angle: a CLI reference, a permissions table, a list of Chat surfaces, a setup guide, the pages that link to it. An edit made to one page in isolation leaves the set contradicting itself.

Before editing, find the related pages:

grep -rliE "<feature name>|<page-slug>" src --include='*.mdx'
grep -n "<page-slug>" src/docs.json

Read each one, then check for:

Contradictions. The edited page and a related one give different setup steps, defaults, or requirements. For example, a feature page that sets LANGSMITH_API_KEY while the CLI page recommends langsmith auth login. Settle it against source, then fix whichever page is wrong.
Duplication. A procedure the edited page restates from the page that owns it. Link to the owner instead. When choosing the owner is the real question, use docs-restructure.
Missing entry points. A page that lists every surface, command group, or permission area of a product should mention the feature and link to it.
Navigation placement. A page filed in a group that does not match its subject. Report it; do not move the page unless asked.

A related page tells you what to check, not what is true. When two pages disagree, the source decides, as described in the section above.

Keep edits to related pages small: a cross-link, a corrected fact, or a short entry that points at the owner page. Anything larger is a restructure, so ask first.

Never hand-edit generated files

These are written by a generator. Editing them looks like it works, then a scheduled run reverts it, and for the changelogs the edit has already gone out over RSS:

File	Generated by
`src/langsmith/changelog.mdx` and `src/snippets/langsmith/fleet-changelog.mdx`	the `changelog-weekly.yml` workflow (`scripts/changelog_pipeline.py weekly`), from merged langchainplus PRs
`src/langsmith/self-hosted-changelog.mdx`	the helm changelog bot
`src/langsmith/langsmith-platform-openapi.json`	`.github/workflows/refresh-langsmith-openapi.yml`
`src/langsmith/agent-server-openapi.json`	PRs from the `langgraph-api` repository
`src/snippets/deepagents-eval-category-matrix.mdx`	`scripts/refresh_deepagents_category_matrix.py`
`src/snippets/langsmith/mda-oauth-catalog.mdx`	`scripts/refresh_mda_oauth_catalog.py`
`build/`	`make build`

When one of these carries the problem you were asked to fix, fix the generator or the upstream source and say so. Do not edit the output.

When an instruction reverses an earlier one

Reviewers change their minds, and on a long thread they will ask for a format they previously rejected. Converting a table to a list and then back wastes a round and loses the reasoning both times.

When an instruction contradicts one you already applied, say so before applying it: name the earlier instruction, the change you made for it, and ask which to keep. Two reversals on the same element mean the requirement is unclear, not that the format is wrong.

Step 4. Verify before handing off

make lint_prose FILES="<changed files>"

Run make broken-links-with-anchors as well when links, page names, or navigation entries changed, and make check-mdx when it adds a JSX tag. Look up a tag new to src/ on Mintlify components first. For a prose review against the style guide, use the docs-review skill.

Step 5. Report

Say which branch the edits are on and whether it is the PR's own branch. Name the related pages you changed, and the ones you read and left alone. If anything could not be verified, list it. Do not push or force-push unless the user asks.

When you write or update a PR description, two rules apply:

Linear: When the work has a Linear issue, link it with Closes [DOC-N](<linear url>) or Refs [DOC-N](<linear url>) as appropriate. sync-linear-issue-from-pr.yml only syncs status for docs-release-watch PRs labeled release-watch-agent, so a human PR does not move the issue.
AI disclosure: End the description with one plain sentence, such as Prepared with Claude Code. Do not add a 🤖 Generated with [Claude Code](...) badge or any similar badge. check-pr-ai-attribution fails a PR that carries one, because the squash merge copies it into the commit on main.