OpenSearch Skills
This is the top-level skill for OpenSearch. It contains four category skills that can also be installed and used independently:
| Category |
Skill |
Install individually |
| search |
opensearch-launchpad |
npx skills add opensearch-project/opensearch-agent-skills@opensearch-launchpad --full-depth |
| observability |
log-analytics |
npx skills add opensearch-project/opensearch-agent-skills@log-analytics --full-depth |
| observability |
trace-analytics |
npx skills add opensearch-project/opensearch-agent-skills@trace-analytics --full-depth |
| cloud |
aws-setup |
npx skills add opensearch-project/opensearch-agent-skills@aws-setup --full-depth |
| cloud |
aiven-setup |
npx skills add opensearch-project/opensearch-agent-skills@aiven-setup --full-depth |
| ingest |
document-processing |
npx skills add opensearch-project/opensearch-agent-skills@document-processing --full-depth |
| cloud |
managed-ingestion-service |
npx skills add opensearch-project/opensearch-agent-skills@managed-ingestion-service --full-depth |
Routing
Route to the right skill based on user intent:
| User Intent |
Skill |
| Build a search app, set up an index, choose a search strategy |
opensearch-launchpad |
| Analyze logs, query with PPL, discover error patterns |
log-analytics |
| Investigate traces, debug spans, analyze service maps |
trace-analytics |
| Deploy to AWS, provision a domain or collection |
aws-setup |
| Deploy to Aiven, provision a managed OpenSearch service |
aiven-setup |
| Process documents into chunks (PDF/DOCX → JSONL) |
document-processing |
| Ingest chunks at scale via OSIS, S3 to AOS/AOSS |
managed-ingestion-service |
| General OpenSearch question |
Search docs first, then route to the relevant skill |
If the user's intent spans multiple skills (e.g., "build a search app and deploy it to Aiven"), start with the appropriate skill and transition to the next when ready.
Feedback Collection (Required Behavior)
This applies to ALL skills in this collection — opensearch-launchpad, log-analytics, trace-analytics, aws-setup, aiven-setup, document-processing, and managed-ingestion-service. Regardless of which skill is active, you MUST follow these rules.
You MUST proactively collect feedback during every interaction. This is not optional — treat it as a core part of the workflow, not an afterthought.
Rules
- Monitor continuously — watch for failures, confusion, and unmet needs throughout the conversation, not just at the end.
- Offer immediately on failure — when any command errors or a step doesn't work, immediately offer to capture feedback before troubleshooting.
- Offer on uncertainty — if you're unsure how to proceed or the skill doesn't cover the user's request, flag it as a potential gap and offer to submit.
- Ask at natural breakpoints — after completing a major phase (not just at the very end), ask "Is this working as expected? Any friction so far?"
- Always ask at end — when the user says they're done or the workflow completes, ask for a 1-5 rating.
- Never send without consent — show the preview, get explicit "yes".
Triggers
| When |
What to do |
| Command returns non-zero exit or error |
→ Immediately: "That failed. Can I capture this as feedback?" |
| User says "that's not what I wanted" / "this is confusing" / expresses frustration |
→ "Sounds like friction. Can I note what went wrong?" |
| User asks for something you can't do |
→ "This isn't supported yet. Can I flag this as a feature gap?" |
| A workaround is needed (something should be simpler) |
→ "That was more steps than it should be. Can I flag this as friction?" |
| Major phase completes |
→ "How's it going so far? Any issues?" |
| User says "done" or workflow ends |
→ "How was the overall experience? (1-5)" |
How to Submit
Requires uv installed (for running Python scripts)
- Compose the feedback (type + context).
- Show preview to user.
- Ask: "May I submit this anonymous feedback?"
- On consent:
uv run python scripts/opensearch_ops.py submit-feedback \
--type <failure|gap|friction|success> \
--skill <skill-name> \
--context "<error message, command, what happened>" \
--comment "<user's words>" \
--rating "<1-5, for success only>"
Feedback Types
failure — A command or step produced an error
gap — User needs something the skill doesn't support
friction — Workflow was confusing, slow, or required workarounds
success — Workflow completed, user satisfied
Shared Resources
All skills share these resources:
- Scripts:
scripts/opensearch_ops.py — CLI for all OpenSearch operations
- Docker bootstrap:
scripts/start_opensearch.sh — Start a local OpenSearch cluster
- CLI Reference: cli-reference.md — Full command reference with examples
- Search Builder UI:
scripts/ui/ — React frontend served on port 8765
bash scripts/start_opensearch.sh
uv run python scripts/opensearch_ops.py <command> [options]
uv run python scripts/opensearch_ops.py --help
Optional MCP Servers
{
"mcpServers": {
"ddg-search": {
"command": "uvx",
"args": ["duckduckgo-mcp-server"]
},
"awslabs.aws-api-mcp-server": {
"command": "uvx",
"args": ["awslabs.aws-api-mcp-server@latest"],
"env": { "FASTMCP_LOG_LEVEL": "ERROR" }
},
"aws-knowledge-mcp-server": {
"command": "uvx",
"args": ["fastmcp", "run", "https://knowledge-mcp.global.api.aws"],
"env": { "FASTMCP_LOG_LEVEL": "ERROR" }
},
"opensearch-mcp-server": {
"command": "uvx",
"args": ["opensearch-mcp-server-py@latest"],
"env": { "FASTMCP_LOG_LEVEL": "ERROR" }
}
}
}
Auto-Installing Missing MCP Servers
Before using any MCP tool, check if the server is available. If missing:
- Locate the MCP config file:
- Kiro:
.kiro/settings/mcp.json
- Cursor:
.cursor/mcp.json
- Claude Code:
.mcp.json
- VS Code (Copilot):
.vscode/mcp.json
- Windsurf:
~/.codeium/windsurf/mcp_config.json
- Read the existing config (or start with
{"mcpServers": {}}).
- Merge in the missing server entry. Do not overwrite existing entries.
- Save and inform the user to restart or reconnect MCP servers.
Answering OpenSearch Knowledge Questions
uv run python scripts/opensearch_ops.py search-docs --query "<your query>"
uv run python scripts/opensearch_ops.py search-docs --query "<query>" --site docs.aws.amazon.com
1---
2name: opensearch-skills
3description: >
4 Build search applications and query log analytics data with OpenSearch.
5 Use this skill when the user mentions OpenSearch, search app, index setup,
6 search architecture, semantic search, vector search, hybrid search, BM25,
7 dense vector, sparse vector, agentic search, RAG, embeddings, KNN, PDF
8 ingestion, document processing, or any related search topic. Also use for
9 log analytics and observability — when the user wants to set up log
10 ingestion, query logs with PPL, analyze error patterns, set up index
11 lifecycle policies, investigate traces, or check stack health. Activate
12 even if the user says log analysis, Fluent Bit, Fluentd, Logstash, syslog,
13 traceId, OpenTelemetry, or log analytics without mentioning OpenSearch.
14compatibility: Requires Docker and uv. AWS deployment requires AWS credentials.
15metadata:
16 source: https://skillmd.com/skills/opensearch-project/opensearch-skills
17 author: opensearch-project
18 version: "2.0"
19---
20
21# OpenSearch Skills
22
23This is the top-level skill for OpenSearch. It contains four category skills that can also be installed and used independently:
24
25| Category | Skill | Install individually |
26|---|---|---|
27| [search](search/SKILL.md) | [opensearch-launchpad](search/opensearch-launchpad/SKILL.md) | `npx skills add opensearch-project/opensearch-agent-skills@opensearch-launchpad --full-depth` |
28| [observability](observability/SKILL.md) | [log-analytics](observability/log-analytics/SKILL.md) | `npx skills add opensearch-project/opensearch-agent-skills@log-analytics --full-depth` |
29| [observability](observability/SKILL.md) | [trace-analytics](observability/trace-analytics/SKILL.md) | `npx skills add opensearch-project/opensearch-agent-skills@trace-analytics --full-depth` |
30| [cloud](cloud/SKILL.md) | [aws-setup](cloud/aws-setup/SKILL.md) | `npx skills add opensearch-project/opensearch-agent-skills@aws-setup --full-depth` |
31| [cloud](cloud/SKILL.md) | [aiven-setup](cloud/aiven-setup/SKILL.md) | `npx skills add opensearch-project/opensearch-agent-skills@aiven-setup --full-depth` |
32| [ingest](ingest/SKILL.md) | [document-processing](ingest/document-processing/SKILL.md) | `npx skills add opensearch-project/opensearch-agent-skills@document-processing --full-depth` |
33| [cloud](cloud/SKILL.md) | [managed-ingestion-service](cloud/managed-ingestion-service/SKILL.md) | `npx skills add opensearch-project/opensearch-agent-skills@managed-ingestion-service --full-depth` |
34
35## Routing
36
37Route to the right skill based on user intent:
38
39| User Intent | Skill |
40|---|---|
41| Build a search app, set up an index, choose a search strategy | [opensearch-launchpad](search/opensearch-launchpad/SKILL.md) |
42| Analyze logs, query with PPL, discover error patterns | [log-analytics](observability/log-analytics/SKILL.md) |
43| Investigate traces, debug spans, analyze service maps | [trace-analytics](observability/trace-analytics/SKILL.md) |
44| Deploy to AWS, provision a domain or collection | [aws-setup](cloud/aws-setup/SKILL.md) |
45| Deploy to Aiven, provision a managed OpenSearch service | [aiven-setup](cloud/aiven-setup/SKILL.md) |
46| Process documents into chunks (PDF/DOCX → JSONL) | [document-processing](ingest/document-processing/SKILL.md) |
47| Ingest chunks at scale via OSIS, S3 to AOS/AOSS | [managed-ingestion-service](cloud/managed-ingestion-service/SKILL.md) |
48| General OpenSearch question | Search docs first, then route to the relevant skill |
49
50If the user's intent spans multiple skills (e.g., "build a search app and deploy it to Aiven"), start with the appropriate skill and transition to the next when ready.
51
52## Feedback Collection (Required Behavior)
53
54**This applies to ALL skills in this collection** — opensearch-launchpad, log-analytics, trace-analytics, aws-setup, aiven-setup, document-processing, and managed-ingestion-service. Regardless of which skill is active, you MUST follow these rules.
55
56You MUST proactively collect feedback during every interaction. This is not optional — treat it as a core part of the workflow, not an afterthought.
57
58### Rules
59
601. **Monitor continuously** — watch for failures, confusion, and unmet needs throughout the conversation, not just at the end.
612. **Offer immediately on failure** — when any command errors or a step doesn't work, immediately offer to capture feedback before troubleshooting.
623. **Offer on uncertainty** — if you're unsure how to proceed or the skill doesn't cover the user's request, flag it as a potential gap and offer to submit.
634. **Ask at natural breakpoints** — after completing a major phase (not just at the very end), ask "Is this working as expected? Any friction so far?"
645. **Always ask at end** — when the user says they're done or the workflow completes, ask for a 1-5 rating.
656. **Never send without consent** — show the preview, get explicit "yes".
66
67### Triggers
68
69| When | What to do |
70|------|------------|
71| Command returns non-zero exit or error | → Immediately: "That failed. Can I capture this as feedback?" |
72| User says "that's not what I wanted" / "this is confusing" / expresses frustration | → "Sounds like friction. Can I note what went wrong?" |
73| User asks for something you can't do | → "This isn't supported yet. Can I flag this as a feature gap?" |
74| A workaround is needed (something should be simpler) | → "That was more steps than it should be. Can I flag this as friction?" |
75| Major phase completes | → "How's it going so far? Any issues?" |
76| User says "done" or workflow ends | → "How was the overall experience? (1-5)" |
77
78### How to Submit
79
80Requires `uv` installed (for running Python scripts)
81
821. Compose the feedback (type + context).
832. Show preview to user.
843. Ask: "May I submit this anonymous feedback?"
854. On consent:
86
87```bash
88uv run python scripts/opensearch_ops.py submit-feedback \
89 --type <failure|gap|friction|success> \
90 --skill <skill-name> \
91 --context "<error message, command, what happened>" \
92 --comment "<user's words>" \
93 --rating "<1-5, for success only>"
94```
95
96### Feedback Types
97
98- `failure` — A command or step produced an error
99- `gap` — User needs something the skill doesn't support
100- `friction` — Workflow was confusing, slow, or required workarounds
101- `success` — Workflow completed, user satisfied
102
103## Shared Resources
104
105All skills share these resources:
106
107- **Scripts**: `scripts/opensearch_ops.py` — CLI for all OpenSearch operations
108- **Docker bootstrap**: `scripts/start_opensearch.sh` — Start a local OpenSearch cluster
109- **CLI Reference**: [cli-reference.md](cli-reference.md) — Full command reference with examples
110- **Search Builder UI**: `scripts/ui/` — React frontend served on port 8765
111
112```bash
113bash scripts/start_opensearch.sh
114uv run python scripts/opensearch_ops.py <command> [options]
115uv run python scripts/opensearch_ops.py --help
116```
117
118## Optional MCP Servers
119
120```json
121{
122 "mcpServers": {
123 "ddg-search": {
124 "command": "uvx",
125 "args": ["duckduckgo-mcp-server"]
126 },
127 "awslabs.aws-api-mcp-server": {
128 "command": "uvx",
129 "args": ["awslabs.aws-api-mcp-server@latest"],
130 "env": { "FASTMCP_LOG_LEVEL": "ERROR" }
131 },
132 "aws-knowledge-mcp-server": {
133 "command": "uvx",
134 "args": ["fastmcp", "run", "https://knowledge-mcp.global.api.aws"],
135 "env": { "FASTMCP_LOG_LEVEL": "ERROR" }
136 },
137 "opensearch-mcp-server": {
138 "command": "uvx",
139 "args": ["opensearch-mcp-server-py@latest"],
140 "env": { "FASTMCP_LOG_LEVEL": "ERROR" }
141 }
142 }
143}
144```
145
146## Auto-Installing Missing MCP Servers
147
148Before using any MCP tool, check if the server is available. If missing:
149
1501. Locate the MCP config file:
151 - Kiro: `.kiro/settings/mcp.json`
152 - Cursor: `.cursor/mcp.json`
153 - Claude Code: `.mcp.json`
154 - VS Code (Copilot): `.vscode/mcp.json`
155 - Windsurf: `~/.codeium/windsurf/mcp_config.json`
1562. Read the existing config (or start with `{"mcpServers": {}}`).
1573. Merge in the missing server entry. Do not overwrite existing entries.
1584. Save and inform the user to restart or reconnect MCP servers.
159
160## Answering OpenSearch Knowledge Questions
161
162```bash
163uv run python scripts/opensearch_ops.py search-docs --query "<your query>"
164uv run python scripts/opensearch_ops.py search-docs --query "<query>" --site docs.aws.amazon.com
165```