--- name: docs-edit description: Edit a docs page that already has an open pull request, or revise a page in place. Covers checking out the PR's own branch instead of cutting a new one, forked cross-repository PRs, reading the real diff, checking the edit against related pages, and the verification to run before handing off. Use when asked to edit, revise, fix, or review changes on a named PR, branch, or existing page. --- # 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. ```bash gh pr view --json number,title,headRefName,baseRefName,author,isCrossRepository,files git status --porcelain # must be clean; stop and ask if it is not git fetch origin git checkout # tracks origin/ ``` Use plain `git checkout `. 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: ```bash 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 `, which configures the fork remote, and confirm push access before committing. Without it, the edits are stranded locally. ## Step 2. Read the real diff ```bash gh pr diff ``` 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: ```bash 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/ --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: ```bash grep -rliE "|" src --include='*.mdx' grep -n "" 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` | `changelog-weekly` skill, from langchainplus fragments | | `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 ```bash make lint_prose FILES="" ``` Run `make broken-links` as well when links, page names, or navigation entries changed. 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.