Add gitbook skills

.agents/skills/cr-create/references/env.example

@@ -0,0 +1,11 @@
+# Copy to .env and fill in. .env is gitignored — never commit it.
+# The API-driven skills read TWO secrets from here (unlike the CLI skills, which
+# use the `gitbook2` auth store). Never print either value.
+
+# GitBook API token — the ONLY auth for the direct-API flow. Create one at
+# https://app.gitbook.com/account/developer and paste it here. Sent as
+# `Authorization: Bearer $GITBOOK_TOKEN` on every api.gitbook.com call.
+GITBOOK_TOKEN=gb_api_...
+
+# Slack notify is optional — only needed for the notify step (a curl POST to this webhook).
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

.agents/skills/cr-create/references/gitbook-review.config.json

@@ -0,0 +1,12 @@
+{
+  "spaceId": "",
+  "repo": "",
+  "branch": "main",
+  "slack": {
+    "mode": "webhook"
+  },
+  "demo": {
+    "existingPageId": "",
+    "newPageParentId": ""
+  }
+}

.agents/skills/write-docs/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: write-docs
+metadata:
+  version: "1.0"
+description: "Write, author, edit, and format GitBook documentation pages in Git-synced repos, IDEs, or any text editor. Use whenever a task involves creating or editing a GitBook markdown page, writing or updating a README.md or SUMMARY.md, inserting a hint, tab, stepper, card, or other GitBook block, configuring page frontmatter or layout options, setting up variables or expressions, or formatting content for GitBook outside the GitBook UI."
+---
+
+# GitBook Documentation Writing
+
+### When to Use This Skill
+
+Use this skill when working with GitBook documentation through:
+
+* Git-synced repositories (GitHub, GitLab)
+* Local markdown editors
+* IDE integrations
+* Any environment where you're editing GitBook content as files rather than through the GitBook UI
+
+### Quick Reference
+
+#### GitBook Content Structure
+
+GitBook organizes content through pages, spaces, and collections:
+
+* **Pages** are individual markdown files that make up your documentation
+* **Spaces** are collections of pages organized into a documentation site
+* **Collections** are groups of spaces
+
+**File structure:**
+
+```text
+/
+  .gitbook/
+    assets/              # GitBook-managed images and files
+    includes/            # Reusable content blocks
+    vars.yaml            # Space-level variables
+  .gitbook.yaml          # Configuration
+  README.md              # Homepage
+  SUMMARY.md             # Table of contents
+  getting-started/
+    installation.md
+    quickstart.md
+  api-reference/
+    authentication.md
+    endpoints.md
+```
+
+**Frontmatter fields (quick form):**
+
+```markdown
+---
+description: "Page description for SEO"
+icon: book-open
+hidden: true
+vars:
+  page_variable: value
+layout:
+  width: default  # or 'wide'
+  tableOfContents:
+    visible: true
+  pagination:
+    visible: true
+---
+```
+
+**Variables and expressions:**
+
+* Space variables: `/.gitbook/vars.yaml`
+* Page variables: Frontmatter `vars:`
+* Expression syntax: `<code class="expression">space.vars.variableName</code>`
+
+**Most common custom blocks:**
+
+* `{% tabs %}...{% endtabs %}` — for alternatives
+* `{% hint style="..." %}...{% endhint %}` — callouts (info/warning/danger/success)
+* `{% stepper %}...{% endstepper %}` — sequential steps
+* `<details>...<summary>...</details>` — expandable content
+
+**Links:**
+
+* External: `[text](https://example.com)`
+* Relative (same space): `[text](page.md)`, `[text](../folder/page.md)`
+* Cross-space (different space): `[text](https://app.gitbook.com/s/<spaceId>/<path>)` — relative paths never cross space boundaries, and this is the only correct URL form (not `/spaces/<id>/pages/<id>`). Get `<spaceId>` from `GET /orgs/{orgId}/spaces` and `<path>` from a page's `path` field in `GET /spaces/{spaceId}/content/pages`. Scaffolding a new site where the target space doesn't exist yet? Use `XSPACE_<KEY>` sentinels; `configure-site` resolves them after creation. Full examples: `references/markdown.md`.
+* Moved/renamed pages keep working — GitBook auto-creates a redirect from the old path.
+
+**Key reminders:**
+
+* Read SUMMARY.md first when working with existing content
+* Test in GitBook after editing locally
+* Keep SUMMARY.md synchronized with your file structure
+* OpenAPI specs must be uploaded via the UI, API, MCP, or CLI, not embedded in markdown
+
+### When to Use Which Block
+
+| Need | Use | Why |
+|---|---|---|
+| Sequential, ordered instructions | `{% stepper %}` | Clear step progression |
+| Alternative options (languages, platforms) | `{% tabs %}` | User chooses without page clutter |
+| Optional or detailed information | `<details>` | Keeps page scannable |
+| Important warnings or tips | `{% hint %}` | Colored callout (info/warning/danger/success) |
+| Side-by-side comparisons | `{% columns %}` | Parallel layout (max 2 columns) |
+| Timeline or changelog | `{% updates %}` | Dated entries with tag filtering |
+| Visual navigation cards | `<table data-view="cards">` | Clickable card grid |
+| Downloadable files | `{% file %}` | File with caption |
+| Call-to-action links | `<a class="button">` | Primary or secondary button |
+| Reusable content across pages | `{% include %}` | Single source of truth |
+| Dynamic content | `<code class="expression">` | Renders variable values |
+
+**Variable scope:**
+
+| If variable is... | Define in... | Access with... |
+|---|---|---|
+| Used across multiple pages | `/.gitbook/vars.yaml` | `space.vars.variableName` |
+| Specific to one page | Frontmatter `vars:` | `page.vars.variableName` |
+
+### Working with Existing Content
+
+1. **Read SUMMARY.md first** — complete table of contents and file hierarchy
+2. **If no SUMMARY.md** — browse the directory structure directly
+3. **Check .gitbook.yaml** — root path, custom README/SUMMARY locations, redirects
+4. **Check .gitbook/assets/** — uploaded images and files
+5. **Check .gitbook/vars.yaml** — space-level variables
+
+### Common Pitfalls
+
+**Cross-space links:**
+
+* Don't use relative paths to link to a page in a different space — they won't resolve.
+* Don't use `/spaces/<spaceId>/pages/<pageId>` — that's not a valid GitBook link form.
+* Use `https://app.gitbook.com/s/<spaceId>/<path>` instead, where `<path>` is the target page's `path` field (from `GET /spaces/{spaceId}/content/pages`), not its page ID.
+* Use `XSPACE_<KEY>` sentinels when space IDs aren't known yet (new space, not yet created).
+
+**File organization:**
+
+* Don't reference the same markdown file twice in SUMMARY.md
+* Keep file paths consistent between SUMMARY.md and actual file locations
+
+**Configuration:**
+
+* When using Git Sync, manage README.md only through your repository
+* Test redirects after moving or renaming files
+
+**Custom blocks:**
+
+* Always close blocks properly (`{% endtab %}`, `{% endhint %}`, etc.)
+* Match opening and closing tags exactly
+
+**Frontmatter:**
+
+* Always quote `description:` values containing `:`, `#`, or other YAML-significant characters — unquoted special characters cause silent Git Sync failures with no error message
+* Frontmatter must be at the very top of the file
+
+### Working with Git Sync
+
+When GitBook is synced with Git, changes flow in both directions — Git changes update GitBook, and GitBook UI changes commit back to Git. Merge conflicts are resolved in Git.
+
+**Best practices:** make structural changes via SUMMARY.md in Git; use branch-based workflows for significant updates; review auto-generated commits from GitBook.
+
+#### Choosing Git Sync vs. a change-request content push
+
+When a space has Git Sync configured and you have (or can get) a local checkout of the synced repo, **prefer editing the files directly and committing/pushing** — Git Sync propagates the change to GitBook. This holds even in an MCP session where a change-request content-push tool (e.g. `updateChangeRequestContent`) is available and connected: the tool being one call away isn't a reason to bypass Git as the source of truth. An agent that discovers it *can* push straight into a CR should still check whether Git Sync is set up and reachable before doing so.
+
+Reach for the change-request content-push path instead (MCP's `updateChangeRequestContent` or similar, or the REST `POST .../change-requests/<cr>/content` endpoint — see the `cr-create` skill) when:
+
+- the space has no Git Sync configured yet (e.g. a brand-new space still mid-setup),
+- there's no local Git checkout available in the current environment (no filesystem access to the synced repo), or
+- the change is small and targeted (a typo, one paragraph, one field) — opening a CR is proportionate, and a full clone/commit/push cycle isn't worth it for that.
+
+For anything larger — a new page tree, a multi-page rewrite, a migration — prefer Git Sync, even if that means pausing to confirm the repo is cloned locally first. Don't default to the change-request tool just because it's the first one that worked.
+
+Whichever path pushes the change, surface the CR's rendered site preview link (not just the editor/diff link) before wrapping up — see the `cr-create` skill's "Surfacing the preview link." It isn't part of the change-request response itself, so it's easy to forget.
+
+### Reference files
+
+Load these on demand when the task requires deeper detail:
+
+- `references/blocks.md` — full syntax and worked examples for every GitBook block type: tabs, steppers, hints, expandable, columns, updates, cards, embeds, files, buttons, icons, reusable content, and OpenAPI blocks. **Load when authoring non-trivial pages or when the quick-reference above isn't enough.**
+- `references/frontmatter.md` — all frontmatter fields with descriptions, YAML quoting rules, cover images, adaptive content (`if:`), and the variables/expressions deep-dive. **Load when configuring page layout, covers, conditional visibility, or variables.**
+- `references/markdown.md` — standard markdown, code blocks with titles, math/TeX, Mermaid diagram types and examples, and SVG handling quirks. **Load when working with diagrams, math, or SVG assets.**
+- `references/configuration.md` — `.gitbook.yaml` options, the `.gitbook/` directory structure (assets, includes, vars, tags), and SUMMARY.md grammar rules in full. **Load when setting up a space, adding redirects, or authoring/editing SUMMARY.md.**