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, --no-track, or a worktree: each produces a net-new branch, and committing there opens a second PR against someone else's work.

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.