elasticsearch-esql
Use this skill when writing or debugging ES|QL queries for Elasticsearch. Activate when the user asks to query logs, metrics, traces, or any Elasticsearch data using ES|QL syntax.
88
84%
Does it follow best practices?
Impact
94%
1.20xAverage score across 3 eval scenarios
Passed
No known issues
Quality
Discovery
89%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 is strong in completeness and distinctiveness, clearly specifying both when to activate and targeting a niche domain (ES|QL). However, it uses second-person voice ('Use this skill when...', 'Activate when the user asks') rather than third-person, and could benefit from listing more specific concrete actions beyond 'writing or debugging'. The trigger terms are well-chosen and cover natural user language.
Suggestions
Rewrite in third-person voice (e.g., 'Writes and debugs ES|QL queries for Elasticsearch') instead of imperative/second-person ('Use this skill when...').
Add more specific concrete actions such as 'construct aggregations, parse pipe-delimited syntax, optimize query performance, troubleshoot syntax errors' to improve specificity.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (ES|QL queries for Elasticsearch) and mentions 'writing or debugging' as actions, but does not list multiple specific concrete actions like parsing syntax, optimizing queries, explaining commands, etc. | 2 / 3 |
Completeness | Explicitly answers both 'what' (writing or debugging ES|QL queries for Elasticsearch) and 'when' ('Activate when the user asks to query logs, metrics, traces, or any Elasticsearch data using ES|QL syntax'). | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would say: 'ES|QL', 'Elasticsearch', 'query logs', 'metrics', 'traces', 'ES|QL syntax'. These cover the key variations a user would naturally mention. | 3 / 3 |
Distinctiveness Conflict Risk | ES|QL is a very specific query language for Elasticsearch, making this clearly distinguishable from general SQL skills, other query language skills, or generic Elasticsearch skills. The 'ES|QL' trigger is highly distinctive. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
79%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a solid ES|QL reference skill that provides concise, actionable query patterns and function references. Its main weakness is the lack of debugging/error-handling guidance despite the skill description explicitly mentioning debugging, and the absence of any validation or feedback loop for query authoring. The content is well-structured within a single file but could benefit from progressive disclosure for advanced topics.
Suggestions
Add a 'Debugging' section with common ES|QL error messages and how to fix them (e.g., type mismatches, unknown fields, syntax errors), since the skill description explicitly covers debugging.
Include a brief workflow for iterative query development: start with FROM + LIMIT to verify data exists, then incrementally add WHERE/STATS/SORT clauses.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient. It doesn't explain what Elasticsearch is or what ES|QL stands for beyond a single sentence. Every section provides direct, usable information without padding. The tips section is terse bullet points, and function references are compact lists. | 3 / 3 |
Actionability | Provides fully executable ES|QL queries covering common patterns (time filtering, aggregation, percentiles, time bucketing, multi-field filtering). The CLI command for running queries is copy-paste ready. Function references are concrete with clear syntax. | 3 / 3 |
Workflow Clarity | The skill is primarily a reference/pattern guide rather than a multi-step workflow, so explicit sequencing is less critical. However, there's no guidance on debugging failed queries, validating results, or handling common errors—which would be expected given the skill description mentions 'debugging ES|QL queries.' | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear sections (Basics, Common Patterns, Functions, Tips), but everything is in a single file with no references to supporting materials. For a skill of this size (~80 lines of content), some separation of the function reference or advanced patterns into a separate file would improve navigation. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
100%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 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- elastic/elastic-ramen
- Commit
2e200ec
- Reviewed
Table of Contents
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.