Update Jamdesk

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.

Critical Rules

Flags

Phase 1: Locate Documentation

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:

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).

Phase 2: Clarify Scope

Review conversation to identify what changed, then ask:

1. Branch strategy (external docs repo only — skip if same-repo): Feature branch created from 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.
2. Scope confirmation: "I plan to [create/update] these pages: ... Any changes?"
3. Additional context (if needed): Terminology, related features, edge cases

Principle: Ask first, write later. 30-second clarification prevents 10-minute rework.

Phase 3: Analyze Existing Docs

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:

Phase 4: Write Documentation

The rules below are the load-bearing standards — fetch https://jamdesk.com/docs only if you need something not covered here.

Content quality:

• Explain why, not just what
• Show the simplest working example first
• Use concrete, realistic values in examples, not placeholders (readers learn faster from examples they can copy-paste) — but anything secret-shaped (API keys, tokens, passwords) must be obviously fake, e.g. sk_test_xxxx
• Show expected output after commands so readers can confirm they're on track
• One concept per section, 3-7 subsections per page
• Define terms once and reuse consistently

Writing quality:

• Active voice, direct instructions
• Short sentences, avoid idioms (global audiences)
• Action-oriented headings ("Configure X", "Verify Y", "Troubleshoot Z")
• Descriptive link text (never "click here")
• Include \x3CWarning> for destructive/irreversible steps
• No description echo: The opening paragraph MUST say something different from the frontmatter description. 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:

1. Opening paragraph (what + why + target audience)
2. Prerequisites (tools, access, versions)
3. Quick Start (simplest example)
4. Configuration/Details
5. Examples (basic → advanced)
6. Troubleshooting (optional — common errors and fixes; errors hit while building the feature are good candidates)
7. What's Next (2-4 related links)

Page types:

• Task pages: Step-by-step procedure with numbered steps
• Reference pages: Minimal example first, then expand with details
• Concept pages: Explain how something works and why (architecture, mental models) — link to task pages for the steps

Heading structure: Single H1 (page title in frontmatter), body sections start at H2.

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?

\x3CColumns cols={2}>
  \x3CCard title="Related Feature" href="/related">
    Continue with this
  \x3C/Card>
  \x3CCard title="API Reference" href="/api">
    Full API details
  \x3C/Card>
\x3C/Columns>

Components: \x3CTabs>, \x3CSteps>, \x3CAccordion>, \x3CColumns>, \x3CCard>, \x3CNote>/\x3CWarning>/\x3CTip>, \x3CCodeGroup>. There is no \x3CCards> component -- use \x3CColumns cols={2}> with \x3CCard> 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/\x3Cfeature>/, 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.

Phase 5: Verify

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 -- \x3Cfiles you wrote>. Never suggest git checkout . — it discards all uncommitted work, including changes the user had in progress.

Phase 6: Commit

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:

1. Commit to feature branch
2. Show diff first
3. Make additional changes

After commit, offer to push and create PR.

Commit format: docs: [action] [what] (e.g., docs: add webhook configuration guide)

Quick Reference

Example

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?

Red Flags

Stop if you catch yourself:

• Skipping clarifying questions
• Creating pages without updating docs.json
• Using full URLs for internal links
• Adding images without alt text
• Making changes with --preview flag
• Including secrets, tokens, or real customer data
• Using "click here" or vague link text
• Missing \x3CWarning> on destructive steps
• Leaving deprecated content without marking it
• Copying the frontmatter description as the opening paragraph (description echo)