Elasticsearch Onboarding

ElasticOfficialCreated by elastic

Skill
Workflow
Software development
Apache-2.0
Low risk

From the author

Help developers new to Elasticsearch get from zero to a working search experience. Guide them through understanding their intent, mapping their data, and building a search experience with best practices baked in. Use this when the user shows intent to build search-related functionality, asks about Elasticsearch-related concepts for their use case, or expresses the need for help getting started with Elasticsearch.

— the description by elastic

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill acts as an Elasticsearch solutions architect, guiding developers from initial intent to a production-ready search implementation. It follows a structured playbook to understand user requirements, inspect existing cluster data, and provide best-practice recommendations for mapping and search architecture. The skill emphasizes an educational approach, requiring explicit confirmation before performing any write operations on the cluster.

What it does

Guides developers through the end-to-end process of building a search experience.
Automatically inspects cluster state, including versions, indices, and mappings.
Provides best-practice advice on data modeling and search relevance.
Generates tested, production-ready code snippets for Elasticsearch operations.
Requires explicit developer approval before executing any cluster-mutating write operations.
Translates high-level search goals into specific API calls using the elastic CLI.

When to use it

When a developer is new to Elasticsearch and needs help getting started.
When a user expresses intent to build search features like e-commerce catalogs or RAG pipelines.
When a developer needs guidance on mapping data or optimizing search relevance.
When a user asks about specific Elasticsearch concepts like kNN, ELSER, or ES|QL.

Advantages

Ensures best practices are applied from the start, reducing the need for future reindexing.
Maintains an educational focus by explaining decisions and requiring confirmation for changes.
Reduces friction by automatically gathering cluster context before making recommendations.
Provides a safe environment for experimentation with clear separation between reads and writes.

Usage examples

“I want to build a search experience for my e-commerce site.”: The agent will initiate the onboarding playbook, ask about the product catalog structure, and begin inspecting the current cluster to propose a mapping strategy.
“How do I build a RAG pipeline with Elasticsearch?”: The agent will guide the user through setting up embeddings, mapping vector fields, and configuring the search pipeline for semantic retrieval.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/elastic/elasticsearch-onboarding/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip elasticsearch-onboarding.zip -d .agents/skills

Documentation by elastic

Elastic Developer Guide

You are an Elasticsearch solutions architect working alongside the developer. Your job is to guide developers from "I want search" to a working search experience — understanding their intent, recommending the right approach, and generating tested, production-ready code. Use the conversation playbook in references/elasticsearch-onboarding-playbook.md to structure the conversation. Always ask one question at a time, listen for signals, and adapt your recommendations to their specific use case and data shape.

Environment Configuration

This skill executes Elasticsearch operations through the elastic CLI. If the elastic CLI is not installed, tell the user what it is needed for. Do not guess credentials, call the HTTP API directly, or attempt other workarounds.

This skill references operations in HTTP-shorthand form (e.g., GET /, GET /_cat/indices, GET /{index}/_mapping, GET /{index}/_settings/index.mode, POST /_query). The Operations table at the end of this document maps each shorthand to the equivalent elastic CLI command — always use the CLI rather than calling the HTTP API directly.

Cluster Access

Cluster interaction splits into reads and writes. Load references/cluster-access/cluster-access.md for the full protocol.

Reads happen automatically. Ground every recommendation in the developer's actual cluster rather than asking them to describe it. Detect the version with GET /, list indices with GET /_cat/indices, read field types with GET /{index}/_mapping, check volume with GET /{index}/_count, and validate relevance by running real queries with POST /{index}/_search or POST /_query.

Writes require confirmation. Before PUT /{index}, POST /_aliases, POST /_bulk, PUT /_ingest/pipeline/{name}, or PUT /_synonyms/{id}, show the developer the exact call you intend to make and wait for approval. Never mutate the cluster silently — this is an educational experience, and the developer needs to see what is being created.

Don't volunteer connection state; do answer connection questions. Two different situations, and the distinction matters:

Unprompted — never open on your own connection or credential status. A cluster you cannot reach is not the developer's first problem; understanding what they want to build is. Lead with the use-case question, and mention a failed read only at the moment it actually blocks you, in one sentence attached to the question you were already asking. Onboarding works fine before any cluster exists.
When the developer explicitly asks how to connect their IDE, editor, or chat client — that request is the task. Answer it fully and concretely from the appendix in references/cluster-access/cluster-access.md, then ask the use-case question at the end. Deflecting a direct setup question into discovery is a failure, not restraint.

Examples

Example user intents that should trigger this skill:

"I want to build a search experience for my e-commerce site"
"How do I get started with Elasticsearch?"
"What are the best practices for building a search experience?"
"Can you help me understand how to model my data for search?"
"How do I build a vector database?"
"I want to build a RAG pipeline with Elasticsearch"
"How do I use EIS for embeddings?"
"How do I connect an LLM to Elasticsearch?"
"How do I do kNN search in Elasticsearch?"
"How do I use ELSER for semantic search?"
"How do I set up the Elasticsearch MCP?"
"How do I combine keyword and vector results with RRF?"
"I want NLP-powered search"
"What's the difference between BM25 and vector search?"
"Can I use ES|QL to query my data?"

Guidelines

Ask one question at a time, then wait.
Don't lead with tooling, connection, or credential setup unprompted — lead with what the developer is building. But if they directly ask how to connect, answer that question fully before moving on.
Only generate code once the user confirms the approach and the mapping.
Use the Synonyms API for synonym management, not a custom-built solution.
Always use a versioned index name + alias (e.g. products_v1 + products_current) and explain why.
Explain decisions briefly, assume the user does not understand Elasticsearch yet.
Always go through the mapping walkthrough — it's the most expensive thing to change later.
Ask what programming language the user wants to use, don't assume.
Avoid generating code with deprecated APIs. If you must use a deprecated API for some reason, explain why and warn about future compatibility issues.

Operations

HTTP API (shorthand)	`elastic` CLI command
`GET /`	`elastic es info`
`GET /_cat/indices`	`elastic es cat indices --index '<pattern>'`
`GET /{index}/_mapping`	`elastic es indices get-mapping --index '<index>'`
`GET /{index}/_count`	`elastic es count --index '<index>'`
`POST /{index}/_search`	`elastic es search --index '<index>' --input-file '<search-body.json>'`
`POST /_query`	`elastic es esql query --format tsv --query "<esql>"`
`PUT /{index}`	`elastic es indices create --index '<index>' --mappings '<json>' --aliases '<json>'`
`POST /_aliases`	`elastic es indices update-aliases --actions '<json>'`
`POST /_bulk`	`elastic es bulk --index '<index>' --input-file '<ndjson-path>'`
`PUT /_ingest/pipeline/{name}`	`elastic es ingest put-pipeline --id '<name>' --input-file '<json-path>'`
`PUT /_synonyms/{id}`	`elastic es synonyms put-synonym --id '<id>' --synonyms-set '<json>'`

Files

ATTRIBUTION.mdAdded by AutoGineer995 B
LICENSELicence file added by AutoGineer11.1 KiB
SKILL.md7.1 KiB
references/catalog-ecommerce/ecommerce.md15.7 KiB
references/cluster-access/cluster-access.md10.2 KiB
references/code-generation/code-generation.md6.7 KiB
references/elasticsearch-onboarding-playbook.md24.0 KiB
references/keyword-search/keyword-search.md9.9 KiB
references/rag-chatbot/rag-chatbot.md15.7 KiB
references/search-ui/search-ui.md21.1 KiB
references/use-case-library/use-case-library.md10.2 KiB
references/vector-hybrid-search/vector-hybrid-search.md20.8 KiB

references/keyword-search/keyword-search.md

name: keyword-search description: Guide for building keyword/full-text search with Elasticsearch. Use when a developer wants text matching, filters, faceted search, autocomplete, or traditional search functionality.

Keyword Search Guide

Guide developers through building full-text keyword search with Elasticsearch. Use this guide when they need text matching, filters, faceting, autocomplete, or traditional search-bar behavior.

1. When to Use This Guide

Apply this guide when the developer signals:

Structured data — products, articles, documents with known fields (title, description, category, price)
Exact matching matters — SKUs, IDs, categories, status values must match precisely
Simple search bar — user types terms and expects documents containing those terms
Filtering and faceting — filter by category, price range, brand; show facet counts
Autocomplete / typeahead — suggest completions as user types
No semantic intent — "red shoes" should match documents containing "red" and "shoes", not "crimson sneakers"

Do not use this guide when: natural language queries return poor results, user expects meaning-based matching, or multilingual semantic similarity is needed. Point them to the vector-hybrid-search guide instead.

2. Index Mapping

Create a mapping with text fields (for full-text search), keyword sub-fields (for exact filtering and sorting), and completion fields (for autocomplete).

Example: products index

PUT /products
{
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "fields": {
          "keyword": { "type": "keyword" }
        },
        "analyzer": "standard"
      },
      "description": {
        "type": "text",
        "fields": {
          "keyword": { "type": "keyword" }
        },
        "analyzer": "standard"
      },
      "category": {
        "type": "keyword"
      },
      "brand": {
        "type": "keyword"
      },
      "price": { "type": "float" },
      "rating": { "type": "float" },
      "created_at": { "type": "date" },
      "title_suggest": {
        "type": "completion",
        "analyzer": "simple",
        "preserve_separators": true,
        "preserve_position_increments": true,
        "max_input_length": 50
      }
    }
  }
}

text + keyword — title and description are searchable; title.keyword and description.keyword support exact match, sorting, aggregations.
keyword — category, brand use for filters and faceting.
completion — title_suggest powers autocomplete.

Synonyms (optional): Use the Elasticsearch Synonyms API so synonyms can be updated without reindexing:

PUT _synonyms/my-synonyms
{
  "synonyms_set": [
    { "id": "wireless", "synonyms": "wireless, bluetooth" }
  ]
}

Then reference the synonym set in a custom analyzer and apply it as a search_analyzer (not the index analyzer) so synonym updates take effect without reindexing:

{
  "settings": {
    "analysis": {
      "analyzer": {
        "synonym_search_analyzer": {
          "tokenizer": "standard",
          "filter": ["lowercase", "synonym_filter"]
        }
      },
      "filter": {
        "synonym_filter": {
          "type": "synonym_graph",
          "synonyms_set": "my-synonyms",
          "updateable": true
        }
      }
    }
  }
}

Apply to fields with "search_analyzer": "synonym_search_analyzer" (keep the default standard analyzer for indexing).

3. Ingestion

Use the bulk API with error handling. Index documents in batches.

from elasticsearch import Elasticsearch, helpers

es = Elasticsearch(cloud_id="...", api_key="...")

def index_products(documents: list[dict]) -> tuple[int, list]:
    """Index documents into products index. Returns (success_count, errors)."""
    actions = []
    for doc in documents:
        doc["title_suggest"] = {"input": doc.get("title", "").split()}
        actions.append({
            "_index": "products",
            "_source": doc
        })

    success, errors = helpers.bulk(
        es,
        actions,
        raise_on_error=False,
        raise_on_exception=False,
        request_timeout=30
    )

    if errors:
        for err in errors:
            if "index" in err and err["index"].get("error"):
                print(f"Error indexing doc: {err['index']['error']}")
    return success, errors

4. Query Patterns

Basic Match Query

GET /products/_search
{
  "query": {
    "match": {
      "title": "wireless headphones"
    }
  }
}

Multi-Match Across Fields

GET /products/_search
{
  "query": {
    "multi_match": {
      "query": "wireless headphones",
      "fields": ["title^2", "description"],
      "type": "best_fields",
      "operator": "or"
    }
  }
}

Bool Query with Filters

GET /products/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "title": "wireless headphones" } }
      ],
      "filter": [
        { "term": { "category": "electronics" } },
        { "range": { "price": { "gte": 50, "lte": 500 } } }
      ]
    }
  }
}

Fuzzy Matching (Typo Tolerance)

GET /products/_search
{
  "query": {
    "match": {
      "title": {
        "query": "wirless headphons",
        "fuzziness": "AUTO"
      }
    }
  }
}

Autocomplete with Completion Suggester

GET /products/_search
{
  "suggest": {
    "title-suggest": {
      "prefix": "wire",
      "completion": {
        "field": "title_suggest",
        "skip_duplicates": true,
        "size": 10
      }
    }
  }
}

Highlighting

GET /products/_search
{
  "query": { "match": { "title": "wireless headphones" } },
  "highlight": {
    "fields": {
      "title": {},
      "description": {}
    }
  }
}

Pagination

GET /products/_search
{
  "query": { "match_all": {} },
  "from": 20,
  "size": 10,
  "sort": [{ "price": "asc" }]
}

ES|QL (Where Applicable)

ES|QL supports filtering and sorting. Use for simple filter + sort queries:

FROM products
| WHERE category == "electronics" AND price >= 50 AND price <= 500
| SORT rating DESC
| LIMIT 20

For full-text search, match queries, or fuzzy matching, ES|QL does not yet support these; use Query DSL.

5. API Endpoint

Wrap the search in a Flask endpoint:

from flask import Flask, request, jsonify
from elasticsearch import Elasticsearch

app = Flask(__name__)
es = Elasticsearch(cloud_id="...", api_key="...")

@app.route("/search", methods=["GET"])
def search():
    q = request.args.get("q", "")
    category = request.args.get("category")
    min_price = request.args.get("min_price", type=float)
    max_price = request.args.get("max_price", type=float)
    page = request.args.get("page", 1, type=int)
    size = request.args.get("size", 10, type=int)

    must = [{"match": {"title": q}}] if q else []
    filter_clauses = []
    if category:
        filter_clauses.append({"term": {"category": category}})
    if min_price is not None:
        filter_clauses.append({"range": {"price": {"gte": min_price}}})
    if max_price is not None:
        filter_clauses.append({"range": {"price": {"lte": max_price}}})

    body = {
        "query": {
            "bool": {
                "must": must if must else [{"match_all": {}}],
                "filter": filter_clauses
            }
        },
        "from": (page - 1) * size,
        "size": size,
        "highlight": {"fields": {"title": {}, "description": {}}}
    }

    resp = es.search(index="products", body=body)
    return jsonify({
        "hits": [h["_source"] for h in resp["hits"]["hits"]],
        "total": resp["hits"]["total"]["value"],
        "page": page
    })

6. Relevance Tuning

Field boosting — "fields": ["title^2", "description"] weights title matches higher.
Function score — boost by rating, recency, or custom logic:

{
  "query": {
    "function_score": {
      "query": { "match": { "title": "headphones" } },
      "functions": [{ "field_value_factor": { "field": "rating", "modifier": "log1p" } }],
      "boost_mode": "sum"
    }
  }
}

Custom analyzers — use synonym filter, edge n-gram for prefix matching, or language-specific analyzers.
Synonyms — add synonym filter for domain terms (e.g., "headphones" ↔ "earphones").

7. Common Follow-Ups

Question	Answer
"How do I add filters?"	Add `filter` clauses to a `bool` query. Use `term` for exact match, `range` for numeric/date ranges.
"How do I handle typos?"	Use `fuzziness: "AUTO"` in match queries, or `match_phrase_prefix` for prefix matching.
"How do I add autocomplete?"	Add a `completion` field to the mapping, populate it during indexing, use the suggest API.
"How do I paginate?"	Use `from` and `size`. For deep pagination, prefer `search_after` with a sort key.

8. When to Upgrade

Suggest hybrid or semantic search when:

Natural language queries return poor results (e.g., "comfortable headphones for running" doesn't match well).
Multilingual content — keyword search doesn't handle cross-language similarity.
"Find similar" — user wants items similar to a selected item, not just keyword overlap.
Synonyms and paraphrasing — synonym lists are too large or maintenance-heavy.

Direct the developer to the vector-hybrid-search guide for vector search, hybrid search (combining keyword + vector with RRF), or using Elasticsearch as a vector store.

Search UI frontend — Need to build the search page? Use the search-ui guide to add a React-based frontend with a search bar, facets, autocomplete, and pagination on top of this index. Connects directly to the Elasticsearch index via the Elasticsearch connector.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

The author says: Elasticsearch 8.x or 9.x, self-managed, Elastic Cloud Hosted, or Elastic Cloud Serverless. Requires the `elastic` CLI with `stack es` support for cluster reads and writes.

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

elastic

Publisher

Elastic (Official)

Source

elastic/agent-skills · skills/elasticsearch/elasticsearch-onboarding · commit 09d879d

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

Also distributed in

elastic/agent-skills

AutoGineer is not affiliated with or endorsed by elastic.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download elasticsearch-onboarding.zip