Agent Skills for Apache Doris

Agent skills for Apache Doris in the open Agent Skills (SKILL.md) format — usable by Claude Code, Cursor, Codex, Cline, Amp, and other agent tools.

A skill is the decision logic an agent is missing: what evidence to collect, how to read it, which conclusion it does and does not support. Everything here is Apache Doris kernel knowledge — vendor-neutral, no downstream distribution's branding.

The repository covers two kinds of work:

• Working with a cluster — designing tables, sizing, diagnosing production incidents, reading query profiles.
• Working on Doris itself — contributor workflows against an apache/doris source checkout.

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

Skills

Every skill is self-contained — install all of them or only the ones you need. Agents select a skill from its description, so in practice you describe the problem and the right one loads.

Working with a cluster

Working on Doris itself

These skills read a Doris source checkout and never touch a cluster; the cluster-side skills never touch repository source. Nothing here builds Doris or runs tests. The one GitHub write in the whole set is doris-repo-review's PASS comment — posted only when the review finds no Blocker and no Major, and only after the user has seen the exact body and approved it.

Install

The open skills CLI works across agent tools (Claude Code, Cursor, Codex, Cline, Amp, …), auto-discovers every skill in this repository, and bundles their references/ and scripts/:

npx skills add apache/doris-skills

Or copy them in manually:

cp -r skills/* ~/.claude/skills/          # all of them
cp -r skills/doris-debug ~/.claude/skills/   # or just one

Then describe your problem — the agent loads the matching skill on its own:

Optional: doriscli

The cluster-side 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; the skills are the “brain” — the decision logic that reads that JSON and recommends table designs, sizing, and fixes.

The recommended install 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 doris-cli repository.

doriscli is optional: without it the skills fall back automatically to plain MySQL-protocol SQL plus the FE HTTP API (see cli-investigation.md). The exact commands and JSON fields the skills depend on are listed in CLI-CONTRACT.md — keep that file and doriscli in sync.

doris-repo-review does not use doriscli; it needs git, an authenticated gh CLI, jq, and python3.

Verification

The factual claims in the cluster-side skills are regression-tested — against a real Apache Doris cluster, against doriscli, and against the skills' own runtime behavior — so they do not 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.

A skill that makes no DDL or doriscli claim (doris-debug, doris-profile-reader, doris-repo-review) has no L1/L2 coverage today. Adding cases for a new skill is welcome but not a merge requirement.

Contributing a skill

A skill is one directory under skills/:

skills/<skill-name>/
├── SKILL.md          # required — frontmatter + the workflow the agent follows
├── references/       # optional — depth the agent loads on demand
├── scripts/          # optional — deterministic work better done in code than by the model
└── <domain>/         # optional — nested sub-skills, each with its own SKILL.md (see doris-debug)

SKILL.md starts with name and description frontmatter. The description is the only thing the router sees, so it must state what the skill does and when to reach for it, in the words a user would actually type. Keep SKILL.md itself to the decision logic and push depth into references/ — the agent reads those on demand.

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.
• Add a row to the matching table above so the skill is discoverable from this README.

Layout

doris-skills/
├── README.md
├── CLI-CONTRACT.md                 # doriscli commands + JSON fields the skills depend on
├── skills/
│   ├── doris-best-practices/       # cluster-side: table design, sizing, query investigation
│   ├── doris-architecture-advisor/ # cluster-side: workload → architecture
│   ├── doris-debug/                # cluster-side: symptom router + 10 nested domain skills
│   ├── doris-profile-reader/       # cluster-side: query profile → bottleneck
│   └── doris-repo-review/          # contributor-side: reviews an apache/doris PR, not a cluster
└── verify/                         # regression suite — L1 DDL, L2 CLI contract, L3 behavior

License

Apache-2.0