Smithery is now a part of Arcade.dev! Read more in our announcement here
Checks if code changes require documentation updates
Review code changes and determine if documentation updates or new
documentation is needed. This skill decides whether a change needs docs;
its counterpart, the write-docs skill, covers
writing them.
[!IMPORTANT] The canonical rules for what belongs in the Coder docs (and what doesn't) live in
docs/.style/content-guidelines.md. Read that first. When this skill conflicts with the content guidelines, the content guidelines govern.
Get the code changes. Use the method provided in the prompt, or if none specified:
gh pr diff <PR_NUMBER> --repo coder/codergit diff main or git diff --stagedgit diff main...<branch>Triage the diff. Check the changed paths against
path-priors.md for what they predict, then walk the
quick decision checklist
in the content guidelines. Most non-user-facing diffs route out of
the docs entirely; see What not to comment on.
A prior sets the starting assumption, not the verdict: verify it against
the diff either way.
Understand the scope. Consider what changed:
Search the docs. Find related content in docs/.
Decide what's needed. Consider:
Report findings. Use the method provided in the prompt, or if none specified, summarize findings directly. When the prompt asks for a comment on a pull request, follow Writing the comment.
Follow this order on every review.
List what the user experiences, not what files changed. "User-facing" means what a user sees, types, clicks, or receives. Dashboard code and wiring code count when they change what the user experiences. A new label, a new tab, a new required field, a new setting, and a removed control all count.
Check two kinds of page per item. For each item on that list, check the conceptual guide for that area, and any page that enumerates the things this change adds to or removes from (a table of settings, a list of tabs, a list of fields). An auto-generated CLI or API reference never closes a gap in a conceptual guide. Treat the reference and the guide as two separate checks.
Search for the old fact, do not read only the diff. List every literal the diff changes: default values, flag names, env var names, thresholds, UI labels. Search the whole docs tree for each old literal before you decide:
grep -rn '<the old literal>' docs/ | grep -v '^docs/reference/'
Search the value as a number and as prose, because a guide can spell it
out ("thirty days" as well as 30d). A hit outside docs/reference/ is
a gap: this PR regenerating a reference page never fixes a conceptual
guide. Report each search you ran and what it returned. A review that
inspects only the files in the diff cannot find this class of gap, which
is the most common real one, so it is not a review.
If no page states the fact and the content guidelines require it, that is also a gap. If no page states it and the guidelines do not require it, that is not a gap: absence alone is not drift.
A PR that documents itself needs nothing more. Judge the state after the whole diff lands. If the diff already adds or fixes the documentation that its own code change requires, the requirement is satisfied inside the PR. Post no comment.
Write the evidence before the verdict. For each user-facing change, state the change, the searches you ran, the page you checked, and what you found on it. Then state whether that evidence shows a real unresolved gap, and comment only when it does. A verdict that contradicts your own evidence is the most common failure mode on this job, so read both once more before you post.
Staying silent is a finding too, and it earns the same evidence. Post
nothing only after every search in step 3 came back empty outside
docs/reference/. "The diff already updates its own reference page" is
not a reason to skip the search.
Name the page, and name the sentence that is now wrong or the list that is now missing an entry. If you cannot name both, you have a hunch, not a finding, and a hunch costs the author more than it saves.
Two habits produce weak findings:
One surface earns one item. Do not split a single change into a required item plus two nearby suggestions.
Every [ ] is work the author owes. Anything optional belongs in the
sentence under an item, or nowhere. An item that says "consider" or "not
strictly required" is not an item.
An item names a page, so it can always link that page. Give the published
URL, which is https://coder.com/docs/ plus the path with the docs/
prefix and the .md suffix removed. docs/ai-coder/ai-gateway/reference.md
becomes https://coder.com/docs/ai-coder/ai-gateway/reference.
Write the path in backticks so it is greppable, then link it, so a reader can open the page in one click:
- [ ] `docs/ai-coder/ai-gateway/reference.md` ([open](https://coder.com/docs/ai-coder/ai-gateway/reference)) - What needs to change
A page this pull request creates has no published URL yet. Name the path in backticks alone and say the page is new.
A relative docs link resolves against the repository in a comment and
404s. Write the path in backticks, or link the published page in full,
such as https://coder.com/docs/reference/api/enterprise.
Link an anchor only when that heading exists on the base branch today. A heading this pull request generates does not exist yet, so name the endpoint or section in words instead.
The comment ends with <!-- doc-check-sticky -->, on its own line, every
time. It is how the next review finds this comment instead of posting a
second one, and how the Slack notice knows a review had findings. A
comment without it reads as silence to everything downstream.
After you post or edit, read the comment back and confirm the marker is there. If it is not, edit the comment to add it.
Search the pull request for <!-- doc-check-sticky --> and edit that
comment instead of adding another. Search again immediately before you
post: a comment you wrote earlier in this same review counts, and reviews
of one pull request can overlap. Edit it, never post a second.
When a comment already exists, compare your findings against it. Check off
[x] items that are now addressed, strike through items the code reverted,
and add [ ] items for new gaps. If an item is checked but you cannot
verify the documentation landed, add a warning note below it. If nothing
meaningful changed, leave the comment alone.
Include only the sections that apply.
## Documentation Check
### Updates Needed
- [ ] `docs/path/file.md` ([open](https://coder.com/docs/path/file)) - What needs to change
- [x] `docs/other/file.md` ([open](https://coder.com/docs/other/file)) - This was addressed
- ~~`docs/removed.md` - No longer needed~~ *(reverted in abc123)*
### New Documentation Needed
- [ ] `docs/suggested/path.md` - What should be documented, on a page that does not exist yet
> ⚠️ *Checked but no corresponding documentation changes found in this PR*
---
*Automated review via [Coder Agents](https://coder.com/docs/ai-coder/agents)*
<!-- doc-check-sticky -->
Keep to this structure. Do not add sections it does not have, such as an evidence block. The evidence belongs in your answer, not in the author's comment.
The <!-- doc-check-sticky --> marker goes last, so the next review can
find this comment.
docs/reference/glossary.md needs a matching entry. See
Glossary and terminology below.Do not produce sticky-comment suggestions for these classes of change.
They have no user-visible documentation surface. When every changed file
falls in one of these classes, CI skips the review before this skill
runs, so a diff in front of you has already passed that gate or a
maintainer forced the review with the doc-check label. See
path-priors.md.
docs/reference/cli/. These are
generated from Go code under cli/; suggest edits to the CLI
definitions instead.If a diff is a mix of one of the above with a user-facing change, comment only on the user-facing portion.
docs/manifest/**/*.yml is the navigation structure; new pages MUST be
added to the right source file there. Each file holds one route and its
direct children, and include pulls in a child's own file. docs/manifest.json is compiled
from it by make gen/docs-manifest; don't edit the JSON directly.docs/reference/cli/*.md is auto-generated from Go code. Don't
edit directly.docs/.style/content-guidelines.md is the canonical source for
what belongs in the docs.Pages documenting staged features must include the applicable state in their route in docs/manifest/**/*.yml, such as state: [premium].
Do not add feature-state suffixes such as (Premium) or (Beta) to page titles or H1s.
The state is displayed in navigation metadata.
This is the canonical rule Evidence justifies a claim; it does not belong in the claim in the content guidelines; the content guidelines govern, so read the rule there. On a page this change adds or edits, flag an implementation identifier the reader neither types nor receives in that page's task, whether the diff adds the identifier or leaves it on a line this change touches; the canonical rule's ladder decides the replacement. Work from the page content in the diff. doc-check does not see commit messages or PR comments, so it does not police whether a stripped identifier was disclosed; that pointer is the author's to provide for the human reviewer. A pre-existing violation on a page the diff does not touch is not this change's finding; mention it as informational context at most, without demanding a fix from this author.
-- as punctuationThis applies in docs prose, code blocks, comments, and string literals.
Use commas, semicolons, or periods, or restructure the sentence. For
numeric ranges, use a plain hyphen (e.g., 0-100). The rule is enforced
by make lint/emdash, but the doc-check skill should also flag
violations it generates or suggests.
Redirects for coder.com/docs are configured in
docs/redirects.json in this repo, and the website rebuilds when the file
changes. When a doc page is renamed or moved:
docs/redirects.json that maps the old path to the new
one, in the same PR as the rename. For example:
{"source": "/docs/old/path", "destination": "/docs/new/path"}.Do not create a docs/_redirects file in this repo; that format isn't
processed by coder.com.
The glossary defines Coder-specific product and feature names, including collisions like the several senses of "agent". It drifts when the product's vocabulary changes and the page doesn't. Flag a glossary update when a change:
This is the canonical rule in Structural rules; the content guidelines govern. Don't flag generic lowercase concepts or internal-only identifiers with no user-facing surface; they don't earn a glossary entry.
Use GitHub-Flavored Markdown alerts:
> [!NOTE]
> Additional helpful information.
> [!WARNING]
> Important warning about potential issues.
> [!TIP]
> Helpful tip for users.
CLI docs in docs/reference/cli/ are auto-generated. Don't suggest
editing them directly. Changes should be made in the Go code that
defines the CLI commands (typically the cli/ directory).
Use sh for shell commands:
coder server --flag-name value
