update-jamdesk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update Jamdesk

更新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.

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.

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.

更新外部代码库中面向客户的文档（不包含CLAUDE.md）。通过

.jamdesk-docs-path

定位文档，提出澄清问题，编写文档，并通过jamdesk CLI进行验证。

提示语： "我将使用update-jamdesk技能为您更新文档。"

适用场景： 面向用户的API、CLI命令、UI界面、配置选项、组件行为或docs.json架构/功能变更。

不适用场景： 内部重构、仅测试代码变更、构建/CI配置修改、无行为变更的性能优化。

常见误区： docs.json格式或配置逻辑的变更属于面向用户的内容。即使变更发生在文档库内部，也需确认：“此变更是否引入或修改了客户使用的配置模式？”如果是，则需要编写文档。

Critical Rules

核心规则

Always	Never
Include frontmatter ( `title` 50-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

始终要做	切勿做
包含页头信息（ `title` 50-60字符， `description` 120-160字符）	创建包含“TODO”的占位页面
优先使用内置组件	使用 `mint.json` （请使用 `docs.json` ）
编写前先提出澄清问题	跳过验证步骤
提前说明前置条件	包含密钥、令牌或真实客户数据
使用主动语态和动作导向型标题	做出绝对承诺（如“始终可用”“即时生效”）
为破坏性操作步骤添加明确警告	使用“点击此处”作为链接文本

Flags

命令标志

Flag	Behavior
(none)	Full workflow: locate → clarify → analyze → write → verify → commit
`--preview`	Phases 1-3 only, describe changes without making them

Proactive: After

/commit

with changes to

**/api/**

**/cli/**

, or

**/components/**

, suggest running this skill.

标志	行为
无	完整工作流：定位 → 澄清 → 分析 → 编写 → 验证 → 提交
`--preview`	仅执行1-3阶段，仅描述变更而不实际修改

主动触发： 当执行

/commit

命令提交

**/api/**

、

**/cli/**

或

**/components/**

目录下的变更后，建议运行本技能。

Phase 1: Locate Documentation

阶段1：定位文档

Find

.jamdesk-docs-path

by walking up from current directory to git root.

yaml

docs_path: ../customer-docs    # Required - relative or absolute path
docs_branch: main              # Optional, default: main

First-time setup: If config doesn't exist, ask user for their docs repo path and create the file. This only happens once per project. Point users to https://jamdesk.com/docs for help getting started with Jamdesk.

Validation: Path exists, contains

docs.json

, check for uncommitted changes. If same git repo as code, skip separate git operations.

.jamdesk-docs-path

文件。

yaml

docs_path: ../customer-docs    # 必填 - 相对或绝对路径
docs_branch: main              # 可选，默认值：main

首次配置： 如果配置文件不存在，询问用户文档库路径并创建该文件。每个项目仅需配置一次。引导用户访问https://jamdesk.com/docs获取Jamdesk入门帮助。

验证： 确认路径存在、包含

docs.json

文件，检查是否有未提交的变更。如果文档库与代码库为同一git仓库，可跳过独立的git操作。

Phase 2: Clarify Scope

阶段2：明确范围

Review conversation to identify what changed, then ask:

Branch strategy: Feature branch (recommended), main, or current branch?
Scope confirmation: "I plan to [create/update] these pages: ... Any changes?"
Additional context (if needed): Terminology, related features, edge cases

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

回顾对话内容确定变更点，然后询问：

分支策略： 功能分支（推荐）、主分支，还是当前分支？
范围确认： “我计划[创建/更新]以下页面：... 是否需要调整？”
补充上下文（如有需要）：术语定义、相关功能、边缘情况

原则： 先询问，再编写。30秒的澄清可避免10分钟的返工。

Phase 3: Analyze Existing Docs

阶段3：分析现有文档

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
New docs.json config/pattern	Update docs.json reference and/or navigation docs

在文档库中搜索该功能的现有文档，呈现分析结果：

现有内容：getting-started.mdx中简要提及该功能
缺失内容：无专属页面

建议方案：
1. 创建：features/new-feature.mdx
2. 更新：getting-started.mdx（添加链接）

决策矩阵：

场景	操作
新功能	创建新页面
行为变更	更新描述该行为的现有页面
小幅度补充	在现有页面中添加章节
重大功能	创建独立新页面
功能弃用/移除	更新现有页面并添加迁移说明
高级用法	在现有页面中添加 `<Accordion>` 组件
docs.json新配置/模式	更新docs.json参考文档和/或导航文档

Phase 4: Write Documentation

阶段4：编写文档

Reference https://jamdesk.com/docs for full standards.

Content quality:

Explain why, not just what
Show the simplest working example first
Use real values in examples, not placeholders
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
```
<Warning>
```
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:

Opening paragraph (what + why + target audience)
Prerequisites (tools, access, versions)
Quick Start (simplest example)
Configuration/Details
Examples (basic → advanced)
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

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

Minimal template:

mdx

---
title: Feature Name
description: SEO description (120-160 chars, unique per page)
lastUpdated: 2026-02-03  # Optional, for frequently-changing features
---

What this does and why it's useful. Target audience: developers who need X.

参考https://jamdesk.com/docs获取完整规范。

内容质量：

解释“为什么”，而不只是“是什么”
先展示最简单的可用示例
示例中使用真实值，而非占位符
每个章节一个核心概念，每页3-7个小节
术语定义一次后统一复用

写作质量：

使用主动语态和直接指令
短句表达，避免习语（面向全球用户）
动作导向型标题（如“配置X”“验证Y”“排查Z问题”）
使用描述性链接文本（切勿用“点击此处”）
为破坏性/不可逆步骤添加
```
<Warning>
```
组件
禁止重复描述： 开头段落必须与页头
```
description
```
内容不同。页头描述用于SEO元标签；开头段落应补充上下文、前置条件或读者可实现的目标，而非重复页头内容。

页面结构：

开头段落（功能介绍+价值+目标受众）
前置条件（工具、权限、版本要求）
快速入门（最简示例）
配置/详细说明
示例（基础→进阶）
下一步（2-4个相关链接）

页面类型：

任务型页面： 带编号步骤的分步流程
参考型页面： 先展示最简示例，再扩展详细内容

标题结构： 单个H1标题（位于页头的页面标题），正文章节从H2开始。

最简模板：

mdx

---
title: 功能名称
description: SEO描述（120-160字符，每页唯一）
lastUpdated: 2026-02-03  # 可选，适用于频繁变更的功能
---

本功能的作用及价值。目标受众：需要X的开发者。

Prerequisites

前置条件

Node.js 18+
API key from Settings

Node.js 18+
从设置获取的API密钥

Quick Start

快速入门

```bash command --example ```

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. See https://jamdesk.com/docs/components

Images: 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.

<Columns cols={2}> <Card title="相关功能" href="/related"> 继续学习该功能 </Card> <Card title="API参考" href="/api"> 完整API详情 </Card> </Columns> ```

组件：

<Tabs>

、

<Steps>

、

<Accordion>

、

<Columns>

、

<Card>

、

<Note>

<Warning>

<Tip>

、

<CodeGroup>

。没有

<Cards>

组件——请使用

<Columns cols={2}>

搭配

<Card>

子组件。查看https://jamdesk.com/docs/components了解详情。

图片： 存储在

/images/<feature>/

目录，使用绝对路径，始终添加替代文本，避免仅依赖颜色传递信息。

链接： 使用相对路径，不带

.mdx

扩展名，避免孤立页面，链接至权威来源（API规范、发布说明）。

API文档： 如有可用，优先使用OpenAPI自动生成。

导航： 将新页面按字母顺序添加至

docs.json

导航，除非用户指定了其他排序方式，或现有结构显示出明确的分组逻辑。

维护： 对频繁变更的功能使用

lastUpdated

页头信息。及时标记或移除已弃用的指南内容。

Phase 5: Verify

阶段5：验证

With CLI (recommended):

bash

jamdesk dev          # Preview locally
jamdesk validate     # Check docs.json schema
jamdesk broken-links # Find broken links

Without CLI: Verify manually - code examples have language tags, frontmatter has title/description, links use correct paths (no

.mdx

), new pages added to

docs.json

Fix errors before proceeding. If user dislikes changes, they can

git checkout .

to revert before commit.

推荐使用CLI：

bash

jamdesk dev          # 本地预览
jamdesk validate     # 检查docs.json架构
jamdesk broken-links # 查找失效链接

无CLI时的操作： 手动验证——代码示例包含语言标签、页头包含标题/描述、链接使用正确路径（无

.mdx

）、新页面已添加至

docs.json

。

修复错误后再继续。 如果用户不满意变更，可在提交前执行

git checkout .

撤销修改。

Phase 6: Commit

阶段6：提交

Present summary of changes, then ask user preference:

Commit to feature branch
Show diff first
Make additional changes

After commit, offer to push and create PR.

Commit format:

docs: [action] [what]

(e.g.,

docs: add webhook configuration guide

)

呈现变更摘要，然后询问用户偏好：

提交至功能分支
先展示差异
进行额外修改

提交后，可主动提出推送代码并创建PR。

提交格式：

docs: [操作] [内容]

（例如：

docs: add webhook configuration guide

）

Quick Reference

快速参考

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

场景	操作
无配置文件	询问用户，创建 `.jamdesk-docs-path`
外部代码库	使用功能分支，执行独立git操作
同仓库文档	无需独立git操作
使用 `--preview` 标志	仅分析，不修改
CLI不可用	使用手动验证清单

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)

Commit? [Y/n]

User: Y

Claude: Committed. Push and create PR?

用户：为新的webhook功能编写文档

Claude：我将使用update-jamdesk技能...

在../customer-docs找到文档

请选择分支策略？
1. 功能分支（推荐）
2. 主分支
3. 当前分支

用户：1

Claude：我将创建docs/webhooks页面。范围是否正确？

用户：是的，同时更新API参考文档

[编写文档，执行验证]

✓ validate验证通过
✓ broken-links检查通过

涉及文件：webhooks/overview.mdx（新增）、api/reference.mdx（更新）、docs.json（更新）

是否提交？[Y/n]

用户：Y

Claude：已提交。是否推送并创建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
```
<Warning>
```
on destructive steps
Leaving deprecated content without marking it
Copying the frontmatter
```
description
```
as the opening paragraph (description echo)

如果发现自己出现以下行为，请立即停止：

跳过澄清问题
创建页面但未更新
```
docs.json
```
内部链接使用完整URL
添加图片但未添加替代文本
使用
```
--preview
```
标志时进行修改
包含密钥、令牌或真实客户数据
使用“点击此处”或模糊的链接文本
破坏性步骤未添加
```
<Warning>
```
组件
保留已弃用内容但未标记
将页头
```
description
```
直接复制为开头段落（重复描述）