opensearch-skills

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

1. Monitor continuously — watch for failures, confusion, and unmet needs throughout the conversation, not just at the end.
2. Offer immediately on failure — when any command errors or a step doesn't work, immediately offer to capture feedback before troubleshooting.
3. 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.
4. 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?"
5. Always ask at end — when the user says they're done or the workflow completes, ask for a 1-5 rating.
6. 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)

1. Compose the feedback (type + context).
2. Show preview to user.
3. Ask: "May I submit this anonymous feedback?"
4. 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:

1. 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
2. Read the existing config (or start with {"mcpServers": {}}).
3. Merge in the missing server entry. Do not overwrite existing entries.
4. 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