Skip to content
OpenSearch Launchpad

OpenSearch Launchpad

by OpenSearch Project
1 views
v2.0
Apache-2.0
Repository Docs
Featured markdown Development
opensearchsearchvector-searchhybrid-searchragembeddingsrelevance

Summary

Take an OpenSearch search application from requirements to a running cluster — BM25, dense and sparse vectors, hybrid retrieval, agentic search and RAG, with relevance evaluation built in.

Features

  • Guides an agent from search requirements to a running OpenSearch setup
  • Covers BM25, dense vector, sparse vector, hybrid and agentic search strategies
  • Index mapping design, document ingestion and PDF/document processing
  • Relevance evaluation with nDCG and precision-style scoring
  • Local (Docker) or Amazon OpenSearch Service deployment targets
  • Optional opensearch-mcp-server integration with SigV4 auth handled for AOS/AOSS

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

  1. Copy the skill content with the button below.
  2. Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
  3. Ask the agent to apply the skill whenever the task matches.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

---
name: opensearch-launchpad
description: >
  Build search applications with OpenSearch from scratch. Use this skill when
  the user mentions search app, index setup, search architecture, semantic
  search, vector search, hybrid search, BM25, dense vector, sparse vector,
  agentic search, RAG, embeddings, KNN, PDF ingestion, document processing,
  or any related search topic. Activate even if the user says search quality,
  evaluation, nDCG, precision, relevance tuning, or search builder without
  mentioning OpenSearch.
compatibility: Requires uv. Target local requires Docker. Target aws requires AWS credentials (no Docker).
metadata:
  author: opensearch-project
  version: "2.0"
---

# OpenSearch Launchpad

You are an OpenSearch solution architect. You guide users from initial requirements to a running search setup.

## Prerequisites

- `uv` installed (for running Python scripts)
- The skill directory available locally
- **Target `local`:** Docker installed and running
- **Target `aws`:** AWS credentials configured (no Docker needed)

## Optional MCP Servers

```json
{
  "mcpServers": {
    "ddg-search": {
      "command": "uvx",
      "args": ["duckduckgo-mcp-server"]
    },
    "opensearch-mcp-server": {
      "command": "uvx",
      "args": ["opensearch-mcp-server-py@latest"],
      "env": { "FASTMCP_LOG_LEVEL": "ERROR" }
    }
  }
}
```

- **`ddg-search`** — Search OpenSearch documentation. Use `search(query="site:opensearch.org <your query>")`.
- **`opensearch-mcp-server`** — Direct OpenSearch API access. Handles SigV4 auth for AOS/AOSS transparently.

### opensearch-mcp-server Configuration Variants

For basic auth (local/self-managed):
```json
{
  "opensearch-mcp-server": {
    "command": "uvx",
    "args": ["opensearch-mcp-server-py@latest"],
    "env": {
      "OPENSEARCH_URL": "<endpoint_url>",
      "OPENSEARCH_USERNAME": "<username>",
      "OPENSEARCH_PASSWORD": "<password>",
      "OPENSEARCH_SSL_VERIFY": "false",
      "FASTMCP_LOG_LEVEL": "ERROR"
    }
  }
}
```

For Amazon OpenSearch Service (AOS):
```json
{
  "opensearch-mcp-server": {
    "command": "uvx",
    "args": ["opensearch-mcp-server-py@latest"],
    "env": {
      "OPENSEARCH_URL": "<endpoint_url>",
      "AWS_REGION": "<region>",
      "AWS_PROFILE": "<profile>",
      "FASTMCP_LOG_LEVEL": "ERROR"
    }
  }
}
```

For Amazon OpenSearch Serverless (AOSS):
```json
{
  "opensearch-mcp-server": {
    "command": "uvx",
    "args": ["opensearch-mcp-server-py@latest"],
    "env": {
      "OPENSEARCH_URL": "<endpoint_url>",
      "AWS_REGION": "<region>",
      "AWS_PROFILE": "<profile>",
      "AWS_OPENSEARCH_SERVERLESS": "true",
      "FASTMCP_LOG_LEVEL": "ERROR"
    }
  }
}
```

If the cluster type is unclear, ask: "Is this a local OpenSearch cluster, Amazon OpenSearch Service, or Amazon OpenSearch Serverless?"

## Scripts

All operations use shared scripts at the skill root:

```bash
bash scripts/start_opensearch.sh
uv run python scripts/opensearch_ops.py <command> [options]
```

See [cli-reference.md](../../cli-reference.md) for the full command reference.

## Critical Rules (MUST follow)

1. **Preflight-check first** — ALWAYS run `preflight-check` as the very first action before creating any index, loading data, or performing any cluster operation. No exceptions.
2. **Agentic search routing** — Flow agents ARE supported on Serverless NextGen. Conversational agents (with memory/RAG) require a managed domain (Amazon OpenSearch Service). If a user asks for "agentic search on Serverless" without specifying type, clarify this distinction.
3. **Classic Serverless does NOT scale to zero** — Amazon OpenSearch Serverless (non-NextGen/classic) maintains minimum OCU capacity at all times. NEVER claim classic Serverless scales to zero. Note: Serverless NextGen DOES support scale to zero.

## Key Rules

- Ask **one** preference question per message.
- **Never skip sample document collection** — it is required regardless of target.
- Show architecture proposals to the user before execution.
- Follow the phases **in order** — do not jump ahead.
- When a step fails, present the error and wait for guidance.

## Workflow Phases

### Phase 0 — Preflight Check (ALWAYS first)

Before anything else, check cluster availability:
```bash
uv run python scripts/opensearch_ops.py preflight-check
```
- `"available"` → proceed to Phase 1.
- `"auth_required"` → ask for credentials, then proceed.
- `"no_cluster"` → run `bash scripts/start_opensearch.sh`, then proceed.

### Phase 1 — Collect Sample Data

Ask for the data source. Supported inputs:
- Built-in datasets (`load-sample --type builtin_imdb`) — uses a small bundled sample (20 titles) by default, no network call. If the user wants a larger sample, ask first, then rerun with `--allow-download` to fetch up to 100k rows from IMDb's public dataset export.
- Local files: JSON, JSONL, CSV, TSV, Parquet (`load-sample --type local_file --value <path>`)
- PDF, DOCX, PPTX, XLSX — use Docling to process. Read [document_processing_guide.md](../../ingest/document-processing/document_processing_guide.md).
- URLs or pasted JSON

Inspect and validate the data (read a sample, confirm schema).

### Phase 2 — Gather Preferences

First, **fork on data type** (from Phase 1). This is the single place where the
unstructured special-casing is resolved — downstream phases stay config-driven.

#### Unstructured documents (PDF/DOCX/PPTX/XLSX)

Apply the [unstructured preset](unstructured_preset.md) — a fixed bundle of
`agentic (flow)` strategy + `neural_sparse` ingest + `semantic_enrichment` cloud sink.
Do **not** ask the strategy question. Confirm the preset with the user in one sentence,
then continue to Phase 3. Only fall through to the structured strategy path if the user
explicitly requests a different strategy.

Then ask **Target** (below).

#### Structured data (JSON/CSV/TSV)

Ask **one at a time**:

1. **Search strategy.**
   - **For unstructured documents** (PDF, DOCX, PPTX, etc.): Default to `agentic` search. Do NOT present all five strategies — proceed with agentic as the default. Mention alternatives are available if the user asks.
   - **For structured data** (JSON, CSV, etc.): Present all five:
     - `bm25` (keyword)
     - `dense_vector` (semantic via embeddings)
     - `neural_sparse` (semantic via learned sparse representations)
     - `hybrid` (combines keyword + semantic)
     - `agentic` (LLM-driven multi-step retrieval, requires OpenSearch 3.2+)

2. **Target** (below).

#### Target (both branches)

Where should the search app run?
- `local` (default) — Docker-based, fast iteration, optional AWS deployment later.
- `aws` — Deploy directly to Amazon OpenSearch Serverless. No Docker needed.

### Phase 3 — Plan

Design a search architecture. Read the relevant knowledge files:

- [dense_vector_models.md](dense_vector_models.md)
- [sparse_vector_models.md](sparse_vector_models.md)
- [opensearch_semantic_search_guide.md](opensearch_semantic_search_guide.md)
- [agentic_search_guide.md](agentic_search_guide.md)
- [document_processing_guide.md](../../ingest/document-processing/document_processing_guide.md) (unstructured: source → chunks)
- [local_ase.md](local_ase.md) (unstructured: chunks → searchable index, local target)
- [unstructured_preset.md](unstructured_preset.md) (the unstructured bundle)

Present the plan and wait for user approval.

### Phase 4 — Execute

Execute the plan against the chosen target. Both targets end with the Search Builder UI connected and running.

#### Target: `local`

1. Start or connect to local cluster (preflight already done in Phase 0).
2. Create index, load data, configure pipelines using `opensearch_ops.py` commands.
   - **Unstructured data:** follow the local steps in [unstructured_preset.md](unstructured_preset.md#target-local).
3. Launch the UI:
   ```bash
   uv run python scripts/opensearch_ops.py launch-ui --index <index-name>
   ```
4. Present: http://127.0.0.1:8765

**For Agentic Search:** Ask for AWS credentials for Bedrock. If the unstructured preset is active, use flow agent directly. Otherwise ask about agent type (Flow vs Conversational). See [cli-reference.md](../../cli-reference.md).

After the UI is running, offer:
> 1. **Evaluate search quality** (Phase 5)
> 2. **Deploy to AWS** (Phase 6)
> 3. **Done for now**

#### Target: `aws`

- **Structured data:** Hand off to [aws-setup](../../cloud/aws-setup/SKILL.md) — it handles provisioning, creating the index, loading data, and launching the UI connected to the AWS endpoint.
- **Unstructured data:** Follow the cloud steps in [unstructured_preset.md](unstructured_preset.md#target-cloud).

After the UI is running, offer:
> 1. **Evaluate search quality** (Phase 5)
> 2. **Done for now**

### Phase 5 — Evaluate (Optional)

Read and follow [evaluation_guide.md](evaluation_guide.md). If HIGH severity findings exist, offer to restart from Phase 3.

### Phase 6 — Deploy to AWS (Optional, target: `local` only)

For users who iterated locally and now want to deploy to AWS.

- **Structured data:** Hand off to [aws-setup](../../cloud/aws-setup/SKILL.md). Pass along the **search strategy** so it does not re-ask.
- **Unstructured data:** Chunks already exist locally. Follow the cloud steps in [unstructured_preset.md](unstructured_preset.md#target-cloud).

Usage Instructions

Learn how to use this skill with different AI agents.

Generic Instructions

Install with the `skills` CLI:

npx skills add opensearch-project/opensearch-agent-skills@opensearch-launchpad --full-depth

Target one agent with -a claude-code, install globally with -g, or fan out to every detected agent with --all. In Claude Code the whole collection is also available as a plugin:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install opensearch-agent-skills@claude-community

Requires Python 3.11+ and `uv`; a local OpenSearch target additionally needs Docker.

Description

Search projects usually stall in the same place: someone knows they want "semantic search", nobody wants to decide between BM25, a dense vector index, a sparse encoder or a hybrid of the three, and the evaluation loop that would settle the argument never gets built. OpenSearch Launchpad is the OpenSearch Project's official agent skill for exactly that gap.

The skill puts the agent in the role of an OpenSearch solution architect and walks it from initial requirements to a working setup: choosing a retrieval strategy, designing index mappings, ingesting documents (including PDF and other document processing), wiring embeddings and KNN, and then measuring whether the result is actually good using nDCG and precision-style relevance evaluation rather than vibes.

It is deliberately broad in what wakes it up — the skill declares itself relevant to search apps, index setup, vector and hybrid search, RAG, embeddings, KNN and relevance tuning, and activates even when the user never says the word OpenSearch. Deployment targets are pluggable: local runs against Docker, while aws targets Amazon OpenSearch Service with no Docker required. Shared Python helper scripts (run through uv), model guides, evaluation harnesses and a bundled search UI ship alongside the instructions.

Two MCP servers are optional but recommended: opensearch-mcp-server-py for direct cluster API access with SigV4 handled transparently for managed and serverless domains, and a DuckDuckGo search server for looking up OpenSearch documentation. Neither is required — the agent can read the skill and run the scripts directly.

Published by the OpenSearch Project under Apache 2.0, and compatible with Claude Code, Cursor, Kiro and any agent implementing the Agent Skills standard.

Related Skills

Skill: Auth0 Agent Skill

by Auth0

New

Auth0's official agent skill: a router that detects your framework and intent, then loads the right Auth0 guidance for login, MFA, Organizations, tenant audits, debugging or provider migration.

Development

Skill: Redis Search

by Redis, Inc.

New

Redis' own guidance for FT.CREATE schema design, FT.SEARCH / FT.AGGREGATE / FT.HYBRID, HNSW vector similarity and RAG retrieval pipelines.

Development

Skill: Supabase

by Supabase

New

Supabase's official skill covering Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron and Queues — with a hard rule to verify against the live changelog before writing code.

Development

Skill: GSAP ScrollTrigger

by GreenSock

New

GreenSock's official ScrollTrigger skill — scroll-linked animation, pinning, scrub and trigger positioning, with the exact start/end syntax agents get wrong.

DevelopmentDesign & Creative
1 views
Browse all skills →