Agent Skills for Apache Doris

Apache Doris agent skills in the open Agent Skills (SKILL.md) format — usable by
Claude Code, Cursor, Codex, Cline, Amp, and other agent tools. This repository contains the
kernel knowledge for any Apache Doris deployment: table design, sizing, query
investigation, and architecture decisions.

The skills pair with doriscli, the Apache Doris CLI (companion doris-cli
repository). doriscli is the "hands" — it runs SQL, fetches and parses query profiles,
and analyzes tablet distribution, all as structured JSON; these skills are the "brain" —
the decision logic that reads that JSON and recommends table designs, sizing, and fixes.
doriscli is optional: when it is not installed the skills fall back to plain
MySQL-protocol SQL plus the FE HTTP API, so they work with or without it (see
skills/doris-best-practices/references/cli-investigation.md).

The exact doriscli commands and JSON fields the skills depend on are listed in
CLI-CONTRACT.md — keep that file and doriscli in sync.

Cluster-lifecycle, billing, and networking operations are managed-service specific and
intentionally out of scope here; use your platform's cluster-management console for those.

Skills

How to use

Install with the open skills CLI — it works
across agent tools (Claude Code, Cursor, Codex, Cline, Amp, …), auto-discovers both
skills in this repo, and bundles their references/:

npx skills add apache/doris-skills

Or copy them in manually:

cp -r skills/* ~/.claude/skills/

For the structured-diagnosis path (query profiles, tablet health), also install
doriscli. The recommended way is from npm, which ships prebuilt binaries (no
Rust toolchain, no compile step):

npm install -g @apache-doris/doriscli
doriscli --version

For other platforms, or to build from source, see the companion doris-cli
repository. Without doriscli, the skills use the SQL + HTTP fallback automatically.

Verification

The factual claims in these skills are regression-tested — against a real Apache Doris
cluster, against doriscli, and against the skills' own runtime behavior — so they don't
drift from reality. See verify/; it runs in three layers:

• L1 — knowledge: every DDL template and gotcha in doris-best-practices is accepted
  or rejected by a live cluster exactly as the skill claims (mysql client).
• L2 — CLI contract: every command and JSON field in CLI-CONTRACT.md
  really resolves against doriscli on a live cluster (doriscli --format json + jq).
• L3 — behavior: the skills behave as written — evidence-first and safety guardrails,
  an end-to-end advisor→DDL→live-cluster loopback, and skill-router triggering — exercised
  through a nested claude -p.

Authoring rules

• Write doriscli and Apache Doris directly. Never introduce a downstream
  distribution's brand strings — CLI names, console URLs, env-var prefixes, hostnames.
• Cloud-mode behavior (storage-compute separation, replication_num=1, file cache) is
  Doris kernel architecture — describe it neutrally as "cloud mode" / "storage-compute".
  Managed-service behavior (suspend/resume, automatic node-count management, billing) is
  out of scope; point at the user's cluster-management console rather than naming a product.
• If you rely on a new doriscli command or output field, add it to
  CLI-CONTRACT.md so the two repositories stay in sync.

Layout

doris-skills/
├── README.md
├── CLI-CONTRACT.md            # doriscli commands + JSON fields the skills depend on
├── skills/
│   ├── doris-best-practices/
│   └── doris-architecture-advisor/
└── verify/                    # regression suite for the skills' claims — L1 DDL, L2 CLI, L3 behavior

License

Apache-2.0