docs: prune learnings section and tighten create-pr skill

.agents/skills/create-pr/SKILL.md

@@ -12,23 +12,41 @@ Push the branch and create a properly structured pull request.
 
 ## 1. Verify the branch
 
+Confirm you're on a dedicated branch, not the default branch:
+
+```bash
+git branch --show-current   # must not be main or master
+```
+
+If this returns `main` or `master`, stop. Create a branch and move your
+commits onto it before continuing.
+
+Confirm commits exist and the working tree is clean:
+
 ```bash
 git log --oneline main..HEAD   # confirm commits exist
-git diff --quiet               # confirm no unstaged changes
+git status --porcelain         # must print nothing
 ```
 
+If `git status --porcelain` prints anything, there are uncommitted or
+unstaged changes. Stop and commit them — or unstage stray files like
+`package-lock.json` — before opening a PR. Don't open a PR mid-edit.
+
 ## 2. Push the branch
 
-Confirm origin points to your fork, not upstream:
+Identify the remote that points at your fork. Inspect the remotes:
 
 ```bash
-git remote get-url origin
+git remote -v
 ```
 
-Then push:
+If `origin` is your fork, use it. If `origin` points at canonical
+`docker/docs` (the upstream), push to your separate fork remote instead —
+never push the branch to `docker/docs` directly:
 
 ```bash
-git push -u origin <branch-name>
+FORK_REMOTE=origin   # or the name of your fork remote if origin is upstream
+git push -u "$FORK_REMOTE" <branch-name>
 ```
 
 ## 3. Create the PR
@@ -46,10 +64,10 @@ duplicate PR; report the existing PR instead. Only proceed if there is no open
 linked PR, or if the existing PR clearly does not address the issue and you
 explain why in the new PR body.
 
-Derive the fork owner dynamically:
+Derive the fork owner dynamically from the same fork remote you pushed to:
 
 ```bash
-FORK_OWNER=$(git remote get-url origin | sed -E 's|.*[:/]([^/]+)/[^/]+(\.git)?$|\1|')
+FORK_OWNER=$(git remote get-url "$FORK_REMOTE" | sed -E 's|.*[:/]([^/]+)/[^/]+(\.git)?$|\1|')
 ```
 
 ```bash
@@ -68,31 +86,54 @@ EOF
 )"
 ```
 
+Prefix the title with the change type to match repo convention — `docs:` for
+documentation changes (or another scope like `hub:` when appropriate), for
+example `docs: fix broken link on install page`.
+
 Keep the body short. Reviewers need to know what changed and why — nothing
 else. Do **not** add a "Test plan" section — documentation PRs don't need one.
 
 Use an accurate disclosure footer that names the active coding agent, for
 example `Generated by Codex` or `Generated by Claude Code`.
 
-### Optional: Learnings section
+### Optional: Netlify preview entry path
 
-If while working on this PR you discovered something non-obvious about the
-repo — a convention not documented in AGENTS.md, a gotcha that tripped you
-up, a pattern that should be codified — add a Learnings section to the PR
-body:
+If the PR primarily edits a single page or a focused section of pages, add a
+`@netlify` stanza to the PR body (for example, just below the Summary). This
+sets the entry path for the Netlify deploy preview so reviewers land on the
+edited page instead of the site root:
 
 ```markdown
-## Learnings
+@netlify /desktop/setup/install/
+```
+
+The stanza takes a single published URL path. Derive it from the source file
+path: drop the `content/` prefix and `.md` suffix, strip the `/manuals`
+segment, and add a trailing slash. For example,
+`content/manuals/desktop/setup/install/mac-install.md` becomes
+`/desktop/setup/install/mac-install/`.
+
+Only add this when the change is focused on one page or section. Skip it for
+PRs that touch many unrelated pages — there is no useful single entry path.
+
+### Optional: Preview links
+
+When the change is focused, also add direct links to the deploy preview in the
+PR body so reviewers can jump straight to the affected pages. The preview URL
+embeds the PR number:
 
-- <what you learned and why it matters>
 ```
+https://deploy-preview-<pr-number>--docsdocker.netlify.app/path/to/page/
+```
+
+The PR number isn't known until `gh pr create` returns, so add these links
+after creating the PR by updating the body:
 
-Add this section between the Summary and the `Closes` line. Only include
-learnings that would help future contributors avoid the same issue. Do not
-include things already documented in AGENTS.md or STYLE.md.
+```bash
+gh pr edit <pr-number> --repo docker/docs --body "..."
+```
 
-The weekly PR learnings scanner reads these sections to surface recurring
-patterns for the team to codify.
+Use the same source-path-to-URL mapping as the `@netlify` stanza above.
 
 ## 4. Apply labels and request review