elasticsearch-best-practices

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

Quality

48%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./elasticsearch-best-practices/SKILL.md

Quality

Discovery

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 a clear technology domain (Elasticsearch) and lists relevant capability areas, but lacks the explicit trigger guidance ('Use when...') that is critical for skill selection. The actions mentioned are category-level rather than concrete, and the description would benefit from more natural user terms and explicit usage triggers.

Suggestions

Add a 'Use when...' clause with explicit triggers like 'Use when the user asks about Elasticsearch, ES clusters, index mappings, search queries, or Elastic Stack'

Make capabilities more concrete by listing specific actions like 'design index mappings, write search queries, configure analyzers, optimize query performance'

Include common term variations users might say: 'ES', 'elastic', 'ELK', 'full-text search', 'aggregations', 'DSL queries'

Dimension	Reasoning	Score
Specificity	Names the domain (Elasticsearch) and mentions three action areas (indexing, querying, search optimization), but these are high-level categories rather than concrete specific actions like 'create index mappings' or 'write aggregation queries'.	2 / 3
Completeness	Describes what (Elasticsearch best practices for indexing/querying/optimization) but completely lacks any 'Use when...' clause or explicit trigger guidance for when Claude should select this skill.	1 / 3
Trigger Term Quality	Includes 'Elasticsearch', 'indexing', 'querying', and 'search optimization' which are relevant keywords, but misses common variations users might say like 'ES', 'elastic', 'full-text search', 'mappings', 'aggregations', or 'DSL'.	2 / 3
Distinctiveness Conflict Risk	Elasticsearch is a specific technology which helps distinguish it, but 'search optimization' and 'querying' could overlap with other database or search-related skills without clearer boundaries.	2 / 3
	Total	7 / 12 Passed

Implementation

64%

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

This is a comprehensive Elasticsearch reference with excellent actionable code examples covering most common operations. However, it's overly long for a single skill file and lacks validation workflows for complex operations like reindexing. The content would benefit from being split into focused sub-documents with better progressive disclosure.

Suggestions

Split into multiple files (QUERIES.md, MAPPINGS.md, SECURITY.md) with SKILL.md as a concise overview pointing to each

Add explicit validation steps for multi-step operations like reindexing (e.g., verify document counts, check for errors in response)

Remove basic field type explanations that Claude already knows, keeping only the Elasticsearch-specific guidance

Add a workflow section for common tasks like 'zero-downtime reindex' with numbered steps and validation checkpoints

Dimension	Reasoning	Score
Conciseness	The content is mostly efficient with good code examples, but includes some unnecessary explanatory text like listing field types that Claude already knows, and some sections could be tightened (e.g., the field types list is basic knowledge).	2 / 3
Actionability	Excellent actionability with fully executable JSON examples throughout, covering mappings, queries, aggregations, bulk operations, and maintenance commands. All examples are copy-paste ready.	3 / 3
Workflow Clarity	While individual operations are clear, multi-step processes like reindexing or bulk indexing lack explicit validation checkpoints. The bulk indexing section mentions disabling refresh but doesn't include verification steps to confirm success.	2 / 3
Progressive Disclosure	Content is well-organized with clear section headers, but it's a monolithic document (~400 lines) that could benefit from splitting into separate files (e.g., QUERIES.md, AGGREGATIONS.md, SECURITY.md) with the main file serving as an overview.	2 / 3
	Total	9 / 12 Passed

Validation

68%

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 — 11 / 16 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
description_trigger_hint	Description may be missing an explicit 'when to use' trigger hint (e.g., 'Use when...')	Warning
metadata_version	'metadata' field is not a dictionary	Warning
license_field	'license' field is missing	Warning
body_steps	No step-by-step structure detected (no ordered list); consider adding a simple workflow	Warning

	Total	11 / 16 Passed

Repository: mindrally/skills
Commit: 47f47c1

Reviewed: about 2 months 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.