Terminal
Terminal/Skill
Lets a reviewer list GitBook docs change requests over the REST API, summarize what changed, and leave comments or verdicts.
By GitBook
Works with
npx skills add gitbookio/gitbook-skills --skill cr-reviewReview documentation change requests against a GitBook space or org entirely through the
GitBook REST API (https://api.gitbook.com/v1, hit with curl), so a reviewer never has
to leave Claude Code to find what needs review, understand what changed, and respond. This is
the reviewer-side companion to cr-create (the authoring side over the same API). The
reviewer flow is: discover → understand → comment → decide.
Because every step is a real HTTP call, never fake an output: if a call returns nothing, says nothing changed, or errors, report exactly that.
gbapi helperEvery call is a Bearer-authenticated request to https://api.gitbook.com/v1. The token lives
in GITBOOK_TOKEN in the repo-root .env (create one at
https://app.gitbook.com/account/developer). Never print the token; never write it to a
tracked file. Define this helper once per session and use it for every call below — it fails
loudly on any non-2xx and prints the API's error body (curl --fail-with-body, curl ≥ 7.76 /
stock on current macOS):
set -a; [ -f .env ] && . ./.env; set +a # load GITBOOK_TOKEN
gbapi() { # gbapi METHOD /path [extra curl args…]
local method="$1" apipath="$2"; shift 2 # NB: not `path` — in zsh that is tied to $PATH
curl -sS --fail-with-body -X "$method" \
"https://api.gitbook.com/v1${apipath}" \
-H "Authorization: Bearer ${GITBOOK_TOKEN}" \
-H "Content-Type: application/json" "$@"
}
Every response is JSON — pipe it through jq and read whole objects. Never hand-parse by
grepping/line-pairing fields — bind the wrong title↔id and every downstream call runs against
the wrong space/CR (a confident "0 comments" from a space that isn't the one you meant). If
gbapi exits non-zero, surface the printed error — do not report success.
<org>, <space>, <cr>, <pageId> are the relevant IDs. Base URL is
https://api.gitbook.com/v1; paths are relative to it.
| Step | Method + path | Notes |
|---|---|---|
| Who am I | GET /user | your own user ID is .id (for requestedReviewer=me) |
| Resolve a person → user ID | GET /orgs/<org>/members?search=<name|email> | match on user.displayName/user.email; the user ID is id (= user.id) |
| List orgs (to get IDs) | GET /orgs?limit=100 | .items[] → id, title |
| List spaces in an org | GET /orgs/<org>/spaces?limit=100 | .items[] → id, title |
| Discover CRs across an org | GET /orgs/<org>/change-requests?[status=][&creator=][&space=][&site=][&requestedReviewer=][&contributor=][&orderBy=] | |
| Discover CRs in a single space | GET /spaces/<space>/change-requests?[status=][&creator=][&requestedReviewer=] | status is effectively required — omitting it returns an empty list, not everything |
| CR detail | GET /spaces/<space>/change-requests/<cr> | subject, status, createdBy, comments, urls.app |
| Link to review the diff | use .urls.app straight from the list/get output — never construct a URL | |
| Link to the rendered preview | GET /spaces/<space> → .organization, then find the site behind the space, read its urls.published/urls.preview, and append /~/changes/<number>/ | urls.app is only the diff view — see "Surfacing the preview link" in the cr-create skill for the full resolution steps. A bare site URL is not a preview of the CR: without the ~/changes/ segment it renders the site's current content. Reviewers deciding approve/request-changes usually want the rendered result, not just the diff |
| Structural change summary | GET /spaces/<space>/change-requests/<cr>/changes | entries like page_created/page_edited with page.title, page.path. Payload is {changes, more} — read .changes, not .items |
| Per-page prose diff | CR side GET /spaces/<space>/change-requests/<cr>/content/page/<pageId>?format=markdown vs base GET /spaces/<space>/content/page/<pageId>?format=markdown, diffed client-side | input to a prose summary only — never paste this as a line-by-line diff; point the user at urls.app for the actual diff |
| Existing comments (context) | GET /spaces/<space>/change-requests/<cr>/comments?format=markdown&status=all | bodies at body.markdown; poster at postedBy.id; classify human vs gitbook:agent |
| Leave a comment (GATE) | POST /spaces/<space>/change-requests/<cr>/comments body {"body":{"markdown":"…"}} (opt. "page"/"node") | posts publicly, notifies the author |
| Submit a verdict (GATE) | POST /spaces/<space>/change-requests/<cr>/reviews body {"status":"approved"|"changes-requested"} (opt. "comment":{"markdown":"…"}) | records a real review |
| Existing reviews / your own | GET /spaces/<space>/change-requests/<cr>/reviews |
status on a review submission accepts exactly approved or changes-requested
(verified against the API enum ChangeRequestReviewStatus). This skill does not merge a CR
(POST …/merge) — merging changes shared state and is out of scope here.
authors notestatus, creator, space, site, requestedReviewer, contributor,
orderBy) are scalar query params and work directly. status takes a single value
(draft/open/archived/merged) — for "any state," union client-side. Omitting status
returns an empty list rather than everything, so always pass one. Default triage
discovery to status=open, but never filter to open when the user asks for the "latest"
or "most recent" CR — a space's newest CR is often a draft.authors filter does work over the raw API (…/comments?authors=<id>,
repeatable). Even so, to split human vs agent you pull all comments and classify on
postedBy.id (a filter narrows, it doesn't classify).GET /user yields your .id directly — pipe every
response through jq.authors server-side filter is available (see above).limit, and paginate with the response's next.page cursor passed as
page= — it is not an integer offset, so page=1 returns HTTP 400. Do this before
concluding "not found."curl and jq on your PATH, and network access to api.gitbook.com.GITBOOK_TOKEN in the repo-root .env (see "Auth"). Confirm with gbapi GET /user
before running actions.GET /orgs and GET /orgs/<org>/spaces give IDs.creator/requestedReviewer take IDs, not
names. Resolve a name/email with GET /orgs/<org>/members?search=… first.gbapi errors, surface the error body. The
diff link must be the API's urls.app, not a hand-built URL.urls.app opens the diff GitBook
itself renders (word-level, syntax-aware, split-view where the org has it enabled) — treat it
as the diff of record for the CR. The per-page markdown fetch-and-compare in "Summarizing a
CR" exists only to inform a prose summary of what changed — never paste a raw unified /
line-by-line diff into chat as a substitute for it.urls.app — it lives on
the Site object (urls.preview), not on the change request, so it's easy to forget it
exists. See "Summarizing a CR."GET /orgs,
GET …/spaces, and the CR-list calls return a capped page with no total / "more" indicator.
Raise limit (and paginate with the next.page cursor as page=, not an integer) and search the full set before telling the user
something doesn't exist.title/subject matches what the user named before
reporting counts or comments — a wrong-ID lookup returns believable, empty results.POST …/comments (posts a public comment)POST …/reviews (records an approve / request-changes verdict)
Discovering, summarizing, and reading comments need no gate.creator/requestedReviewer filter. Resolve the name
via members?search= and, if there's more than one match (or none), show the candidates and
confirm who before filtering. Don't guess from the member list.status=open). A CR list won't include merged/closed items
unless you pass status explicitly — do so when the user wants those too.gbapi GET /user | jq '{id, displayName, email}' # confirm auth + your OWN user ID
gbapi GET "/orgs?limit=100" | jq -r '.items[] | "\(.id)\t\(.title)"' # org IDs
gbapi GET "/orgs/<org>/spaces?limit=100" | jq -r '.items[] | "\(.id)\t\(.title)"' # space IDs in an org
Raise limit, and paginate with the next.page cursor as page= (not an integer), before concluding "not found."
<org>, <space>, <cr>, <pageId> below are the relevant IDs.
# Resolve a person to a user ID (for creator / requestedReviewer)
gbapi GET "/orgs/<org>/members?search=ada@example.com" \
| jq -r '.items[] | "\(.id)\t\(.user.displayName)\t\(.user.email)"'
# → match on user.displayName / user.email; the user ID is `id`
# Discover CRs across an org — open ones, optionally narrowed by creator/space
gbapi GET "/orgs/<org>/change-requests?status=open" | jq '.items'
gbapi GET "/orgs/<org>/change-requests?status=open&creator=<userId>" | jq '.items'
gbapi GET "/orgs/<org>/change-requests?status=open&space=<space>" | jq '.items'
ME=$(gbapi GET /user | jq -r .id)
gbapi GET "/orgs/<org>/change-requests?requestedReviewer=$ME" | jq '.items' # "assigned to me"
# Discover CRs in a single space
gbapi GET "/spaces/<space>/change-requests?status=open" | jq '.items'
# Inspect one CR (subject, status, author, comment count, app link)
gbapi GET "/spaces/<space>/change-requests/<cr>" \
| jq '{number, subject, status, author: .createdBy, comments, url: .urls.app}'
# Summarize what changed — structural first
gbapi GET "/spaces/<space>/change-requests/<cr>/changes" | jq '.'
# → page_created / page_edited entries with page.title and page.path
# Optional deeper per-page prose diff: CR content vs base content
gbapi GET "/spaces/<space>/change-requests/<cr>/content/page/<pageId>?format=markdown" # CR side
gbapi GET "/spaces/<space>/content/page/<pageId>?format=markdown" # base side
# diff the two markdown blobs client-side
# Read existing comments for context (classify on postedBy.id)
gbapi GET "/spaces/<space>/change-requests/<cr>/comments?format=markdown&status=all" | jq '.items'
# Leave a comment (GATE)
gbapi POST "/spaces/<space>/change-requests/<cr>/comments" \
--data '{"body":{"markdown":"Looks good — one nit on the retry section."}}' | jq '.'
# add "page":"<pageId>" (or "node":"<nodeId>") in the body to anchor the comment
# Submit a verdict (GATE)
gbapi POST "/spaces/<space>/change-requests/<cr>/reviews" --data '{"status":"approved"}' | jq '.'
gbapi POST "/spaces/<space>/change-requests/<cr>/reviews" --data '{"status":"changes-requested"}' | jq '.'
# optionally include "comment":{"markdown":"…"} in the same body
requestedReviewer=$ME; get your ID from GET /user).GET /orgs/<org>/members?search=. If the search
returns more than one match — or none — surface the candidates and confirm before filtering.
Never auto-pick.status=open by default) and present a compact table, one row per CR:
number · subject · author (createdBy.displayName) · status · #comments (comments) · last
updated (updatedAt) · the app URL (urls.app).…/changes lists each changed page as page_created /
page_edited (with page.title and page.path) — enough for a "3 pages edited, 1 new page"
overview.…/change-requests/<cr>/content/page/<pageId>?format=markdown) and the base-side markdown
(…/spaces/<space>/content/page/<pageId>?format=markdown) and diff them client-side as
input to a prose summary, not as output. Use the comparison to describe what changed
("rewrote the intro, added a troubleshooting section") — don't paste the raw unified /
line-by-line diff into chat; GitBook's own diff (urls.app, see step 3) is the diff of record
and is always the better way to actually see the change. Caveat: a markdown round-trip
can re-escape multi-line integration blocks (e.g. a {% @mermaid/diagram %} block) — don't
report such re-escaping as a real authored change; eyeball multi-line integration blocks
before flagging them.urls.app — as the place to actually see the
diff (mention the split-diff view if the org has it enabled); the prose summary from step 2
supplements that link, it doesn't replace it. Also resolve and include the site preview
link (urls.preview on the Site behind this space — see cr-create's "Surfacing the
preview link") when one exists, so the user can see the rendered docs, not just the diff. If
the space isn't attached to a published site, say so rather than silently omitting it.postedBy.id == "gitbook:agent", advisory) separately from human comments.page/node), a specific page ("page":"<pageId>"), or a specific block ("node":"<nodeId>").POST …/comments (gate — it's public and notifies the author).id / URL). Don't claim it posted if
the call errored.approved or changes-requested) and whether the user also wants a
summary comment (either post it first via "Leaving a comment," or include "comment":{"markdown":"…"}
in the review body).POST …/reviews with {"status":"<verdict>"} (gate — records a real review and notifies the
author). Report the result verbatim.requested-reviewers list into reviews. So if a CR shows zero requested reviewers, it may
simply mean reviews are already in — check GET …/reviews.curl + jq and the gbapi helper perform every action in this skill. There is no helper
script and no CLI.cr-create skill for the authoring side over the API (create a
CR, push content, request reviewers, notify Slack, fix/resolve comments) — its .env /
GITBOOK_TOKEN setup, the human-vs-agent comment split, and the markdown round-trip caveat are
documented there in more depth.