skilld
All skills
clickhouse avatar

/clickhouse-managed-postgres-rca

@544384f official
by clickhouseclickhouse/agent-skills543 stars
39

MUST USE when investigating performance issues on a ClickHouse-managed Postgres instance. Provides an evidence-based RCA workflow that scrapes the Prometheus endpoint for system signal, pulls per-digest evidence from the Slow Query Patterns API, and recommends (does not apply) a fix.

Ask your Agent

Use this Skill: https://skilld.dev/gh/clickhouse/agent-skills/clickhouse-managed-postgres-rca

This session only. Nothing lands on disk.

rulesrecommend-only.md

≈394 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Recommend-only boundary

This skill never executes mutations on the Postgres instance.

Never do

  • Run CREATE INDEX, ALTER, DROP, VACUUM, ANALYZE, REINDEX, or any other DDL/DML on the user's instance.
  • Call pg_cancel_backend or pg_terminate_backend.
  • Modify any configuration, role, or extension.
  • Open a psql session to the user's instance and run commands inside it on their behalf.

What you do instead

Write the exact SQL the human should run, explain why, and state explicitly that you did not run it. Use the structure in rules/output-template.md.

If the user asks you to apply the fix

Decline and explain. Example response:

I can't apply the fix on your instance — this skill is recommend-only by contract. The SQL above is ready to copy; you can run it from psql or whatever client you use. I'm happy to help interpret the result or roll back if it doesn't behave as expected.

The point of the boundary is that an agent reasoning from incomplete information (no plans, no full table stats) shouldn't be mutating production. The recommendation may be right but a human should sanity-check the call.

Read-only operations are fine

The two API calls this skill makes — Prometheus scrape and slow-query-patterns list — are read-only. You can re-scrape or re-list freely to confirm a fix took effect after the human applies it.

Source: SKILL.md on GitHub

Third-party checks

1 alert3mo3 checks · Risk SAFE
  • Gen Agent Trust Hub3mo

    This skill provides a structured diagnostic workflow for ClickHouse-managed Postgres instances. It fetches system metrics and query patterns from official ClickHouse Cloud APIs to identify performance bottlenecks like full scans or hot loops. It includes a strong 'recommend-only' guardrail, ensuring no modifications are made to the database.

  • Socket3mo

    No alerts

  • Snyk3mo

    Risk: HIGH · 3 issues

Provenance

Signed by skilld at 544384f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 4 months ago

Capability

metadata
{
  "author": "ClickHouse Inc",
  "version": "0.1.0"
}

Topics

  • Performance
  • clickhouse
  • postgres
  • rca
  • troubleshooting
  • prometheus
  • slow-query
  • managed-database

README badge

README badge for clickhouse/agent-skills/clickhouse-managed-postgres-rca

What it does

Investigates performance issues on ClickHouse-managed Postgres instances by scraping Prometheus metrics and querying the Slow Query Patterns API to identify the root cause. Follows a six-step RCA workflow that reasons from system signals and query digests to recommend (but not apply) fixes like addressing full table scans, N+1 loops, or write congestion.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with self-hosted Postgres or only ClickHouse Cloud?
Only ClickHouse Cloud managed Postgres instances. The skill requires the ClickHouse Cloud API endpoints for Prometheus metrics and the Slow Query Patterns API.
What credentials do I need to use this skill?
A ClickHouse Cloud API key and secret pair for HTTP Basic auth, plus the organization ID and service ID for the Postgres instance you're investigating.
Can this skill apply fixes automatically?
No. The skill diagnoses the issue and recommends a fix, but the human must apply it. The skill never runs DDL or backend termination commands.
Does this skill provide query plans or EXPLAIN output?
No. It reasons from Prometheus system metrics and slow query pattern statistics, not from query plans. You will not get per-table scan counts or autovacuum timestamps.
How long does the RCA workflow take?
Approximately 1 second. Steps 2 and 3 (Prometheus scrape and slow query patterns) run in parallel, reducing wall time from ~2s sequential to ~1s.

Generated from the current SKILL.md. These answers refresh after source changes.