elasticsearch-best-practices

Elasticsearch development best practices for indexing, querying, and search optimization

Quality

45%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./elasticsearch-best-practices/SKILL.md

Quality

Content

57%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill excels at actionability with comprehensive, executable JSON examples covering the full Elasticsearch surface area. However, it suffers from being a monolithic reference document that tries to cover everything in one file, lacking progressive disclosure and clear multi-step workflows with validation checkpoints. It would be significantly improved by restructuring into a concise overview with references to topic-specific files.

Suggestions

Split the content into focused reference files (e.g., QUERIES.md, MAPPINGS.md, ILM.md, SECURITY.md) and keep SKILL.md as a concise overview with navigation links to each topic.

Add explicit numbered workflows with validation steps for destructive operations like reindexing and alias swapping (e.g., verify source index, create destination, validate document count, swap alias).

Remove field type descriptions and basic concept explanations (filter vs must context, what keyword type does) that Claude already knows, keeping only the non-obvious guidance and examples.

Add a verification/validation step after bulk indexing workflows (e.g., check document count, verify mapping, test a sample query) to prevent silent data issues.

Dimension	Reasoning	Score
Conciseness	The skill is fairly efficient with its JSON examples serving as documentation, but it's overly comprehensive for a single SKILL.md file. Field type descriptions (keyword, text, date, etc.) and basic concepts like what filter context does are things Claude already knows. The sheer length (~400+ lines) with many sections that could be trimmed or split into separate files hurts token efficiency.	2 / 3
Actionability	The skill provides fully executable JSON examples for every concept—mappings, queries, aggregations, bulk indexing, ILM policies, security roles, reindexing, and more. All examples are copy-paste ready with realistic field names and values, making them immediately usable.	3 / 3
Workflow Clarity	While individual operations are clear, multi-step workflows lack explicit sequencing and validation checkpoints. For example, the bulk indexing section mentions disabling refresh but doesn't provide a clear numbered workflow with verification steps. Reindexing and alias swapping—potentially destructive operations—lack validation/rollback guidance.	2 / 3
Progressive Disclosure	This is a monolithic wall of content with no references to external files and no layered structure. All content—from basic mappings to ILM policies to security roles—is inlined in a single file. With no bundle files, this ~400+ line document would benefit greatly from splitting into focused reference files (e.g., QUERIES.md, MAPPINGS.md, SECURITY.md) with a concise overview in SKILL.md.	1 / 3
	Total	8 / 12 Passed

Description

32%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description identifies the technology domain (Elasticsearch) and lists broad capability areas but lacks specificity in concrete actions and completely omits explicit trigger guidance ('Use when...'). It reads more like a topic label than a skill description that would help Claude reliably select it from a large pool of skills.

Suggestions

Add an explicit 'Use when...' clause with trigger scenarios, e.g., 'Use when the user asks about Elasticsearch index mappings, search queries, query DSL, analyzers, or cluster configuration.'

List more specific concrete actions instead of broad categories, e.g., 'Create and configure index mappings, write Query DSL queries, optimize search relevance with custom analyzers, manage index lifecycle policies.'

Include common keyword variations users might use: 'ES', 'elastic', 'ELK stack', 'Lucene', 'search relevance', 'aggregations', 'bulk indexing'.

Dimension	Reasoning	Score
Specificity	Names the domain (Elasticsearch) and mentions some actions (indexing, querying, search optimization), but these are broad categories rather than specific concrete actions like 'create index mappings, write DSL queries, configure analyzers'.	2 / 3
Completeness	Describes what at a high level (best practices for indexing, querying, search optimization) but completely lacks any 'Use when...' clause or explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, missing 'Use when' caps completeness at 2, and the 'what' is also weak, so this scores a 1.	1 / 3
Trigger Term Quality	Includes relevant keywords like 'Elasticsearch', 'indexing', 'querying', and 'search optimization' that users might naturally say, but misses common variations like 'ES', 'elastic', 'search queries', 'mappings', 'analyzers', 'DSL', or '.yml config'.	2 / 3
Distinctiveness Conflict Risk	Elasticsearch is a specific technology which helps distinguish it, but 'querying' and 'search optimization' are broad enough to potentially overlap with other database or search-related skills. The lack of explicit triggers increases conflict risk.	2 / 3
	Total	7 / 12 Passed

Validation

90%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (584 lines); consider splitting into references/ and linking	Warning

	Total	10 / 11 Passed

Repository: mindrally/skills
Path: elasticsearch-best-practices/SKILL.md
Commit: 05a7130

Reviewed: about 4 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.