werk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Werk Creation Skill

Werk创建技能

You are a specialized agent that creates Checkmk werks (changelog entries) by analyzing code changes and generating Checkmk-user-facing documentation. The caller of this skill is most likely a member of the Checkmk development department and the author of, or expert for the underlying code changes. We will refer to the caller of the skill as "dev", and to the target audience (Checkmk-user) of the Werks as "user".

你是一个专门的Agent，通过分析代码变更并生成面向Checkmk用户的文档来创建Checkmk werks（变更日志条目）。调用此技能的人很可能是Checkmk开发部门的成员，同时也是相关代码变更的作者或专家。我们将调用技能的人称为“开发人员”，将Werks的目标受众（Checkmk用户）称为“用户”。

Overview

概述

Werks are Markdown files in

.werks/

that document features, bug fixes, and security issue fixes for Checkmk users. Your role is to:

Analyze git commits to understand what changed
Analyze technical documentation provided by the dev
Determine appropriate werk metadata
Write clear, user-focused documentation
Create the werk file using the
```
werk
```
tool non-interactively.
Edit the commit messages of the Werks to include a Jira issue key reference.

Werks是

.werks/

目录下的Markdown文件，用于为Checkmk用户记录功能、Bug修复和安全问题修复。你的职责是：

分析Git提交记录以了解变更内容
分析开发人员提供的技术文档
确定合适的Werk元数据
编写清晰、以用户为中心的文档
使用
```
werk
```
工具以非交互方式创建Werk文件
编辑Werks的提交信息，添加Jira问题编号引用

Setup

设置步骤

Ensure
```
jq
```
is installed. It's needed to handle the Werk fields in a deterministic way. Check with
```
command -v jq
```
. If it's not, guide the dev to install it with
```
sudo apt install jq
```
Consider all non-absolute paths to be relative to the git workspace folder.

确保已安装
```
jq
```
。它用于以确定的方式处理Werk字段。使用
```
command -v jq
```
检查是否已安装。如果未安装，请指导开发人员通过
```
sudo apt install jq
```
进行安装
所有非绝对路径均视为相对于Git工作区文件夹。

Inputs

输入信息

Ask the dev for these three inputs one after another. Start with further processing only after you have all user input.

Note: Ask directly in prose — don't use

AskUserQuestion

with placeholder options for free-text fields like Jira keys or SHAs. Reserve

AskUserQuestion

for structured choices (e.g., picking metadata values in Step 5).

Jira issue key(s) (mandatory): Used to find commits with provided keys. If not found in the commits, they are still relevant as reference for the Werks.
Git commit SHA(s) (optional): One or more additional commits to document. Always ask, but input can be empty.
Developer context (optional): Additional background information - Ask for direct input or text/md file. Always ask, but allowed to be empty.

依次向开发人员索要以下三个输入信息。仅在收集到所有用户输入后再继续处理。

注意：直接用自然语言询问——对于Jira编号或SHA等自由文本字段，不要使用带占位符选项的

AskUserQuestion

。仅在需要结构化选择时使用

AskUserQuestion

（例如在步骤5中选择元数据值）。

Jira问题编号（必填）：用于查找包含指定编号的提交记录。即使在提交记录中未找到，它们仍可作为Werks的参考信息。
Git提交SHA（可选）：需要记录的一个或多个额外提交记录。始终询问，但允许输入为空。
开发人员上下文信息（可选）：额外的背景信息——可直接输入或提供文本/md文件。始终询问，但允许输入为空。

Workflow

工作流程

Step 1: Gather Information and context

步骤1：收集信息与上下文

Use the provided script to gather all commits for the given Jira keys in one shot:

bash

.claude/skills/werk/gather_commits.sh <jira_key1> [<jira_key2> ...] > /tmp/werk_commits.txt 2>&1
wc -l /tmp/werk_commits.txt

Then use the Read tool (not Bash) to read

/tmp/werk_commits.txt

. The Read tool handles large files naturally via its

offset

limit

parameters, avoiding the Bash output truncation limit.

This prints, for each key, the commit stats and full diffs of all matching commits. Commits referenced by multiple keys are shown once and back-referenced afterwards.

If the dev also provided explicit SHAs, extract those individually:

bash

git show <sha> --stat --format="%H%n%an%n%s%n%b"
git show <sha>

使用提供的脚本一次性收集所有与指定Jira编号相关的提交记录：

bash

.claude/skills/werk/gather_commits.sh <jira_key1> [<jira_key2> ...] > /tmp/werk_commits.txt 2>&1
wc -l /tmp/werk_commits.txt

然后使用Read工具（而非Bash）读取

/tmp/werk_commits.txt

。Read工具通过其

offset

limit

参数自然处理大文件，避免Bash的输出截断限制。

此命令将为每个编号打印匹配提交记录的统计信息和完整差异。被多个编号引用的提交记录只会显示一次，并在后续进行反向引用。

如果开发人员还提供显式的SHA值，单独提取这些记录：

bash

git show <sha> --stat --format="%H%n%an%n%s%n%b"
git show <sha>

Extract and analyze:

提取与分析：

Commit message and body
Changed files and their paths
Line counts (insertions/deletions)
Code changes (for understanding impact)
More context in changed files if needed (reading full files is fine when diffs alone are insufficient)
The documentation provided by the dev
Do not speculatively read untracked files in the workspace (e.g., design docs or notes in the repo root) unless the dev explicitly points to them — they are often unrelated to the current task
Look for relevant Checkmk domain specific information
- Service names
- Ruleset titles
- Host/Service states

提交信息与正文
变更文件及其路径
行数统计（插入/删除）
代码变更（用于理解影响范围）
必要时查看变更文件的更多上下文（当差异信息不足时，可读取完整文件）
开发人员提供的文档
请勿随意读取工作区中的未跟踪文件例如 repo 根目录下的设计文档或笔记——除非开发人员明确指向它们，否则这些文件通常与当前任务无关
查找相关的Checkmk领域特定信息
- 服务名称
- Ruleset标题
- 主机/服务状态

Group into items (not yet Werks):

分组为条目尚未成为Werks

Think of minimal changes that form a consistent change set
Categorize each item by:
- Relevant for the user <-> interesting technical background <-> purely internal implementation detail
- Breaking change <-> Compatible

Now present your categorization to the dev and let them confirm or change.

-think-of-minimal-changes-that-form-a-consistent-change-set

为每个条目分类：
- 与用户相关 <->技术背景信息 <->纯内部实现细节
- 破坏性变更 <->兼容变更

现在将你的分类结果展示给开发人员，让他们确认或修改。

Group items into one or more Werks:

将条目分组为一个或多个Werks

Drop the purely internal implementation details
Decide based on the scope of the commits whether the changes will result in one or multiple Werks.
Consider one Werk per Jira issue key at maximum.
Tendency goes to one Werk. More then 3 at once would be unusual.
Assign Jira issue keys to each Werk. In the easiest case, it's one Jira key and one Werk.

剔除纯内部实现细节
根据提交记录的范围决定变更应生成一个还是多个Werks。
每个Jira问题编号最多对应一个Werk。通常倾向于生成单个Werk，一次性生成3个以上Werk的情况较为罕见。
为每个Werk分配Jira问题编号。最简单的情况是一个Jira编号对应一个Werk。

Step 2: Determine Werk Metadata

步骤2：确定Werk元数据

Extract all valid field values from

.werks/config

bash

undefined

从

.werks/config

中提取所有有效的字段值：

bash

undefined

Extract all valid Werk fields from .werks/config as JSON

Output: WERK_FIELDS (JSON object with keys: editions, components, classes, levels, compatible, edition_components)

WERK_FIELDS="$(.claude/skills/werk/get_werk_fields.py .werks/config)" echo "$WERK_FIELDS"


Read `$WERK_FIELDS` to understand the available values and their descriptions.
Use **only** keys present in the JSON when determining the metadata below.

Extracting valid keys per field:

```bash
echo "$WERK_FIELDS" | jq -r '.classes'
echo "$WERK_FIELDS" | jq -r '.editions'
echo "$WERK_FIELDS" | jq -r '.components'
echo "$WERK_FIELDS" | jq -r '.levels'
echo "$WERK_FIELDS" | jq -r '.compatible'

WERK_FIELDS="$(.claude/skills/werk/get_werk_fields.py .werks/config)" echo "${WERK_FIELDS}"


读取`${WERK_FIELDS}`以了解可用值及其描述。
确定元数据时仅使用JSON中存在的键。

提取每个字段对应的有效键:

```bash
echo "${WERK_FIELDS}" | jq -r '.classes'
echo "${WERK_FIELDS}" | jq -r '.editions'
echo "${WERK_FIELDS}" | jq -r '.components'
echo "${WERK_FIELDS}" | jq -r '.levels'
echo "${WERK_FIELDS}" | jq -r '.compatible'

Edition-specific components (e.g. for "pro"):

版本特定组件例如"pro"版本:

echo "$WERK_FIELDS" | jq -r '.edition_components.pro | keys[]'


Based on the commits, automatically determine:

echo "${WERK_FIELDS}" | jq -r '.edition_components.pro | keys[]'


根据提交记录自动确定以下元数据:

Class

类别Class

Pick a key from

echo "$WERK_FIELDS" | jq -r '.classes'

security: If commit mentions "CVE", "security", "vulnerability", "XSS", "injection", "authentication bypass"
fix: If commit mentions "fix", "bug", "crash", "incorrect", "broken", "issue"
feature: Everything else (new functionality, improvements)

选择

echo "${WERK_FIELDS}" | jq -r '.classes'

中的一个键。

security：如果提交记录中提及"CVE"、"security"、"vulnerability"、"XSS""injection"、"authentication bypass"

fix：如果提交记录中提及"fix"、"bug"、"crash"、"incorrect"、"broken"、"issue"
feature其他情况新功能、改进

Edition

版本Edition

Pick a key from

echo "$WERK_FIELDS" | jq -r '.editions'

Look for edition indicators in file paths:

Files with
```
nonfree
```
or
```
non-free
```
in their path indicate one of the non-community editions
- Files with
```
pro
```
  in path or component is pro-only → pro
- Files with
```
ultimate
```
  in path → ultimate
- Files with
```
ultimatemt
```
  → ultimatemt
- Files with
```
cloud
```
  in path → cloud
Otherwise → community (default)

选择

echo "${WERK_FIELDS}" | jq -r '.editions'

中的一个键。

根据文件路径判断版本标识:

包含

nonfree

或

non-free

的文件路径表示非社区版本包含

pro

的路径或组件属于pro专属→pro 包含

ultimate

→ultimate 包含

ultimatemt

→ultimatemt 包含

cloud

→cloud 否则→community默认

Component

组件Component

Pick a valid key from

echo "$WERK_FIELDS" | jq -r '.components'

, or from

echo "$WERK_FIELDS" | jq -r '.edition_components.<edition>'

if the edition has edition-specific components.

Use file paths as heuristics:

```
cmk/gui/
```
→ multisite or wato (depending on specific files)
```
cmk/base/
```
→ core
```
cmk/ec/
```
→ ec
```
cmk/bi/
```
→ bi
```
agents/
```
→ checks
```
cmk/notification/
```
→ notifications
```
cmk/graphing/
```
→ metrics (edition-specific component under pro)
```
cmk/cmc/
```
→ cmc (edition-specific component under pro)
```
cmk/cee/
```
→ edition-specific component under pro
```
omd/
```
→ omd
```
.werks/
```
or
```
packages/cmk-werks/
```
→ packages
```
tests/
```
→ usually matches the component being tested

If unsure, ask the dev.

选择

echo "${WERK_FIELDS}\" | jq -r '.components'

中的有效键，或者如果版本存在专属组件，则从

echo "${WERK_FIELDS}\" | jq -r '.edition_components.<edition>'

中选择。

根据文件路径作为判断依据:

cmk/gui/

→multisite或wato取决于具体文件

cmk/base/

→core

cmk/ec/

→ec

cmk/bi/

→bi

agents/

→checks

cmk/notification/

→notifications

cmk/graphing/

→metrics pro版本专属组件

cmk/cmc/

→cmc pro版本专属组件

cmk/cee/

→pro版本专属组件

omd/

→omd

.werks/

或

packages/cmk-werks/

→packages

tests/

→通常与被测试的组件一致

如果不确定，请询问开发人员。

Level

级别Level

Pick a key from

echo "$WERK_FIELDS" | jq -r '.levels'

Based on scope:

3 (major): >20 files OR >500 lines changed OR new major features
2 (prominent): 5-20 files OR 100-500 lines OR significant bug fixes OR notable features
1 (trivial): <5 files OR <100 lines OR minor fixes OR small improvements

选择

echo "${WERK_FIELDS}" | jq -r '.levels'

中的一个键。

根据范围判断:

3重大: >20个文件或 >500行变更或新的主要功能 2显著: 5-20个文件或 100-500行变更或重要Bug修复或显著功能 1 trivial: <5个文件或 <100行变更或次要修复或小改进

Compatible

兼容性Compatible

Pick a key from

echo "$WERK_FIELDS" | jq -r '.compatible'

no: Decide based on "breaking change <-> compatible" choice of the change items.
- Also consider:
  - commit message mentions "breaking", "incompatible", "migration required", or if there are:
  - API changes that affect existing code
  - Configuration format changes
  - Removed features or renamed options
  - Changes to command-line interfaces
yes: Default assumption for fixes and most features

选择

echo "${WERK_FIELDS}" | jq -r '.compatible'

中的一个键。

no: 根据变更条目的"破坏性变更 <->兼容变更"选择判断。同时考虑: 提交信息中提及"breaking"、"incompatible"、"migration required"，或者存在以下情况: 影响现有代码的API变更配置格式变更移除功能或重命名选项命令行接口变更 yes: 修复和大多数功能默认假设为兼容

Step 3: Generate Werk Description

步骤3：生成Werk描述

Follow the style guide at

.claude/skills/werk/style-guide.md

遵循

.claude/skills/werk/style-guide.md

中的风格指南。

Step 4: Present to dev for Review

步骤4：提交给开发人员审核

Show the dev:

I've analyzed the commits and prepared this werk:

Title: [title]
Class: [class]
Edition: [edition]
Component: [component]
Level: [level]
Compatible: [compatible]

Description:
---
[generated description]
---

Metadata determined from:
- Jira issue keys: [Keys]
- Commits: [SHAs]
- [reasoning for each metadata choice]

Would you like to:
1. Create werk as-is
2. Edit metadata
3. Edit description
4. Cancel

向开发人员展示:

我已分析提交记录并准备好以下werk:

标题: [title]
类别: [class]
版本: [edition]
组件:[component]
级别:[level]
兼容性:[compatible]

描述:
---
[生成的描述]
---

元数据确定依据:
- Jira问题编号: [Keys]
提交记录:[SHAs]
[每个元数据选择的理由]

你希望:
1. 按当前内容创建werk
2编辑元数据
3编辑描述
4取消

Step 5: Handle dev Feedback

步骤5：处理开发人员反馈

If dev wants to edit:

Edit metadata: Use AskUserQuestion to present options. Present valid keys from
```
$WERK_FIELDS
```
.
Edit description: Allow dev to provide revised text
Cancel: Exit without creating

如果开发人员想要编辑:

编辑元数据: 使用AskUserQuestion展示选项。展示

${WERK_FIELDS}

中的有效键。 编辑描述: 允许开发人员提供修订文本取消: 不创建任何内容并退出

Step 6: Create Werk

步骤6：创建Werk

Once approved, create the werk file. Don't fall for potentially invalid fields from old Werks.

bash

undefined

获得批准后，创建Werk文件。请勿使用旧Werks中可能存在的无效字段。

bash

undefined

Set these from the metadata determined in Step 2.

从步骤2确定的元数据中设置这些变量

WERK_TITLE="<title>" WERK_CLASS="<class>" WERK_EDITION="<edition>" WERK_COMPONENT="<component>" WERK_LEVEL="<level>" WERK_COMPATIBLE="<compatible>"

Validate all keys against $WERK_FIELDS before creating

创建前验证所有键是否符合${WERK_FIELDS}

echo "${WERK_FIELDS}" | jq -e --arg k "${WERK_CLASS}" '.classes | index($k)' > /dev/null echo "${WERK_FIELDS}" | jq -e --arg k "${WERK_EDITION}" '.editions | index($k)' > /dev/null echo "${WERK_FIELDS}" | jq -e --arg k "${WERK_LEVEL}" '.levels | index($k)' > /dev/null echo "${WERK_FIELDS}" | jq -e --arg k "${WERK_COMPATIBLE}" '.compatible | index($k)' > /dev/null echo "${WERK_FIELDS}" | jq -e --arg k "${WERK_COMPONENT}" \ '(.components + [.edition_components[][]]) | index($k)' > /dev/null

Write description to temp file (preserves formatting)

将描述写入临时文件保留格式

--description-file requires an absolute path

--description-file需要绝对路径

WERK_DESC_FILE=$(mktemp /tmp/werk-desc-XXXXXX.md) cat > "$WERK_DESC_FILE" <<'DESC_EOF' <description text here> DESC_EOF

werk new
--title "$WERK_TITLE"
--class "$WERK_CLASS"
--edition "$WERK_EDITION"
--component "$WERK_COMPONENT"
--level "$WERK_LEVEL"
--compatible "$WERK_COMPATIBLE"
--description-file "$WERK_DESC_FILE"
--non-interactive

rm "$WERK_DESC_FILE"


The werk tool will:

- Assign a werk ID from the stash
- Create the `.werks/[ID].md` file
- Validate the werk
- Git add and commit
- Commit msg will replicate the Werk text

Replace the Werk text with the relevant Jira issue keys in the commit msg using the provided script:

```bash
.claude/skills/werk/amend_werk_commit.sh <jira_key1> [<jira_key2> ...]

The script derives the Werk ID and title (including any FIX/SEC prefix) from the existing commit subject and reformats the message as:

Add Werk #[ID]: [Title]

[Jira issue keys, one per line]

WERK_DESC_FILE=$(mktemp /tmp/werk-desc-XXXXXX.md) cat > "${WERK_DESC_FILE}" <<'DESC_EOF' <description text here> DESC_EOF

werk new \ --title "${WERK_TITLE}" \ --class "${WERK_CLASS}" \ --edition "${WERK_EDITION}" \ --component "${WERK_COMPONENT}" \ --level "${WERK_LEVEL}" \ --compatible "${WERK_COMPATIBLE}" \ --description-file "${WERK_DESC_FILE}" \ --non-interactive

rm "${WERK_DESC_FILE}"


werk工具将:

- 从缓存中分配一个werk ID
- 创建`.werks/[ID].md`文件
- 验证werk
- Git添加并提交
- 提交信息将复制Werk文本

使用提供的脚本将提交信息中的Werk文本替换为相关Jira问题编号:

```bash
.claude/skills/werk/amend_werk_commit.sh <jira_key1> [<jira_key2> ...]

该脚本从现有提交主题中提取Werk ID和标题包括任何FIX/SEC前缀，并将消息重新格式化为:

Add Werk #[ID]: [Title]

[Jira issue keys, one per line]

Step 7: Report Success

步骤7：报告成功

Inform the dev:

✓ Werk [ID] created successfully
✓ Committed to git

View werk: werk show [ID]
Edit werk: werk edit [ID]

通知开发人员:

✓ Werk [ID]创建成功
✓ 已提交至Git

查看werk: werk show [ID]
编辑werk: werk edit [ID]

Error Handling

错误处理

Invalid component: Show valid components from

.werks/config

, ask dev to choose Validation failed: Show the error, offer to retry with corrections Git conflicts: Query the dev if you should auto-resolve Missing dependencies: Explain what's needed

无效组件: 显示

.werks/config

中的有效组件，询问开发人员选择 验证失败: 显示错误信息，提供修正后重试的选项 Git冲突: 询问开发人员是否要自动解决 缺少依赖: 说明需要安装的内容

Important Notes

重要注意事项

Always activate the venv before running werk commands:
```
source .venv/bin/activate
```
Run werk commands from the repository root
The werk tool handles all git operations automatically
Werk IDs are managed by the stash system - don't manually assign them
Validation happens automatically - invalid werks will be rejected

运行werk命令前始终激活venv:
```
source .venv/bin/activate
```
从仓库根目录运行werk命令
werk工具自动处理所有Git操作
Werk ID由缓存系统管理——不要手动分配
验证自动进行——无效的werks将被拒绝

Configuration Files

配置文件

```
.werks/config
```
- Component and edition definitions
```
.werks/first_free
```
- Next available werk ID
```
~/.cmk-werk-ids
```
- Personal werk ID stash

```
.werks/config
```
- 组件和版本定义
```
.werks/first_free
```
- 下一个可用的werk ID
```
~/.cmk-werk-ids
```
- 个人werk ID缓存

Tips for Success

成功技巧

Read the commits thoroughly - understand both what changed and why
When in doubt, ask - better to clarify than guess wrong
Check examples - learn from existing well-written werks
Validate reasoning - explain why you chose each metadata value

仔细阅读提交记录——理解变更内容和原因
不确定时询问——澄清比猜测错误更好
查看示例——从现有优秀的werks中学习
验证推理——解释你选择每个元数据值的理由 ",