elastic-caveman

why use many token when few token do trick — for Elasticsearch

An Agent Skill that brings token-efficient "caveman mode" to the Elastic stack. Based on JuliusBrussee/elastic-caveman (17k+ stars), purpose-built for Elasticsearch, Kibana, ES|QL, Elastic Security, and Elastic Observability workflows.

Designed to layer on top of the official elastic/agent-skills. Install Elastic skills for the knowledge. Install caveman to stop the yapping.

Before / After

| 🗣️ Normal (208 tokens) | 🪨 Caveman (52 tokens) | |---|---| | "Sure thing! I'd be happy to help you write that ES|QL query. What you're looking for is a query that will filter for open tickets with critical priority and group them by product area. Here's how you can accomplish this using ES|QL: FROM support-tickets \| WHERE status == "Open" AND priority == "Critical" \| STATS count = COUNT(*) BY product_area \| SORT count DESC \| LIMIT 100 This query works by first selecting all records from the support-tickets index, then filtering for only those with status Open and priority Critical. It then groups the results by the product_area field, counts the number of tickets in each group, sorts in descending order by count to show the product areas with the most critical open tickets first, and applies a safety limit of 100 rows though there are likely fewer product areas than this. Feel free to modify the time range or add additional filters as needed. Let me know if you'd like any adjustments!" | FROM support-tickets \| WHERE status == "Open" AND priority == "Critical" \| STATS count = COUNT(*) BY product_area \| SORT count DESC \| LIMIT 100 — Filters open + critical, groups by product_area, counts, sorts desc. |

Same query. Same accuracy. 75% less word. Brain still big.

┌──────────────────────────────────────────────────┐
│  TOKENS SAVED            ████████████████  63.6% │
│  TECHNICAL ACCURACY      ████████████████  100%  │
│  ES|QL PRESERVED         ████████████████  100%  │
│  API PATHS PRESERVED     ████████████████  100%  │
│  FIELD NAMES PRESERVED   ████████████████  100%  │
│  FILLER WORDS REMAINING  ░░░░░░░░░░░░░░░░  ~0%  │
│  VIBES                   ████████████████  OOG   │
└──────────────────────────────────────────────────┘

Live Eval — Real Elastic Instance

Not just claims. We tested against a live Elastic MCP endpoint with real support-tickets and salesforce-cases data. Full results in EVAL.md.

| Scenario | MCP Tool | Normal | Caveman | Saved | |---|---|---|---|---| | List indices | platform_core_list_indices | 107 | 14 | 86.9% | | Get index mapping | platform_core_get_index_mapping | 143 | 40 | 72.0% | | Generate ES|QL | platform_core_generate_esql | 208 | 52 | 75.0% | | Execute ES|QL | platform_core_execute_esql | 149 | 44 | 70.5% | | Search tickets | platform_core_search | 221 | 143 | 35.3% | | Search escalated | platform_core_search | 198 | 128 | 35.4% | | Stats by priority | platform_core_execute_esql | 140 | 36 | 74.3% | | Total | | 1,284 | 467 | 63.6% |

Range: 35–92% savings depending on query type. Metadata queries save the most (92%). Data-heavy search results still save 35% because the data itself is the content — caveman no compress data, only compress fluff around data.

Why This Exists

Every AI agent working with Elasticsearch wraps perfectly good API responses in paragraphs of filler:

• "Of course! I'd be happy to help you see your indices." — you asked. obviously agent will help.
• "This information is really helpful for writing queries" — you know. that why you asked.
• "Feel free to modify the time range or add additional filters" — you always could.
• "Let me know if you'd like any adjustments!" — you will. without being invited.

Multiply this across every GET /_cat/shards, every ES|QL query, every ILM debug session. That's thousands of wasted output tokens per conversation — tokens you're paying for, tokens that slow response time, tokens that bury the actual answer in a wall of text.

Caveman fix. One install. Every Elastic response becomes just signal, no noise.

A March 2026 paper "Brevity Constraints Reverse Performance Hierarchies in Language Models" found that constraining large models to brief responses improved accuracy by 26 percentage points on certain benchmarks. Verbose not always better. Sometimes less word = more correct.

Install

Pick your agent. One command. Done.

| Agent | Install Command | |---|---| | Claude Code | npx skills add srikolag/elastic-caveman -a claude-code | | Cursor | npx skills add srikolag/elastic-caveman -a cursor | | Codex | npx skills add srikolag/elastic-caveman -a codex | | Windsurf | npx skills add srikolag/elastic-caveman -a windsurf | | GitHub Copilot | npx skills add srikolag/elastic-caveman -a github-copilot | | Gemini CLI | npx skills add srikolag/elastic-caveman -a gemini-cli | | Roo | npx skills add srikolag/elastic-caveman -a roo | | All agents | npx skills add srikolag/elastic-caveman --all |

Install once. Done. Caveman persist.

Manual Install

git clone https://github.com/srikolag/elastic-caveman.git
cp -r elastic-caveman/elastic-caveman ~/.agents/skills/

Supported Agent Directories

| Agent | Skill Directory | |---|---| | Claude Code | .claude/skills/elastic-caveman/ | | Cursor | .agents/skills/elastic-caveman/ | | Codex | .agents/skills/elastic-caveman/ | | Windsurf | .windsurf/skills/elastic-caveman/ | | Roo | .roo/skills/elastic-caveman/ | | GitHub Copilot | .agents/skills/elastic-caveman/ | | Gemini CLI | .agents/skills/elastic-caveman/ |

Usage

Trigger with:

• /elastic-caveman
• caveman mode
• less tokens please
• talk like a caveman
• be terse

Stop with: stop caveman or normal mode or /verbose

| Phrase | Action | |---|---| | /elastic-caveman | Activate caveman mode | | caveman mode | Activate caveman mode | | less tokens please | Activate caveman mode | | be terse | Activate caveman mode | | stop caveman | Deactivate — normal prose | | normal mode | Deactivate — normal prose | | /verbose | Deactivate — normal prose |

What Caveman Smash vs. Keep

| 🪨 Smash (remove) | 🧠 Keep (preserve verbatim) | |---|---| | Articles: a / an / the | Elasticsearch API paths (PUT /_index_template/...) | | Filler openers ("Sure! I'd be happy to...") | Query DSL and ES|QL syntax | | Hedging ("It might be worth considering...") | Field names (event.category, source.ip) | | Repetition of what user just said | Index patterns (logs-*, .ds-*) | | Passive voice (when active shorter) | Kibana UI labels (Discover, Dev Tools) | | Transition fluff ("Additionally...") | Error messages and stack traces — verbatim | | Closing pleasantries ("Let me know!") | Code inside fences — syntactically correct | | Obvious statements | Technical nouns (shard, replica, ILM, pipeline) | | | Version numbers and cluster names |

Before / After — More Examples

Index Mapping

Normal (143 tokens):

Great question! Let me look up the mapping for the support-tickets index so you can see all the available fields and their types. This information is really helpful for writing queries and understanding how your data is structured. Here's what I found:

account_id [keyword], account_name [keyword], case_id [keyword], created_date [date], days_open [integer], description [text], priority [keyword], product_area [keyword], sentiment_score [float], status [keyword], subject [text]

As you can see, you have 11 fields with a good mix of types. If you'd like to query any of these fields or need help writing an ES|QL query, feel free to ask!

Caveman (40 tokens):

support-tickets mapping: account_id keyword, account_name keyword, case_id keyword, created_date date, days_open integer, description text, priority keyword, product_area keyword, sentiment_score float, status keyword, subject text

72% reduction. Every field name and type preserved exactly.

ILM Debug

Normal (149 tokens):

I understand you're having trouble with your ILM policy not rolling over. This is actually a fairly common issue, and there are several things we should check. First, let me explain that ILM policies require certain conditions to be met before a rollover occurs. Common reasons include: the index wasn't created with a write alias, rollover conditions not met yet, lifecycle.poll_interval too high, ILM step in ERROR state. You can check with GET /logs-000001/_ilm/explain. Hope that helps track down the issue!

Caveman (44 tokens):

Check ILM: GET /logs-000001/_ilm/explain. Common rollover failures: 1) missing write alias, 2) conditions not met, 3) lifecycle.poll_interval too high, 4) ILM step in ERROR state.

70% reduction. Every API path and technical term intact.

Layering with elastic/agent-skills

elastic-caveman is built to work alongside the official elastic/agent-skills. It does not override technical guidance — skills like elasticsearch-esql, elasticsearch-authz, kibana-alerting-rules, and elasticsearch-security-troubleshooting still provide correct Elastic-specific instructions. Caveman only compresses the prose wrapping around that guidance.

Recommended Install Order

# 1. Install official Elastic skills first (the knowledge)
npx skills add elastic/agent-skills

# 2. Install caveman last (the compression)
npx skills add srikolag/elastic-caveman

Caveman applies last, compressing output from all skills. Knowledge stay. Fluff go.

Tip: Don't install every Elastic skill. Each installed skill adds routing context. Install elasticsearch-esql and the auth skills, then add only what you need. Then add caveman on top. Lean and mean.

How It Works

This is an Agent Skill — a SKILL.md file with YAML frontmatter and markdown instructions that any compatible AI agent reads and follows. The description field in the frontmatter tells the agent when to activate it.

No runtime. No binary. No API calls. Just a markdown file that reshapes how your agent talks when working with Elastic.

elastic-caveman/
├── README.md
├── EVAL.md                      # Live eval results from real Elastic instance
├── LICENSE                      # Apache 2.0
├── .gitattributes
├── elastic-caveman/
│   └── SKILL.md                 # The agent skill
└── scripts/
    ├── validate-skill.sh        # Lint SKILL.md frontmatter
    └── eval-harness.py          # Reproduce eval against any Elastic MCP endpoint

Validate

bash scripts/validate-skill.sh
# PASS: elastic-caveman/SKILL.md frontmatter is valid

Contributing

1. Fork this repo
2. Edit elastic-caveman/SKILL.md
3. Run bash scripts/validate-skill.sh — must pass
4. Open a PR

Skill follows the agentskills.io specification. Keep rules in markdown. Keep YAML frontmatter valid. Keep code examples syntactically correct.

Star This Repo

If caveman save you mass token on Elastic queries — leave mass star. ⭐

License

Apache 2.0 — same as elastic/agent-skills. See LICENSE.

Copyright 2026 Sri Kolagani