## Summary
Adds two `clickhousectl`-based infra skills in a normalized format,
where each skill has a thin `SKILL.md` with a local-vs-cloud decision
tree that routes to `ref/local.md` and `ref/cloud.md`, and the local
workflow hands off to cloud when going to production.
### infra-postgres (new)
- `ref/local.md` — Docker-backed local Postgres for development: start,
psql client (host psql or Docker-exec fallback), `.env` wiring via
`dotenv`, lifecycle (stop/remove). Verified end-to-end against
clickhousectl 0.3.1 (container start, SQL, dotenv, list, stop, remove);
example JSON output captured from real runs.
- `ref/cloud.md` — managed ClickHouse Cloud Postgres services (beta):
API-key auth, service creation, connections and TLS certs, runtime
config (pgConfig/pgBouncerConfig), read replicas, promote/switchover,
point-in-time restore.
### infra-clickhouse (merges clickhousectl-local-dev +
clickhousectl-cloud-deploy)
- Same structure: `ref/local.md` carries the local dev workflow,
`ref/cloud.md` the ClickHouse Cloud deployment workflow.
- Fixes a stale command from the old cloud-deploy skill: `clickhousectl
cloud login` no longer exists in 0.3.1 — it's `clickhousectl cloud auth
login`.
- The superseded `clickhousectl-local-dev` and
`clickhousectl-cloud-deploy` directories are removed.
### Registration
- README: new "Infra ClickHouse" and "Infra Postgres" sections replace
the two clickhousectl sections; Quick Start bullets updated.
- `.claude-plugin/marketplace.json`: entries for both new skills;
superseded entries removed.
- `.claude-plugin/plugin.json`: skills array updated accordingly.
### Descriptions
Frontmatter descriptions follow the [Agent Skills authoring best
practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices):
third person, capabilities first, then "Use when …" trigger contexts
using the vocabulary users actually say (Postgres/PostgreSQL, psql,
deploy to ClickHouse Cloud), with both the local and cloud cases
explicit.
## Test plan
- [x] Local Postgres workflow run end-to-end with clickhousectl 0.3.1
(start → query → dotenv → list → stop → remove)
- [x] Cloud command surface verified against `clickhousectl cloud
postgres`/`cloud service`/`cloud auth` `--help` output
- [x] All JSON files validate; no remaining references to the removed
skill names outside intentional "supersedes" notes
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
## Summary
The `clickhousectl-local-dev` and `clickhousectl-cloud-deploy` skills
were added under `skills/` (#32) but were never registered anywhere
discoverable:
- **README.md** — added both skills to the *Available Skills* section
(matching the style of the existing entries) and added two Quick Start
bullets
- **.claude-plugin/marketplace.json** — added plugin entries for both
skills (version `0.2.0`, matching their SKILL.md metadata)
- **.claude-plugin/plugin.json** — appended both skill paths to the
`skills` array
This follows the same registration pattern used for the chdb skills in
#35.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
## Why
Installers/agents look one level deep. The npx skills add CLI and the
agent skill directories listed in the README (.claude/skills/,
.cursor/skills/, .github/skills/, etc.) expect each skill as a direct
child of skills/. A nested
skills/clickhouse-client-js/clickhouse-js-node-troubleshooting/ will not
be picked up by those scanners.
---
- [x] Promote
`skills/clickhouse-client-js/clickhouse-js-node-troubleshooting/` to
top-level `skills/clickhouse-js-node-troubleshooting/`
- [x] Remove empty `skills/clickhouse-client-js/` wrapper directory
- [x] Add an entry for the skill under "Available Skills" in `README.md`
- [x] Add `./skills/clickhouse-js-node-troubleshooting/` to the `skills`
array in `.claude-plugin/plugin.json`
- [x] Add a plugin entry for the skill in
`.claude-plugin/marketplace.json`
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com>
Co-authored-by: Peter Leonov <peter.leonov@clickhouse.com>
# Proposed PR: Add `clickhouse-architecture-advisor` skill
## Summary
This PR adds a new skill, `clickhouse-architecture-advisor`, intended to
complement the existing `clickhouse-best-practices` skill.
The new skill does **not** replace official best practices. Instead, it
provides a workload-aware architecture decision layer that helps agents
and users reason about:
- when to apply specific ClickHouse patterns
- why a pattern fits a given workload
- how to translate best practices into a concrete architecture
## Why this belongs in `agent-skills`
The current `clickhouse-best-practices` skill is excellent at
rule-backed guidance for schema design, query optimization, and
ingestion. This proposal fills a different gap:
- multi-step architecture design
- workload classification
- tradeoff-driven decisioning
- explicit distinction between official guidance and field heuristics
This is especially useful for:
- early-stage customer architecture
- real-time design workshops
- workload sizing discussions
- POC design
- SA/TAM advisory workflows
## What this PR includes
### New skill
- `skills/clickhouse-architecture-advisor/`
### New components
- `SKILL.md`
- `README.md`
- `AGENTS.md`
- `metadata.json`
- `schemas/recommendation_schema.yaml`
- `mappings/doc_links.yaml`
### Decision rules
- `decision-ingestion-strategy.md`
- `decision-partitioning-timeseries.md`
- `decision-join-enrichment.md`
- `decision-late-arriving-upserts.md`
- `decision-real-time-preaggregation.md`
### Examples
- `observability-high-throughput.md`
- `finserv-market-surveillance.md`
- `siem-security-analytics.md`
## Recommendation model
Every recommendation is explicitly classified as one of:
- `official` — directly backed by official docs
- `derived` — inferred from official docs and ClickHouse behavior
- `field` — experience-based, explicitly labeled as such
This keeps the skill aligned with the principle that docs remain the
source of truth while still allowing architecture guidance to be useful
in real-world scenarios.
## Non-goals
This PR does not:
- override `clickhouse-best-practices`
- introduce commercial recommendations
- create a parallel documentation system
- present field heuristics as official guidance
## Suggested review focus
- Naming and scope of the skill
- Whether the official / derived / field classification is the right
pattern
- Whether the decision rules should remain separate or partially merge
into the existing best-practices skill
- Whether more explicit docs links are needed in specific rules
## Notes
This proposal is intentionally conservative:
- it cites official documentation
- it flags heuristics
- it uses examples to show how the architecture layer complements
existing rules
Alasdair Brown