Make the repo self-onboarding for Claude Code and Codex

.claude/skills/altinity-kb-article-writer/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: altinity-kb-article-writer
+description: Write new Altinity Knowledge Base articles in the repository's established style, including section selection, target markdown file path, Hugo frontmatter, and full draft content. Use when asked to create or draft KB articles for ClickHouse topics in this repository.
+---
+
+# Altinity KB Article Writer
+
+Write a complete KB-ready draft that matches this repository's style.
+
+## Use this workflow
+
+1. Identify article intent from the prompt:
+- Problem statement or topic
+- Target audience (operator, developer, data engineer, mixed)
+- Desired depth (`quick how-to`, `troubleshooting`, `deep explanation`)
+- Environment constraints (Cloud, Kubernetes, replication, version constraints)
+
+2. Select the best section using `references/section-map.md`.
+
+3. Propose the destination path in this format:
+- `content/en/<section>/<slug>.md`
+
+4. Build frontmatter using the defaults in `references/kb-style-guide.md`:
+- Required: `title`, `linkTitle`, `description`
+- Optional: `keywords`, `weight` (only when explicitly needed for ordering)
+
+5. Draft the article using `references/article-template.md` and style rules:
+- Short practical intro
+- Clear `##` and `###` headings
+- Language-tagged code fences (`sql`, `bash`, `yaml`, `xml`, etc.)
+- Actionable examples and caveats
+- Related resources at the end
+
+6. Run a self-review using `references/qa-checklist.md`.
+
+7. Return output in this order:
+- Suggested path
+- Full markdown (frontmatter + body)
+- QA checklist result (pass/fail bullets)
+- If section routing is ambiguous, include one alternative path
+
+## Authoring rules
+
+- Prefer practical, operator-useful guidance over theory.
+- Use concise technical English.
+- Preserve ClickHouse naming and SQL syntax exactly.
+- Do not add uncommon frontmatter fields (`alias`, `manualLink`, redirects) unless explicitly requested.
+- Avoid unsupported claims; if unsure, state assumptions.
+
+## File and slug rules
+
+- Use lowercase kebab-case slugs.
+- Prefer `altinity-kb-<topic>.md` in sections where that convention is common.
+- If a likely collision exists, append a disambiguator (for example `-v2` or `-on-kubernetes`).
+

.claude/skills/altinity-kb-article-writer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Altinity KB Article Writer"
+  short_description: "Draft KB articles in local Altinity style"
+  default_prompt: "Use $altinity-kb-article-writer to draft a new KB article with section path, frontmatter, and full markdown in this repository style."

.claude/skills/altinity-kb-article-writer/references/article-template.md

@@ -0,0 +1,65 @@
+# KB Article Template
+
+Use this template as the baseline shape, then adjust to topic.
+
+```markdown
+---
+title: "<Human title>"
+linkTitle: "<Navigation title>"
+description: >
+    <One sentence summary of the page purpose.>
+keywords:
+  - <optional-keyword-1>
+  - <optional-keyword-2>
+---
+
+<Short practical intro: what this solves, when to use it.>
+
+## Problem
+
+<Describe symptom, failure mode, or task objective.>
+
+## Solution
+
+<Explain approach and why it works.>
+
+### Step 1: <Name>
+
+```sql
+-- or bash/yaml/etc
+```
+
+<Explain expected output or interpretation.>
+
+### Step 2: <Name>
+
+```sql
+-- or bash/yaml/etc
+```
+
+<Explain expected output or interpretation.>
+
+## Validation
+
+<How to confirm the fix/design works. Include checks and thresholds if relevant.>
+
+## Caveats
+
+- <Version caveat>
+- <Performance caveat>
+- <Operational caveat>
+
+## Related resources
+
+- [<Internal KB link>](</altinity-kb-.../>)
+- [<Official docs link>](https://clickhouse.com/docs/)
+```
+
+## Minimal variant
+
+For short pages (for example function or setting notes), keep:
+- frontmatter
+- short intro
+- one or two focused sections
+- at least one example block
+

.claude/skills/altinity-kb-article-writer/references/kb-style-guide.md

@@ -0,0 +1,71 @@
+# Altinity KB Style Guide (Repository Baseline)
+
+This guide captures the dominant style used under `content/en/**` in this repository.
+
+## Frontmatter defaults for normal KB pages
+
+Use:
+
+```yaml
+---
+title: "Page title"
+linkTitle: "Left nav title"
+description: >
+    One-sentence summary.
+---
+```
+
+Optional:
+- `keywords`: list of 2-5 useful search terms
+- `weight`: only if explicit ordering in section navigation is needed
+
+Avoid unless explicitly requested:
+- `manualLink`, `alias`/`aliases`, redirect `type`/`target`, `draft`
+
+## Content structure
+
+- Start with a short practical intro (1-3 paragraphs).
+- Use `##` for major sections and `###` for subsections.
+- Keep sections task-oriented:
+  - Context/problem
+  - Steps or examples
+  - Validation or expected outcome
+  - Caveats / edge cases
+
+## Code and command blocks
+
+- Use fenced blocks with language tags:
+  - `sql`, `bash`, `yaml`, `xml`, `json`, `text`
+- Keep runnable snippets minimal and focused.
+- Prefer realistic table/settings names.
+
+## Length
+
+KB articles are short. Median is ~430 words; 90% are under 1100.
+
+- Target under 1000 words; over 1500 needs a clear reason.
+- Cut mechanism write-ups, source-code walkthroughs, stack traces, and evidence
+  tables — those belong in the PR description. Give the operational rule and its
+  version scope, not the derivation.
+
+See the length budget in `AGENTS.md` for the authoritative wording.
+
+## Writing tone
+
+- Technical and direct.
+- Emphasize actionable guidance for operators and engineers.
+- Prefer concrete examples over abstract descriptions.
+- Use concise English; avoid marketing wording.
+
+## Links
+
+- Add internal KB links when relevant.
+- Add official external links for docs/blog/release notes.
+- End with a "Related resources" section when useful.
+
+## Filename and slug
+
+- Lowercase kebab-case filename.
+- Prefer `altinity-kb-<topic>.md` where section convention suggests it.
+- Place in best-fit section under `content/en`.
+

.claude/skills/altinity-kb-article-writer/references/qa-checklist.md

@@ -0,0 +1,43 @@
+# QA Checklist for Generated KB Articles
+
+Run this checklist before returning output.
+
+This checklist covers mechanical correctness only. Also answer the **Review
+questions** in `AGENTS.md` — they cover whether the reader needs the content, how
+you know the examples work, and whether the article actually solves the problem
+end-to-end. A draft can pass every box below and still be the wrong article.
+
+## Metadata
+
+- [ ] Path is under `content/en/<section>/`.
+- [ ] Filename uses lowercase kebab-case.
+- [ ] Frontmatter has `title`, `linkTitle`, `description`.
+- [ ] Optional fields are justified (`keywords`, `weight`).
+- [ ] Uncommon fields are not present unless requested.
+
+## Structure and readability
+
+- [ ] Intro clearly states problem and scope.
+- [ ] Headings are logical (`##` then `###`).
+- [ ] Steps or examples are easy to follow.
+- [ ] Caveats or assumptions are explicit.
+
+## Technical quality
+
+- [ ] SQL/commands are syntactically plausible.
+- [ ] Code fences include language tags.
+- [ ] Version-sensitive behavior is called out if relevant.
+- [ ] No unsupported claims are presented as facts.
+
+## Linking
+
+- [ ] Includes relevant internal KB links when possible.
+- [ ] Includes high-quality official external references when useful.
+
+## Final output contract
+
+- [ ] Output includes suggested path.
+- [ ] Output includes full markdown draft.
+- [ ] Output includes brief QA result (`PASS` or `FAIL` with reasons).
+- [ ] If routing was ambiguous, one alternative path is included.
+

.claude/skills/altinity-kb-article-writer/references/section-map.md

@@ -0,0 +1,48 @@
+# Section Map for `content/en`
+
+Select the section that best matches the user topic.
+
+## Primary routing rules
+
+- `altinity-kb-queries-and-syntax`
+  - SQL syntax, query behavior, joins, window functions, TTL syntax, query semantics
+- `altinity-kb-setup-and-maintenance`
+  - Operational troubleshooting, replication operations, backup/restore, upgrades in practice, cluster setup
+- `altinity-kb-schema-design`
+  - `ORDER BY`, `PARTITION BY`, materialized views, table modeling, codecs, LowCardinality design
+- `altinity-kb-integrations`
+  - Kafka, MySQL, Spark, BI tools, external systems and connectors
+- `altinity-kb-useful-queries`
+  - Reusable diagnostics queries against `system.*` and operational SQL snippets
+- `altinity-kb-dictionaries`
+  - External dictionaries, layouts, dictionary performance and configuration
+- `altinity-kb-functions`
+  - Function behavior, function-specific examples, expression patterns
+- `engines`
+  - Engine internals and engine-specific behavior (MergeTree family, Atomic, etc.)
+- `altinity-kb-kubernetes`
+  - Altinity Operator, Kubernetes deployment and networking issues
+- `upgrade`
+  - Upgrade strategy, compatibility notes, known upgrade pitfalls
+
+## Tie-break rules
+
+1. If article is mostly query text and reusable snippets, prefer `altinity-kb-useful-queries`.
+2. If article is mostly conceptual SQL behavior, prefer `altinity-kb-queries-and-syntax`.
+3. If topic is schema/key design, prefer `altinity-kb-schema-design`.
+4. If issue is runtime operations and incidents, prefer `altinity-kb-setup-and-maintenance`.
+5. If still ambiguous, choose the section with the highest overlap and provide one alternative path.
+
+## Path format
+
+Use:
+- `content/en/<section>/<slug>.md`
+
+Where:
+- `<slug>` is lowercase kebab-case
+- Prefix with `altinity-kb-` when it fits section naming patterns
+
+Examples:
+- `content/en/altinity-kb-useful-queries/altinity-kb-find-heavy-merges.md`
+- `content/en/altinity-kb-schema-design/altinity-kb-choosing-order-by-for-events.md`
+

AGENTS.md

@@ -2,6 +2,25 @@
 
 This repository contains overall-facing ClickHouse knowledge base articles. Optimize for correctness, safety, and reviewability. Do not optimize for large rewrites, cosmetic churn, or generic prose improvement.
 
+## Start here: read the style guide before writing
+
+Before drafting or substantially rewriting an article, read these. They are short —
+under 300 lines in total — and they encode the house style that this file only
+summarizes:
+
+| File | What it gives you |
+|---|---|
+| `.claude/skills/altinity-kb-article-writer/SKILL.md` | The authoring workflow, start to finish |
+| `.claude/skills/altinity-kb-article-writer/references/kb-style-guide.md` | Frontmatter defaults, structure, tone |
+| `.claude/skills/altinity-kb-article-writer/references/article-template.md` | The baseline article shape, plus a minimal variant |
+| `.claude/skills/altinity-kb-article-writer/references/section-map.md` | Which section an article belongs in |
+| `.claude/skills/altinity-kb-article-writer/references/qa-checklist.md` | Self-review before you hand the work back |
+
+Claude Code loads this directory as a skill automatically. Codex and other tools do
+not — read the files directly. Do not rely on inspecting neighbouring articles
+instead: sampling nearby files tells you the frontmatter shape but not the tone or
+length norms, which is where drafts most often go wrong.
+
 ## Mission
 
 When modifying an article, do all of the following:
@@ -157,6 +176,27 @@ Review generated commands carefully before executing them. Destructive actions c
 - Use tables only when they compress real information.
 - Keep appendix/reference links readable; avoid dumping long raw URLs into the body when a shorter reference style works.
 
+### Length budget
+
+KB articles are short by design. Across the 250 articles in `content/en`, the median
+is about 430 words and 90% are under 1100.
+
+- **Target: under 1000 words.**
+- **Over 1500 words needs a clear reason.** Only 13 of 250 articles are that long.
+- One closing `## Related resources` section. Do not also add a separate references list.
+
+Check before you finish:
+
+```bash
+wc -w content/en/<section>/<file>.md
+```
+
+If an article runs long, the cause is usually explanation that belongs in a commit
+message or a PR description rather than in the KB: mechanism write-ups, source-code
+walkthroughs, stack traces, or evidence tables justifying a claim. State the
+operational rule and the version it applies to; leave out the derivation. A reader
+needs to know what to do and when it breaks, not why the internals behave that way.
+
 ## Specific guidlines from other reviews (human add here)
 
 These are repository-specific lessons and should guide similar edits:
@@ -218,6 +258,42 @@ Choose the lightest valid outcome.
 
 Default to smaller.
 
+## Review questions
+
+The checklist below catches mechanical problems. These questions catch the ones that
+matter more. Answer them against the actual draft, not from memory, before handing
+work back.
+
+**Does the reader need this?**
+
+- Is it simple enough, but not simpler?
+- Does this detail change what the user should do?
+- Can this be explained with a simple example instead of implementation internals?
+- Is there anything here the reader simply doesn't need to know?
+
+Mechanism write-ups, source-code walkthroughs, and evidence tables almost always
+fail these. Being able to explain *why* the internals behave a certain way is not a
+reason to put it in the article. Put it in the pull request instead, where a
+reviewer wants it.
+
+**Is it true?**
+
+- How do you know this example actually works? Name the version and environment you
+  ran it on. "It should work" is not an answer.
+- Is every example copy-pasteable and tested? If you reformatted a tested example,
+  it is no longer tested — run it again.
+
+**Is it enough?**
+
+- Does it solve the user's problem end-to-end?
+
+This last question is the counterweight, and it carries as much weight as the other
+six combined. Everything above pushes toward cutting; only this one pushes toward
+keeping. Applied without it, the questions will happily strip an article down past
+useful. A warning that looks like an internals digression but changes what an
+operator configures is not a digression — it is the article. Cut derivations, not
+decisions.
+
 ## Final checklist
 
 Before finishing, verify all of the following:
@@ -232,5 +308,8 @@ Before finishing, verify all of the following:
 - Useful existing detail was not accidentally removed.
 - The diff is reviewable.
 - A human can verify each important claim quickly.
+- The style guide was read before drafting.
+- The article is within the length budget, or the reason it is not is stated.
+- The review questions above were answered against the draft.
 
 If any item above fails, reduce scope or stop at findings instead of forcing a patch.