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.

intent

use this skill when user-facing code changes need documentation: after implementing APIs, CLI commands, UI components, config options, or schema changes. triggers on explicit requests like "update docs", "document this", "add to jamdesk docs", or "docs are outdated", and also proactively after feature work that changes user-facing behavior, even if the user doesn't ask. skip for internal refactors, test-only changes, build/CI config, or performance work without behavior changes.

inputs

external connections:

• jamdesk CLI (optional but recommended): verify at which jamdesk. if present, enables automated validation (Phase 5). if missing, fall back to manual verification checklist. install via https://jamdesk.com/docs.
• git repo (required): code repo with .jamdesk-docs-path config at git root.
• docs repo (required): customer-facing docs referenced in .jamdesk-docs-path, contains docs.json (not mint.json).

config file (.jamdesk-docs-path): located at git root of code repo. YAML format:

docs_path: ../customer-docs    # Required - relative or absolute path to docs repo
docs_branch: main              # Optional - base branch for feature branches, default: main

context from conversation:

• description of user-facing changes (APIs, commands, UI, config, behavior).
• existing documentation coverage (search results, related pages).
• user preference for branch strategy (feature branch, main, current).

flags:

• --preview: analyze only (Phases 1-3), describe changes without writing. skip first-time config creation (report what you'd create instead) and branch-strategy question. do not make any file changes.

procedure

Phase 1: Locate Documentation

1. walk up from current directory to git root.
2. check for .jamdesk-docs-path file at git root.
3. if file missing, ask user: "what's the path to your docs repo?" (relative or absolute). create .jamdesk-docs-path at git root with user's input. point to https://jamdesk.com/docs for first-time setup help.
4. parse docs_path and docs_branch from config.
5. verify docs_path exists. if not, re-ask user and update config.
6. verify docs.json exists in docs_path. if only mint.json exists, stop with message: "your docs use mint.json. migrate to docs.json first." see https://jamdesk.com/docs for migration guide.
7. check which jamdesk. if not found, note that manual verification (Phase 5) will be needed.
8. check docs working tree status. if dirty (uncommitted changes), ask user: "docs repo has uncommitted work. stash, commit, or proceed anyway?" do not proceed silently on dirty tree.
9. if docs live in same git repo as code (same-repo docs), note this and skip separate git operations in later phases (Phases 2, 6).

output of Phase 1:

• .jamdesk-docs-path exists and is valid.
• docs_path and docs_branch values confirmed.
• working tree status resolved.
• flag set: same-repo docs (yes/no), CLI available (yes/no).

Phase 2: Clarify Scope

1. review conversation to identify what changed (new feature, behavior change, deprecation, etc.).
2. if external docs repo only (not same-repo), ask: "which branch strategy? (1) feature branch from docs_branch (recommended), (2) main, (3) current branch?" check for unmerged branches from previous runs and surface one instead of creating duplicate.
3. ask: "i plan to [create/update] these pages: [list]. any changes?"
4. if needed, ask clarifying questions: terminology, related features, edge cases, whether docs.json config/navigation changes are needed.

output of Phase 2:

• branch strategy chosen (external docs repo only).
• page scope confirmed (create/update list).
• terminology and edge cases clarified.

Phase 3: Analyze Existing Docs

1. search docs_path for existing coverage of the feature (use keywords from Phase 2).
2. present findings:
   • "Existing: [pages that mention feature]"
   • "Missing: [what's not covered]"
   • "Recommended: [create new/update existing/add section]"
3. use decision matrix (below, under decision points) to recommend action.
4. if --preview flag set, describe what you'd create without writing files. report what docs.json entries you'd create.

output of Phase 3:

• existing docs inventory.
• recommended pages to create or update.
• proposed docs.json changes.

Phase 4: Write Documentation

1. for each page (new or update):
   • start with frontmatter: title (≤60 chars), description (120-160 chars, unique, SEO-focused), optional lastUpdated: YYYY-MM-DD for frequently-changing features.
   • opening paragraph: explain what this does, why it's useful, target audience. must be different from frontmatter description (no description echo).
   • structure: prerequisites, quick start, configuration/details, examples (basic to advanced), troubleshooting (optional), what's next.
   • use action-oriented headings ("Configure X", "Verify Y", "Troubleshoot Z").
   • write in active voice, short sentences. avoid idioms (global audiences).
   • show simplest working example first. use concrete, realistic values in examples (readers copy-paste). mask secrets as obviously fake: sk_test_xxxx, api_key_here, etc.
   • include expected output after commands so readers can confirm progress.
   • define terms once, reuse consistently.
   • include <Warning> components for destructive/irreversible steps.
   • use descriptive link text (never "click here"). use relative paths without .mdx extension.
   • add images only when they aid understanding (UI walkthroughs, visual states). store in /images/<feature>/, use absolute paths, include alt text.
   • one concept per section, 3-7 subsections per page.
2. add or update pages in docs repo.
3. update docs.json navigation: add new pages in alphabetical order unless user specified different ordering or existing structure suggests intentional grouping.
4. if same-repo docs, keep changes on current branch (no separate branch operations).

output of Phase 4:

• .mdx files written to docs_path.
• docs.json updated with new pages/nav entries.
• all code examples tested and functional.

Phase 5: Verify

1. if jamdesk CLI available:
   • run jamdesk validate to check docs.json schema.
   • run jamdesk broken-links to find broken links.
   • fix any errors before proceeding.
2. if CLI unavailable, verify manually:
   • code examples have language tags.
   • frontmatter includes title and description.
   • links use relative paths without .mdx extension.
   • new pages added to docs.json.
   • no orphan pages (all new pages linked from navigation or other pages).
3. test code examples: run commands and snippets where feasible. broken copy-paste examples are the most common docs complaint.
4. if user dislikes changes, revert files this skill touched: git checkout -- <filenames>. never suggest git checkout . (discards user's other work).
5. if --preview flag set, skip this phase.

output of Phase 5:

• validation passed (or manual checks passed).
• code examples tested.
• all links valid.
• ready to commit.

Phase 6: Commit

1. if same-repo docs, skip this phase (doc changes ride along with code change's normal commit flow).
2. if external docs repo:
   • present summary: "Files changed: [list]. Pages created: [list]. Pages updated: [list]. Navigation updated: [yes/no]."
   • ask user preference: "(1) commit to feature branch, (2) show diff first, (3) make additional changes"
   • on choice (1): commit with format docs: [action] [what] (e.g., docs: add webhook configuration guide). offer to push and create PR.
   • on choice (2): show git diff. return to menu above.
   • on choice (3): return to Phase 4 for edits.

output of Phase 6:

• commit created on feature branch (external repo).
• PR created (optional, user consent).
• or changes ready for user's normal commit flow (same-repo).

decision points

Phase 1: Config file missing

• if .jamdesk-docs-path does not exist, ask user for docs path and create file. this only happens once per project.

Phase 1: Docs validation failures

Check	On failure	Action
docs_path exists	path invalid or wrong	re-ask user, update config
docs.json present	only mint.json exists	stop, user must migrate to docs.json first
which jamdesk	CLI missing	continue with manual verification in Phase 5
working tree clean	uncommitted changes in docs repo	ask user: stash, commit, or proceed anyway. do not proceed silently.

Phase 1: Same-repo docs detection

• if docs live in same git repo as code, skip separate git operations in Phases 2 and 6. doc changes stay on current branch, no branch-strategy question.

Phase 2: Branch strategy (external docs repo only)

• if docs are in same repo as code, skip this question.
• if docs are in external repo, offer: (1) feature branch from docs_branch (recommended), (2) main, (3) current branch.
• if unmerged feature branch from previous run exists, surface it instead of creating new branch.

Phase 3: What to create/update (decision matrix)

Scenario	Action
new feature, no existing coverage	create new dedicated page
behavior change on existing feature	update existing page describing that behavior
small addition to existing feature	add section to existing page (do not create new page)
major new capability	create new standalone page
deprecation or removal	update existing page + add migration/upgrade notes section
advanced usage pattern	add <Accordion> to existing page (keeps page scannable for beginners)
new docs.json config pattern or schema change	update docs.json reference page and/or update navigation docs

Phase 4: Image inclusion

• if screenshot aids understanding of UI workflow or visual states, include it.
• if text or code alone is clear, skip image.
• store images in /images/<feature>/, use absolute paths, always include alt text.

Phase 4: Component availability

• use built-in components first: <Tabs>, <Steps>, <Accordion>, <Columns>, <Card>, <Note>, <Warning>, <Tip>, <CodeGroup>.
• no <Cards> component exists. use <Columns cols={2}> with <Card> children instead.
• if needed component not listed, check https://jamdesk.com/docs/components.

Phase 4: Navigation ordering

• add new pages to docs.json in alphabetical order unless user specified different ordering.
• if existing structure suggests intentional grouping (not alphabetical), follow that pattern.

Phase 5: CLI availability

• if jamdesk CLI found, run jamdesk validate and jamdesk broken-links.
• if CLI not found, do manual verification: frontmatter validity, link format, schema compliance, no orphans.

Phase 5: Revert on user dissatisfaction

• if user dislikes changes, revert files this skill touched: git checkout -- <filenames>.
• never run git checkout . (destroys user's other uncommitted work).

Phase 6: Same-repo vs external repo

• if same-repo docs, skip entire Phase 6. doc changes go into normal code change commit flow.
• if external docs repo, follow full Phase 6 workflow: summarize, ask commit preference, commit, offer push/PR.

Flag: --preview

• analyze only, do not write files.
• skip first-time config creation (report what you'd create).
• skip branch-strategy question.
• describe Phase 3 recommendations without acting.
• report proposed docs.json entries without adding them.
• skip Phases 4, 5, 6.

output contract

Phase 1 success:

• .jamdesk-docs-path exists at git root and is valid (parseable YAML, docs_path points to directory with docs.json).
• working tree status resolved (clean or user approved dirty state).

Phase 2 success:

• branch strategy chosen and confirmed (external repo) or skipped (same-repo).
• page scope (create/update list) confirmed.
• clarifying questions answered.

Phase 3 success:

• existing coverage inventory provided.
• recommended actions listed with rationale.

Phase 4 success:

• all .mdx files written to correct paths in docs_path.
• frontmatter (title, description) valid for each page.
• opening paragraph differs from frontmatter description.
• all code examples tested and include expected output.
• docs.json updated with new pages in correct section, alphabetical order (unless otherwise specified).
• all links relative, no .mdx extensions, no broken links.
• images (if used) stored in /images/<feature>/, absolute paths, alt text present.
• no secrets, tokens, or real customer data in docs.

Phase 5 success:

• jamdesk validate passed (if CLI available) or manual checks passed.
• jamdesk broken-links passed (if CLI available).
• code examples tested and functional.
• no orphan pages.

Phase 6 success (external repo):

• commit created on feature branch with format docs: [action] [what].
• commit message references changed files and pages.
• push and PR offered to user.

Phase 6 success (same-repo):

• phase skipped, no separate git operations.

--preview flag success:

• Phases 1-3 completed.
• summary provided of what would be created/updated without writing files.

outcome signal

• user announces: "I'm using the update-jamdesk skill to update your documentation."
• Phase 1 complete: user sees "docs config located at [path], working tree clean" or "config created, ready to proceed."
• Phase 2 complete: user sees scope confirmation ("i plan to create/update...") approved.
• Phase 3 complete: user sees analysis of existing coverage and recommended actions.
• Phase 4 complete: user sees list of files written (e.g., "webhooks/overview.mdx created, api/reference.mdx updated, docs.json updated").
• Phase 5 complete: user sees validation results ("✓ validate passed", "✓ broken-links passed") or manual checklist results.
• Phase 6 complete (external): user sees commit summary and prompt: "commit to feature branch?", then "push and create PR?" after commit succeeds. confirmation: "committed to [branch]" and "PR created at [URL]" (if pushed).
• Phase 6 skipped (same-repo): user sees "doc changes ready for normal commit flow with code changes" and no separate git menu.
• --preview flag: user sees analysis summary without any file changes. message: "no changes made (--preview flag)."