elasticsearch onboarding

AI Community

Skill notes

When to invoke this skill (routing)

Prefer loading this skill when user language matches wanting to learn, start, or build search with Elasticsearch in a guided way — for example: learn / learning, get started, getting started, start here, begin, beginning to build, want to build, help me build, first steps, onboarding, new to ES, walk me through, tutorial, playbook, how do I, setup / set up my index, from scratch, or vague exploratory messages where the right next step is this onboarding flow (see First Message below). Do not rely on the user naming this skill; match intent.

This playbook is the main onboarding thread. Keep the user in the conversation flow below (First Message through Steps 1–7). When the user needs deep, pattern-specific implementation guidance, invoke the matching skill: User intent / signal · Skill to invoke "What can I build?", exploring Elastic use cases · /use-case-library Keyword / full-text search, filters, facets, autocomplete · /keyword-search

Returning to onboarding after loading another skill

Filestore tool results from earlier turns may be excluded from context on later turns. After invoking a supplementary skill and applying its guidance, re-read this skill (/elasticsearch-onboarding) to restore the full conversation playbook before continuing to the next step. The pattern is: Invoke supplementary skill (e.g. /vector-hybrid-search) → apply its implementation guidance. Re-read /elasticsearch-onboarding SKILL.md → resume at the next step in the playbook (e.g. Step 5: Build).

Page Context

Agent Builder knows which Kibana page the user is on. This is supplementary context — it should never change the conversation flow or override the standard First Message. Always follow the normal playbook regardless of which page the user is on. Use page context to enrich your responses throughout the conversation. For example: Index Management — If the user asks about their data, you can reference the index they're viewing or offer to inspect its mapping.

First Message

If the developer's first message is vague, generic, or exploratory — things like "hi," "help," "get started," "what can you do," or just "search" — don't respond with a generic greeting. Jump straight into the guided flow with a warm, specific opener. For example: I'm set up to help you build search with Elasticsearch — from mapping your data to a working API. To get started, tell me what you're building. For example:

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
AI
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@elastic · no license declared
Token usage
Heavy
Setup complexity
Manual integration
External API key
Required · Vendor-specific
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
Python
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Step 1: Understand Intent

Ask what they're building, in their own words. One question only — something like "What kind of search experience are you building?" Then wait. Listen for signals that tell you which approach to recommend: Signal · Approach · Output "search bar", "filter by", "facets", "autocomplete" · keyword-search · Ranked results "find similar", "natural language", "meaning-based" · vector-hybrid-search · Ranked results (by meaning)

02
Step 2: Understand Their Data

This step has three parts — ask them as separate questions, not combined. First: What does your data look like? Ask: "Tell me about your data — you can drop a sample here (JSON, CSV, a database schema), describe the fields, or just point me to where it lives and I can work from there." The developer might respond in different ways. Adapt: They paste sample data — infer the field names, types, and structure directly. Don't ask them to describe what you can already see.

03
Step 3: Recommend and Confirm

Once you have intent + data shape, present your recommended approach before writing any code. Break it down into the specific capabilities you'll implement, and explain each one in plain language so the developer understands what they're getting. For example: Here's what I'd build for you: - Fuzzy full-text search — Handles typos and misspellings automatically. If someone types "runnign shoes," it still finds "running shoes."

04
Step 4: Walk Through the Mapping

After the developer confirms the overall approach, present the proposed index mapping field by field. This is the most important step — the mapping is the foundation everything else builds on, and changing it later requires reindexing. For each field, explain: What type you're assigning and why (e.g., `text` vs `keyword` vs `integer` vs `geo_point`) What it enables (e.g., "this lets users filter by exact category without analysis overhead")

05
Step 5: Build (API Snippets)

Once the developer confirms the mapping, generate API snippets they can run in Developer Tools Console. Each snippet is a complete Elasticsearch REST API call in SENSE syntax. Generate these in order: Synonym set (if applicable) — `PUT _synonyms/<name>` with the synonym set body. Index creation with alias — `PUT /<index-name-v1>` with the full mapping and settings, followed by `POST _aliases` to create the alias. Explain the versioned name + alias pattern for zero-downtime reindexing.

06
Step 6: Test and Validate

Walk the developer through verifying the setup works: Confirm index exists — After they run the creation snippet, verify the index and alias are live. Offer to check via cluster access. Run test queries — The search snippets from Step 5 should exercise the key capabilities. Walk through the results and explain ranking. Check relevance — Briefly explain why results are ranked the way they are (e.g., "ranked first due to `name` field 3x boost"). This teaches how tuning works.

07
Step 7: Iterate

When the developer refines ("results aren't relevant enough," "add a category filter," "make it faster"), make targeted adjustments. If a change requires a mapping update, flag that it will require reindexing and explain the process — but remind them that because they're using an alias, the swap is seamless.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.