Use when user-facing code changes need documentation, user says "update docs"/"document this"/"add to jamdesk docs", or after implementing APIs, CLI commands, or UI components.
Updates customer-facing documentation in external repositories (not CLAUDE.md). Locates docs via .jamdesk-docs-path, asks clarifying questions, writes documentation, and verifies with the jamdesk CLI. Learn more about Jamdesk on the Jamdesk homepage.
Announce: "I'm using the update-jamdesk skill to update your documentation."
Use when: User-facing changes to APIs, CLI commands, UI, config options, component behavior, or docs.json schema/features.
Skip when: Internal refactors, test-only changes, build/CI config, performance work without behavior change.
Right-size it: Not every change deserves a new page — a renamed config key is one edited line in an existing page, not a new doc.
Common mistake: Changes to docs.json format or config handling are user-facing. Even if the change was made inside the docs repo itself, ask: "Does this introduce or change a config pattern that customers use?" If yes, document it.
| Always | Never |
|--------|-------|
| Include frontmatter (title ≤ 60 chars, description 120-160 chars) | Create stub pages with "TODO" |
| Use built-in components first | Use mint.json (use docs.json) |
| Ask clarifying questions before writing | Skip verification |
| State prerequisites up front | Include secrets, tokens, or real customer data |
| Use active voice and action-oriented headings | Promise guarantees ("always works", "instant") |
| Include explicit warnings for destructive steps | Use "click here" link text |
| Flag | Behavior |
|------|----------|
| (none) | Full workflow: locate → clarify → analyze → write → verify → commit |
| --preview | Phases 1-3 only, describe changes without making them. Skip first-time config creation (report what you would create) and the branch-strategy question |
Find .jamdesk-docs-path by walking up from current directory to git root. It is a YAML file that lives at the git root of the code repo:
docs_path: ../customer-docs # Required - relative or absolute path
docs_branch: main # Optional - base branch for new feature branches, default: main
First-time setup: If config doesn't exist, ask user for their docs repo path and create the file at the git root. This only happens once per project. Point users to https://jamdesk.com/docs for help getting started with Jamdesk.
Preflight checks — resolve each failure before writing anything:
| Check | On failure |
|-------|-----------|
| docs_path exists | Re-ask the user for the path, update the config |
| Contains docs.json | If only mint.json exists, stop — tell the user to migrate to docs.json first |
| which jamdesk | CLI missing — continue, but use the manual verification checklist in Phase 5 |
| Docs working tree is clean | Stop and ask: stash, commit existing work, or proceed anyway. Never proceed silently onto a dirty tree |
Same-repo docs: If the docs live in the same git repo as the code, skip separate git operations entirely — stay on the current branch, include doc changes alongside the code change, and skip the branch-strategy question (Phase 2) and the commit menu (Phase 6).
Review conversation to identify what changed, then ask:
docs_branch (recommended), main, or current branch? If an unmerged docs branch from a previous run exists, surface it instead of silently creating a second one.Principle: Ask first, write later. 30-second clarification prevents 10-minute rework.
Search docs repo for existing coverage of the feature. Present findings:
Existing: getting-started.mdx mentions feature briefly
Missing: No dedicated page
Recommended:
1. Create: features/new-feature.mdx
2. Update: getting-started.mdx (add link)
Decision matrix:
| Scenario | Action |
|----------|--------|
| New feature | Create new page |
| Behavior change | Update existing page describing that behavior |
| Small addition | Add section to existing page |
| Major capability | New standalone page |
| Deprecation/removal | Update existing + add migration notes |
| Advanced usage | Add <Accordion> to existing page (keeps the page scannable for beginners) |
| New docs.json config/pattern | Update docs.json reference and/or navigation docs |
The rules below are the load-bearing standards — fetch https://jamdesk.com/docs only if you need something not covered here.
Content quality:
sk_test_xxxxVoice and tone:
| Rule | Example / note | |------|----------------| | Address the reader as "you" | "You can configure..." | | Refer to the product by name, never "we" | "Acme supports..." not "We support..." | | Present tense, active voice, direct instructions | "The command creates..." not "The command will create..." | | Use contractions | "don't", "isn't", "you'll" | | "must" for requirements, "can" for options | Never "should" for a requirement — use "must" or "we recommend" | | Cut "please", "simply", "just", "easily", "obviously" | If it were simple, the reader wouldn't need the page | | No Latin abbreviations | "for example" not "e.g.", "that is" not "i.e." | | No time-relative words | "currently", "new", "soon", "recently" go stale as docs age | | Don't anthropomorphize | "The server returns..." not "The server thinks..." | | Short sentences, no idioms | Write for a global audience | | Action-oriented headings | "Configure X", "Verify Y", "Troubleshoot Z" |
Anti-slop rules — these patterns read as AI-generated; remove on sight:
Mechanics:
<Warning> for destructive/irreversible stepsdescription. The description is for SEO meta tags; the opening paragraph should complement it with context, prerequisites, or what the reader will accomplish -- not repeat it.Page structure:
Page types:
Heading structure: Single H1 (page title in frontmatter), body sections start at H2. Sentence case (match the existing docs if they use title case), never skip levels, max depth H4. Give every H2/H3 at least one intro sentence before any list or sub-heading.
Minimal template:
---
title: Feature Name
description: SEO description (120-160 chars, unique per page)
lastUpdated: YYYY-MM-DD # Optional, for frequently-changing features - replace with today's actual date
---
What this does and why it's useful. Target audience: developers who need X.
## Prerequisites
- Node.js 18+
- API key from [Settings](/settings)
## Quick Start
\`\`\`bash
command --example
\`\`\`
## What's Next?
<Columns cols={2}>
<Card title="Related Feature" href="/related">
Continue with this
</Card>
<Card title="API Reference" href="/api">
Full API details
</Card>
</Columns>
Components: <Tabs>, <Steps>, <Accordion>, <Columns>, <Card>, <Note>/<Warning>/<Tip>, <CodeGroup>. There is no <Cards> component -- use <Columns cols={2}> with <Card> children. If you need a component not listed here, check https://jamdesk.com/docs/components
Images: Add screenshots when they aid understanding (UI walkthroughs, visual states) — skip them when text or code alone is clear. Store in /images/<feature>/, use absolute paths, always include alt text, avoid color-only cues.
Links: Relative paths, no .mdx extension, avoid orphan pages, link to source of truth (API spec, release notes).
API docs: Prefer OpenAPI auto-generation when available.
Navigation: Add new pages to docs.json navigation in alphabetical order unless the user has specified a different ordering or the existing structure suggests intentional grouping.
Maintenance: Use lastUpdated frontmatter for frequently-changing features. Mark or remove deprecated guidance promptly.
Renames and removals: When renaming, moving, or deleting a page, update every internal link to the old path and add a redirect if the docs.json schema supports it — never leave inbound links dangling. jamdesk broken-links must pass afterward (Phase 5).
With CLI (recommended):
jamdesk validate # Check docs.json schema
jamdesk broken-links # Find broken links
jamdesk dev starts a long-running local preview server — never run it in the foreground yourself. Offer it to the user for a visual check, or run it as a background command.
Without CLI (detected in Phase 1 preflight): Verify manually - code examples have language tags, frontmatter has title/description, links use correct paths (no .mdx), new pages added to docs.json.
Test code examples: Run commands and snippets where feasible before publishing — broken copy-paste examples are the most common docs complaint.
Fix errors before proceeding. If the user dislikes the changes, revert only the files this skill touched: git checkout -- <files you wrote>. Never suggest git checkout . — it discards all uncommitted work, including changes the user had in progress.
Same-repo docs: Skip this menu — the doc changes ride along with the code change's normal commit flow.
External docs repo: Present summary of changes, then ask user preference:
After commit, offer to push and create PR.
Commit format: docs: [action] [what] (e.g., docs: add webhook configuration guide)
| Situation | Action |
|-----------|--------|
| No config file | Ask user, create .jamdesk-docs-path |
| External repo | Feature branch, separate git ops |
| Same-repo docs | No separate git ops needed |
| --preview flag | Analyze only, no changes |
| CLI unavailable | Manual verification checklist |
User: Document the new webhook feature
Claude: I'm using the update-jamdesk skill...
Found docs at ../customer-docs
Branch strategy?
1. Feature branch (recommended)
2. Main
3. Current
User: 1
Claude: I'll create docs/webhooks. Scope look right?
User: Yes, also update API reference
[Writes docs, runs verification]
✓ validate passed
✓ broken-links passed
Files: webhooks/overview.mdx (new), api/reference.mdx (updated), docs.json (updated)
1. Commit to feature branch
2. Show diff first
3. Make additional changes
User: 1
Claude: Committed. Push and create PR?
Stop if you catch yourself:
docs.json--preview flag<Warning> on destructive stepsdescription as the opening paragraph (description echo)Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer