elasticsearch-onboarding

elastic/agent-skills

Guide developers from zero to a working Elasticsearch search experience with best practices.

What is elasticsearch-onboarding?

This skill helps developers new to Elasticsearch understand search concepts, map their data effectively, and build production-ready search experiences. Use it when users want to build search functionality, ask about Elasticsearch concepts, or need onboarding guidance.

Guide developers through understanding their search intent and use case
Help design and validate data mappings for optimal search performance
Generate tested, production-ready code for search implementations
Recommend appropriate search approaches (keyword, vector, semantic, RAG)
Explain Elasticsearch best practices like versioned indices with aliases
Support multiple programming languages and search patterns

How to install elasticsearch-onboarding

npx skills add https://github.com/elastic/agent-skills --skill elasticsearch-onboarding

Prerequisites

Elasticsearch 9.x instance or cluster
Understanding of your data structure and search requirements

Claude Code

Cursor

Windsurf

Cline

How to use elasticsearch-onboarding

1.Describe your search use case or intent to the skill
2.Answer questions about your data shape and search goals one at a time
3.Review and confirm the recommended data mapping before code generation
4.Specify your preferred programming language
5.Receive generated, production-ready code following Elasticsearch best practices

Use cases

Good for

Building a search experience for an e-commerce site with product discovery
Setting up a RAG pipeline with Elasticsearch and LLM integration
Implementing semantic search using ELSER embeddings or vector search
Designing data models for complex search requirements before implementation
Combining keyword and vector search results with reciprocal rank fusion (RRF)

Who it's for

Developers new to Elasticsearch
Teams building search-powered applications
Engineers implementing RAG or semantic search pipelines
Developers migrating to Elasticsearch from other search solutions

elasticsearch-onboarding FAQ

When should I use this skill?

Use it when you want to build search functionality, need help understanding Elasticsearch concepts for your use case, or are getting started with Elasticsearch for the first time.

Will the skill generate code immediately?

No. The skill follows a structured conversation to understand your intent and data first. Code is only generated once you confirm the approach and data mapping.

What search patterns does this skill support?

It supports keyword search (BM25), vector/semantic search, RAG pipelines, kNN search, ELSER embeddings, and hybrid approaches combining multiple search types.

Do I need to know Elasticsearch before using this skill?

No. The skill is designed for developers new to Elasticsearch and explains concepts and decisions in accessible terms.

Why does the skill emphasize data mapping?

Data mapping is the most expensive thing to change later in production. The skill guides you through mapping design upfront to avoid costly refactoring.

Full instructions (SKILL.md)

Source of truth, from elastic/agent-skills.

name: elasticsearch-onboarding description: > 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. compatibility: Elasticsearch 9.x metadata: author: elastic version: 0.1.0

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.

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.
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.