elasticsearch-onboarding

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

- **Unprompted** — never open on your own connection or credential status. A cluster you cannot reach is not the

Audit 0.4.1 · source sha 30fcdedc45a1 · 28 Oct 2026Report an issue or request a re-scan

• Publisherelastic GitHub organizationOwner of the repository this skill is read from
• Source folderelastic/agent-skills/skills/elasticsearch/elasticsearch-onboardingThe exact folder we audited
• LicenceApache-2.0As the repository states it
• Commit pinned for this verdict30fcdedc45a1A new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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…

---
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 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.
metadata:
  author: elastic
  version: 0.3.0
  universal: true
---

# 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](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.

<!-- begin-partial: preamble -->

## Environment Configuration

This skill executes Elasticsearch operations through the `elastic` CLI. If the
[`elastic` CLI](https://github.com/elastic/cli#configuration) 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](#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.

<!-- end-partial: preamble -->

## Cluster Access

Cluster interaction splits into **reads** and **writes**. Load
[references/cluster-access/cluster-access.md](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](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`                                                       

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-28
   !CAUTION B 89 / 100

   first audit · source 30fcdedc45a1

Questions about elasticsearch-onboarding

• github.com/elastic/agent-skills/tree/main/skills/elasticsearch/e — the audited source at commit 30fcdedc45a1 and every finding aboveObserved · 28 Oct 2026

Spotted something wrong? Report a correction · Methodology