Version Upgrade Advisor

What it does

When your agent uses it

• Tasks that involve Data warehousing
• Tasks that involve Code migrations
• Tasks that involve Changelog and release notes

Example prompts

• “Use the version-upgrade-advisor skill to advise whether and how to upgrade ClickHouse — versioning scheme, upgrade path, what you gain…”
• “/version-upgrade-advisor”

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

1. 1One significant line at a time — do not skip multiple major version lines (e.g. 23.3 → 24.3 → 25.3, not 23.3 → 25.3 in one hop). Review…
2. 2Read the changelog first — ClickHouse marks breaking changes explicitly. Settings that change defaults or are removed are the most common…
3. 3Test on staging with production data volumes — especially joins, aggregations with large state, and any experimental features you use.
4. 4Back up before upgrading — at minimum export table schemas; ideally snapshot data or use replicas as rollback points.
5. 5Rolling upgrade for replicated clusters — upgrade one replica at a time. ClickHouse supports mixed-version replication within the same…
6. 6Upgrade ClickHouse Keeper / ZooKeeper in sync — if using Keeper, check compatibility requirements for the version pair.

What it can do on your machine

Read from SKILL.md and the folder at commit fc39ef0. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are sql).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Version Upgrade Advisor loads about 1.6k tokens when it runs. Until then it costs about 37 tokens; SKILL.md has 620 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~37

When it runs · the whole SKILL.md, loaded when a task matches

~1.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from chmonitor/chmonitor at commit fc39ef0, republished under its GPL-3.0 licence (© chmonitor). 620 words, ~1,643 tokens.

name

version-upgrade-advisor

description

Advises whether and how to upgrade ClickHouse — versioning scheme, upgrade path, what you gain, pre/post-upgrade checklist.

SELECT version(), uptime();

-- 1. Check settings that differ from defaults (non-default = potential conflict)
SELECT name, value, default, changed
FROM system.settings
WHERE changed = 1
ORDER BY name;

-- 2. Check for deprecated settings in use
SELECT name, value
FROM system.settings
WHERE name IN (
  -- populate from the target version's deprecation list; do not hard-code here
);

-- 3. List experimental features in use
SELECT name, value
FROM system.settings
WHERE name LIKE '%experimental%' AND value != '0';

-- 4. Check current errors before upgrade (baseline)
SELECT name, value, last_error_message
FROM system.errors
WHERE value > 0
ORDER BY value DESC
LIMIT 20;

-- 5. Verify replication is healthy (replicated clusters only)
SELECT database, table, replica_name, is_leader,
       log_max_index - log_pointer AS lag
FROM system.replicas
WHERE log_max_index - log_pointer > 0
   OR future_parts > 0;

-- Confirm version
SELECT version();

-- Check for new errors since upgrade
SELECT name, value, last_error_message, last_error_time
FROM system.errors
WHERE value > 0
  AND last_error_time > now() - INTERVAL 1 HOUR
ORDER BY value DESC;

-- Confirm replication caught up (clusters)
SELECT database, table, replica_name,
       log_max_index - log_pointer AS lag,
       last_queue_update
FROM system.replicas
ORDER BY lag DESC;

-- Spot-check query performance on known slow queries
-- (run your typical workload; compare system.query_log duration_ms)
SELECT query_id, query, duration_ms
FROM system.query_log
WHERE type = 'QueryFinish'
  AND event_time > now() - INTERVAL 30 MINUTE
ORDER BY duration_ms DESC
LIMIT 20;

© chmonitor, GPL-3.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/version-upgrade-advisor of chmonitor/chmonitor.

Open the folder on GitHubat commit fc39ef0