skills: assess documentation impact and fit before adding content (#26388)

Documentation updates can be technically accurate yet unnecessary,
duplicated, or poorly placed. Update research to justify an edit through
the reader's task and a specific documentation gap, write to integrate
it into the existing page, and review-changes to assess reader value,
placement, and flow.

Keep the guidance in the existing skills, without a required reporting
template. Each skill update has its own commit.

Markdown checks pass; Vale reports only pre-existing findings outside
the edited lines. Skill validation passes after excluding unchanged
Claude-specific metadata unsupported by the Codex validator.

Generated by Codex

.agents/skills/research/SKILL.md

@@ -11,9 +11,9 @@ description: >
 
 # Research
 
-Thoroughly investigate the topic at hand and produce a clear plan for
-the fix. The goal is to identify exact files, named targets within those
-files, and the verified content needed for the fix.
+Investigate the topic and determine whether documentation needs to change.
+When an update is warranted, identify exact files, named targets within
+those files, and the verified content needed.
 
 ## 1. Gather context
 
@@ -65,15 +65,34 @@ plan a fix based on an unverified claim.
 If the fix requires a replacement URL and that URL cannot be verified (e.g.
 network restrictions), report it as a blocker rather than guessing.
 
-## 6. Check the live site (if needed)
+## 6. Assess documentation impact
+
+A code change or release-note entry is evidence to investigate, not a reason
+by itself to add documentation. Identify the reader's task and what the
+change alters about it. Recommend an update when existing guidance becomes
+incorrect, leaves a gap in that task, or omits a capability useful to readers.
+An implementation fix may need no update if the docs already describe the
+intended behavior.
+
+For each recommended update, connect the reader's task, the documentation
+gap, the destination page and section, and the proposed treatment. Prefer
+correcting existing prose or examples when they serve that task. Check related
+pages for contradictions, without assuming each needs the same explanation.
+
+If there is no clear home, reconsider the value and scope before proposing a
+section or page. A separate home can be justified by a distinct reader task,
+not by the need to place a release-note bullet. "No documentation change" is
+a valid finding; explain it briefly when assessing a set of changes.
+
+## 7. Check the live site (if needed)
 
 For URL or rendering issues, fetch the live page:
 
-```
+```text
 https://docs.docker.com/<path>/
 ```
 
-## 7. Report findings
+## 8. Report findings
 
 Summarize what you found — files to change, the specific problem in each,
 what the fix should be, and any constraints. This context feeds directly

.agents/skills/review-changes/SKILL.md

@@ -82,6 +82,18 @@ context:
 - Would a reader be confused by anything the change introduces or leaves
   out?
 
+Accuracy alone doesn't justify an addition. For each substantive addition, ask:
+
+- Does it help readers act, choose, or understand a consequence?
+- Does it belong under this heading and at this point in the explanation?
+- Does it interrupt a procedure, example, or explanation already in progress?
+- Is the detail proportional to its value here, or would a link suffice?
+- Would removing it improve the page without losing necessary guidance?
+
+Recommend shortening, moving, or deleting accurate text when it doesn't serve
+the page's task. When reviewing multiple commits, check both each change in
+context and the combined diff for repeated explanations.
+
 ## 6. Review code and template changes
 
 For non-Markdown changes (JS, HTML, CSS, Hugo templates):
@@ -102,6 +114,7 @@ accurate.
 - There is a factual error or contradiction (on-page or cross-page)
 - A cross-reference is broken or misleading
 - A reader would be confused
+- An addition duplicates guidance or disrupts the page without enough reader value
 
 When requesting changes, be specific: quote the exact text that is wrong,
 explain why, and suggest the correct fix.

.agents/skills/write/SKILL.md

@@ -64,6 +64,17 @@ Always read each file before modifying it. Make the minimal change that
 fixes the issue. Do not improve surrounding content, add comments, or
 address adjacent problems.
 
+Before drafting an addition, identify the reader's task and read the destination
+section with the surrounding content. Choose where the information fits and
+whether to correct prose, replace an example, or extend the explanation.
+Related subject matter alone doesn't make a section an appropriate home.
+
+Explain current behavior in terms of what readers need to do, choose, or
+understand. Keep detail proportional to that need. Give each explanation a
+clear home; elsewhere, include only the context needed for that page's task
+and link to the fuller explanation. Don't interrupt a procedure, example, or
+explanation to insert a related fact.
+
 Follow the writing guidelines in CLAUDE.md, STYLE.md, and COMPONENTS.md.
 
 ## 3. Front matter check