Update Docs Website Skill

Update Docs Website

This skill works in the nx repo only.

CRITICAL:

If you are not in the nx repo, say so and stop working!
If there are uncommitted/untracked files, say so and stop working!

Why two branches

Docs commits must land on BOTH:

website-<major> (e.g. website-23) - deploys nx.dev for the current major
the latest release branch <major>.<minor>.x (e.g. 23.1.x) - used for patch releases, and the release pipeline overwrites the website-<major> branch from it

If only website-23 gets the commit, the next patch release from 23.1.x wipes it.

How to Update

1. Determine the branches

The + on each refspec is required. A release force-pushes website-<major> from the release branch, so a non-forced fetch is rejected as non-fast-forward and leaves origin/website-<major> pointing at the pre-release commit.

git fetch origin '+refs/heads/master:refs/remotes/origin/master'
git fetch origin '+refs/heads/website-*:refs/remotes/origin/website-*'
git fetch origin '+refs/heads/*.x:refs/remotes/origin/*.x'

Website branch: highest origin/website-<N> where <N> is an integer. Exclude website-master and any branch with extra path segments (e.g. website-19-cherry-01/...).
```
git for-each-ref --format='%(refname:short)' 'refs/remotes/origin/website-*' \
  | grep -E '^origin/website-[0-9]+$' | sort -V | tail -1
```
Release branch: highest origin/<N>.<minor>.x with the SAME major <N> as the website branch.
```
git for-each-ref --format='%(refname:short)' 'refs/remotes/origin/*.x' \
  | grep -E "^origin/${MAJOR}\.[0-9]+\.x$" | sort -V | tail -1
```
If no release branch exists for that major, say so and continue with the website branch only.

Confirm the remote-tracking refs actually match the remote before touching them:

git ls-remote origin refs/heads/<website-branch> refs/heads/<release-branch>
git rev-parse origin/<website-branch> origin/<release-branch>

If the shas differ, the fetch did not take - stop and re-fetch. Every later step (the anchor commit, the cherry-pick list, any conflict) is wrong otherwise.

Report both branch names before doing any work.

2. Sync the branches

git checkout master && git reset --hard origin/master
git checkout <website-branch> && git reset --hard origin/<website-branch>
git checkout <release-branch> && git reset --hard origin/<release-branch>

3. Build the cherry-pick list (from the website branch)

On <website-branch>, get the last commit subject -> /tmp/last-website-commit.txt
Back on master, find the commit whose subject matches /tmp/last-website-commit.txt -> sha in /tmp/last-master-sha.txt
On master, list commits between that sha and HEAD, filtered to subjects starting with docs( or feat(nx-dev) -> /tmp/commits-to-cherry-pick.txt (oldest at bottom, as git log prints it)

4. Cherry-pick onto the website branch

On <website-branch>, oldest to newest:

git cherry-pick <sha>

On failure: record in /tmp/failed-website.txt, git cherry-pick --abort, move on.
If the pick is empty (already applied): git cherry-pick --skip, record as skipped.

5. Cherry-pick the SAME list onto the release branch

The release branch was cut from master at a different point, so some commits may already be there.

Skip any commit whose subject already appears in the release branch's log:
```
git log <release-branch> --format='%s' | grep -Fxq "<subject>"
```
Cherry-pick the rest oldest to newest, same rules as step 4.
- Failures -> /tmp/failed-release.txt
- Empty picks -> git cherry-pick --skip

Conflicts are more likely here than on the website branch - do NOT try to resolve them, just abort and report.

6. Report

Print a per-branch breakdown:

| Branch | Cherry-picked | Already present / skipped | Failed | | ------ | ------------- | ------------------------- | ------ |

List failed shas with subjects so they can be handled manually.

Do NOT push. End by reminding which branches have unpushed commits, e.g.:

git push origin website-23
git push origin 23.1.x

Agent Skills: Update Docs Website

Install this agent skill to your local

Skill Files