[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6DRZ7ZSYHED4ECEV6CDZAMX":3,"skill-same:01M6DRZ7ZSYHED4ECEV6CDZAMX":96},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":28,"linkOnly":29,"markdownContent":30,"markdownBody":31,"frontMatter":32,"refName":33,"commitSha":34,"skillDirectory":35,"forksCount":36,"repositoryHtmlUrl":37,"repositoryHomepageUrl":6,"ownerHtmlUrl":38,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":39,"install":40,"resources":53},"01M6DRZ7ZSYHED4ECEV6CDZAMX","promql-validator",null,"Validate, lint, audit, or fix PromQL queries and alerting rules; detects anti-patterns.","AntifragileTech\u002Fantifragile-claude-code","AntifragileTech","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F174357194?v=4","01M6DQCYMK4CDSQQAN0ZC72NTV","01M6DQCYS9YPW1WKMQ5TJMPQ43",9,"MIT","https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fdevops\u002Fpromql-validator\u002FSKILL.md",[],[18,19,20,21,22,23,24,25,26,27],"promql validator","validate","lint","audit","alerting","Rules","fix","anti-patterns","queries","patterns","2026-11-10 10:12:30",false,"---\nname: promql-validator\ndescription: Validate, lint, audit, or fix PromQL queries and alerting rules; detects anti-patterns.\n---\n\n## How This Skill Works\n\nThis skill performs multi-level validation and provides interactive query planning:\n\n1. **Syntax Validation**: Checks for syntactically correct PromQL expressions\n2. **Semantic Validation**: Ensures queries make logical sense (e.g., rate() on counters, not gauges)\n3. **Anti-Pattern Detection**: Identifies common mistakes and inefficient patterns\n4. **Optimization Suggestions**: Recommends performance improvements\n5. **Query Explanation**: Translates PromQL to plain English\n6. **Interactive Planning**: Helps users clarify intent and refine queries\n\n## Workflow\n\nWhen a user provides a PromQL query, follow this workflow:\n\n### Working Directory Requirement\n\nRun validation commands from the repository root so relative paths resolve correctly:\n\n```bash\ncd \"$(git rev-parse --show-toplevel)\"\n```\n\nIf running from another location, use absolute paths to `scripts\u002F` files.\n\n### Step 1: Validate Syntax\n\nRun the syntax validation script to check for basic correctness:\n\n```bash\npython3 devops-skills-plugin\u002Fskills\u002Fpromql-validator\u002Fscripts\u002Fvalidate_syntax.py \"\u003Cquery>\"\n```\n\nOutput parsing notes:\n- Exit `0`: syntax valid\n- Exit non-zero: syntax failure; include stderr and pinpoint token\u002Fposition\n- Prefer quoting the smallest failing fragment, then provide corrected query\n\nThe script will check for:\n- Valid metric names and label matchers\n- Correct operator usage\n- Proper function syntax\n- Valid time durations and ranges\n- Balanced brackets and quotes\n- Correct use of modifiers (offset, @)\n\n### Step 2: Check Best Practices\n\nRun the best practices checker to detect anti-patterns and optimization opportunities:\n\n```bash\npython3 devops-skills-plugin\u002Fskills\u002Fpromql-validator\u002Fscripts\u002Fcheck_best_practices.py \"\u003Cquery>\"\n```\n\nOutput parsing notes:\n- Treat script sections as independent findings (cardinality, metric-type misuse, regex misuse, etc.)\n- If script output is empty but query is complex, add a manual sanity pass and mark it as `manual-review`\n- Preserve script wording for finding labels, then add remediation in plain English\n\nThe script will identify:\n- High cardinality queries without label filters\n- Inefficient regex matchers that could be exact matches\n- Missing rate()\u002Fincrease() on counter metrics\n- rate() used on gauge metrics\n- Averaging pre-calculated quantiles\n- Subqueries with excessive time ranges\n- irate() over long time ranges\n- Opportunities to add more specific label filters\n- Complex queries that should use recording rules\n\n### Step 3: Explain the Query\n\nParse and explain what the query does in plain English:\n- What metrics are being queried\n- What type of metrics they are (counter, gauge, histogram, summary)\n- What functions are applied and why\n- What the query calculates\n- What labels will be in the output\n- What the expected result structure looks like\n\n**Required Output Details** (always include these explicitly):\n\n```\n**Output Labels**: [list labels that will be in the result, or \"None (fully aggregated to scalar)\"]\n**Expected Result Structure**: [instant vector \u002F range vector \u002F scalar] with [N series \u002F single value]\n```\n\nExample:\n```\n**Output Labels**: job, instance\n**Expected Result Structure**: Instant vector with one series per job\u002Finstance combination\n```\n\n### Line-Number Citation Method (Required)\n\nWhen citing examples\u002Fdocs in recommendations, include file path + 1-based line numbers:\n\n```text\nexamples\u002Fgood_queries.promql:42\ndocs\u002Fbest_practices.md:88\n```\n\nRules:\n- Cite the most relevant single line (or start line if multi-line snippet)\n- Keep citations tight; do not cite full files\n- If line numbers are unavailable, state `line number unavailable` and provide file path\n\n### Step 4: Interactive Query Planning (Phase 1 - STOP AND WAIT)\n\nAsk the user clarifying questions to verify the query matches their intent:\n\n1. **Understand the Goal**: \"What are you trying to monitor or measure?\"\n   - Request rate, error rate, latency, resource usage, etc.\n\n2. **Verify Metric Type**: \"Is this a counter (always increasing), gauge (can go up\u002Fdown), histogram, or summary?\"\n   - This affects which functions to use\n\n3. **Clarify Time Range**: \"What time window do you need?\"\n   - Instant value, rate over time, historical analysis\n\n4. **Confirm Aggregation**: \"Do you need to aggregate data across labels? If so, which labels?\"\n   - by (job), by (instance), without (pod), etc.\n\n5. **Check Output Intent**: \"Are you using this for alerting, dashboarding, or ad-hoc analysis?\"\n   - Affects optimization priorities\n\n> **IMPORTANT: Two-Phase Dialogue**\n>\n> After presenting Steps 1-4 results (Syntax, Best Practices, Query Explanation, and Intent Questions):\n>\n> **⏸️ STOP HERE AND WAIT FOR USER RESPONSE**\n>\n> Do NOT proceed to Steps 5-7 until the user answers the clarifying questions.\n> This ensures the subsequent recommendations are tailored to the user's actual intent.\n\n### Step 5: Compare Intent vs Implementation (Phase 2 - After User Response)\n\n**Only proceed to this step after the user has answered the clarifying questions from Step 4.**\n\nAfter understanding the user's intent:\n- Explain what the current query actually does\n- Highlight any mismatches between intent and implementation\n- Suggest corrections if the query doesn't match the goal\n- Offer alternative approaches if applicable\n\nWhen relevant, mention known limitations:\n- Note when metric type detection is heuristic-based (e.g., \"The script inferred this is a gauge based on the `_bytes` suffix. Please confirm if this is correct.\")\n- Acknowledge when high-cardinality warnings might be false positives (e.g., \"This warning may not apply if you're using a recording rule or know your cardinality is low.\")\n\n### Step 6: Offer Optimizations\n\nBased on validation results:\n- Suggest more efficient query patterns\n- Recommend recording rules for complex\u002Frepeated queries\n- Propose better label matchers to reduce cardinality\n- Advise on appropriate time ranges\n\n**Reference Examples**: When suggesting corrections, cite relevant examples using this format:\n\n```\nAs shown in `examples\u002Fbad_queries.promql` (lines 91-97):\n❌ BAD: `avg(http_request_duration_seconds{quantile=\"0.95\"})`\n✅ GOOD: Use histogram_quantile() with histogram buckets\n```\n\nCitation sources:\n- `examples\u002Fgood_queries.promql` - for well-formed patterns\n- `examples\u002Foptimization_examples.promql` - for before\u002Fafter comparisons\n- `examples\u002Fbad_queries.promql` - for showing what to avoid\n- `docs\u002Fbest_practices.md` - for detailed explanations\n- `docs\u002Fanti_patterns.md` - for anti-pattern deep dives\n\n**Citation Format**: `file_path (lines X-Y)` with the relevant code snippet quoted\n\n### Step 7: Let User Plan\u002FRefine\n\nGive the user control:\n- Ask if they want to modify the query\n- Offer to help rewrite it for better performance\n- Provide multiple alternatives if applicable\n- Explain trade-offs between different approaches\n\n## Key Validation Rules\n\n### Syntax Rules\n\n1. **Metric Names**: Must match `[a-zA-Z_:][a-zA-Z0-9_:]*` or use UTF-8 quoting syntax (Prometheus 3.0+):\n   - Quoted form: `{\"my.metric.with.dots\"}`\n   - Using __name__ label: `{__name__=\"my.metric.with.dots\"}`\n2. **Label Matchers**: `=` (equal), `!=` (not equal), `=~` (regex match), `!~` (regex not match)\n3. **Time Durations**: `[0-9]+(ms|s|m|h|d|w|y)` - e.g., `5m`, `1h`, `7d`\n4. **Range Vectors**: `metric_name[duration]` - e.g., `http_requests_total[5m]`\n5. **Offset Modifier**: `offset \u003Cduration>` - e.g., `metric_name offset 5m`\n6. **@ Modifier**: `@ \u003Ctimestamp>` or `@ start()` \u002F `@ end()`\n\n### Semantic Rules\n\n1. **rate() and irate()**: Should only be used with counter metrics (metrics ending in `_total`, `_count`, `_sum`, or `_bucket`)\n2. **Counters**: Should typically use `rate()` or `increase()`, not raw values\n3. **Gauges**: Should not use `rate()` or `increase()`\n4. **Histograms**: Use `histogram_quantile()` with `le` label and `rate()` on `_bucket` metrics\n5. **Summaries**: Don't average quantiles; calculate from `_sum` and `_count`\n6. **Aggregations**: Use `by()` or `without()` to control output labels\n\n### Performance Rules\n\n1. **Cardinality**: Always use specific label matchers to reduce series count\n2. **Regex**: Use `=` instead of `=~` when possible for exact matches\n3. **Rate Range**: Should be at least 4x the scrape interval (typically `[2m]` minimum)\n4. **irate()**: Best for short ranges (\u003C5m); use `rate()` for longer periods\n5. **Subqueries**: Avoid excessive time ranges that process millions of samples\n6. **Recording Rules**: Use for complex queries accessed frequently\n\n## Anti-Patterns to Detect\n\n### High Cardinality Issues\n\n❌ **Bad**: `http_requests_total{}`\n- Matches all time series without filtering\n\n✅ **Good**: `http_requests_total{job=\"api\", instance=\"prod-1\"}`\n- Specific label filters reduce cardinality\n\n### Regex Overuse\n\n❌ **Bad**: `http_requests_total{status=~\"2..\"}`\n- Regex is slower and less precise\n\n✅ **Good**: `http_requests_total{status=\"200\"}`\n- Exact match is faster\n\n### Missing rate() on Counters\n\n❌ **Bad**: `http_requests_total`\n- Counter raw values are not useful (always increasing)\n\n✅ **Good**: `rate(http_requests_total[5m])`\n- Rate shows requests per second\n\n### rate() on Gauges\n\n❌ **Bad**: `rate(memory_usage_bytes[5m])`\n- Gauges measure current state, not cumulative values\n\n✅ **Good**: `memory_usage_bytes`\n- Use gauge value directly or with `avg_over_time()`\n\n### Averaging Quantiles\n\n❌ **Bad**: `avg(http_request_duration_seconds{quantile=\"0.95\"})`\n- Mathematically invalid to average pre-calculated quantiles\n\n✅ **Good**: `histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket[5m])))`\n- Calculate quantile from histogram buckets\n\n### Excessive Subquery Ranges\n\n❌ **Bad**: `rate(metric[5m])[90d:1m]`\n- Processes millions of samples, very slow\n\n✅ **Good**: Use recording rules or limit range to necessary duration\n\n### irate() Over Long Ranges\n\n❌ **Bad**: `irate(metric[1h])`\n- irate() only looks at last two samples, range is wasted\n\n✅ **Good**: `rate(metric[1h])` or `irate(metric[5m])`\n- Use rate() for longer ranges or reduce irate() range\n\n### Mixed Metric Types\n\n❌ **Bad**: `avg(http_request_duration_seconds{quantile=\"0.95\"}) \u002F rate(node_memory_usage_bytes[1h]) + sum(http_requests_total)`\n- Combines summary quantiles, gauge metrics, and counters in arithmetic\n- Produces meaningless results\n\n✅ **Good**: Keep each metric type in separate, purpose-specific queries:\n- Latency: `histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket[5m])))`\n- Memory: `node_memory_usage_bytes{instance=\"prod-1\"}`\n- Request rate: `rate(http_requests_total{job=\"api\"}[5m])`\n\n## Output Format\n\nProvide validation results in this structure:\n\n```\n## PromQL Validation Results\n\n### Syntax Check\n- Status: ✅ VALID \u002F ⚠️ WARNING \u002F ❌ ERROR\n- Issues: [list any syntax errors with line\u002Fposition]\n\n### Semantic Check\n- Status: ✅ VALID \u002F ⚠️ WARNING \u002F ❌ ERROR\n- Issues: [list any logical problems]\n\n### Performance Analysis\n- Status: ✅ OPTIMIZED \u002F ⚠️ CAN BE IMPROVED \u002F ❌ INEFFICIENT\n- Issues: [list optimization opportunities]\n- Suggestions: [specific improvements]\n\n### Query Explanation\nYour query: `\u003Cquery>`\n\nThis query does:\n- [Plain English explanation]\n- Metrics: [list metrics and their types]\n- Functions: [explain each function]\n- Output: [describe result structure]\n\n### Intent Verification\nLet me verify this matches your needs:\n\n1. What are you trying to measure? [your goal here]\n2. Is this a counter\u002Fgauge\u002Fhistogram\u002Fsummary? [metric type]\n3. What time range interests you? [time window]\n4. Do you need aggregation? If so, by which labels? [aggregation needs]\n5. Is this for alerting, dashboarding, or analysis? [use case]\n\n### Recommendations\n[Based on the analysis, suggest improvements or alternatives]\n```\n\n## Interactive Dialogue\n\nAfter validation, engage in dialogue:\n\n**Claude**: \"I've validated your query. It's syntactically correct, but I notice it queries `http_requests_total` without any label filters. This could match thousands of time series. What specific service or endpoint are you trying to monitor?\"\n\n**User**: [provides intent]\n\n**Claude**: \"Great! Based on that, here's an optimized version: `rate(http_requests_total{job=\"api-service\", path=\"\u002Fusers\"}[5m])`. This calculates the per-second rate of requests to the \u002Fusers endpoint over the last 5 minutes. Does this match what you need?\"\n\n**User**: [confirms or asks for changes]\n\n**Claude**: [provides refined query or alternatives]\n\n## Examples\n\nSee the `examples\u002F` directory for:\n- `good_queries.promql`: Well-written queries following best practices\n- `bad_queries.promql`: Common mistakes and anti-patterns (with corrections)\n- `optimization_examples.promql`: Before\u002Fafter optimization examples\n\n## Documentation\n\nSee the `docs\u002F` directory for:\n- `best_practices.md`: Comprehensive PromQL best practices guide\n- `anti_patterns.md`: Detailed anti-pattern reference with explanations\n\n## Important Notes\n\n1. **Be Interactive**: Always ask clarifying questions to understand user intent\n2. **Be Educational**: Explain WHY something is wrong, not just THAT it's wrong\n3. **Be Helpful**: Offer to rewrite queries, don't just criticize\n4. **Be Context-Aware**: Consider the user's use case (alerting vs dashboarding)\n5. **Be Thorough**: Check all four levels (syntax, semantics, performance, intent)\n6. **Be Practical**: Suggest realistic optimizations, not theoretical perfection\n\n## Integration\n\nThis skill can be used:\n- Standalone for query review\n- During monitoring setup to validate alert rules\n- When troubleshooting slow Prometheus queries\n- As part of code review for recording rules\n- For teaching PromQL to team members\n\n## Validation Tools\n\nThe skill uses two main Python scripts:\n\n1. **validate_syntax.py**: Pure syntax checking using regex patterns\n2. **check_best_practices.py**: Semantic and performance analysis\n\nBoth scripts output JSON for programmatic parsing and human-readable messages for display.\n\n## Success Criteria\n\nA successful validation session should:\n1. Identify all syntax errors\n2. Detect semantic problems\n3. Suggest at least one optimization (if applicable)\n4. Clearly explain what the query does\n5. Verify the query matches user intent\n6. Provide actionable next steps\n\n## Known Limitations\n\nThe validation scripts have some limitations to be aware of:\n\n### Metric Type Detection\n- **Heuristic-based**: Metric types (counter, gauge, histogram, summary) are inferred from naming conventions (e.g., `_total`, `_bytes`)\n- **Custom metrics**: Metrics with non-standard names may not be correctly classified\n- **Recommendation**: When the script can't determine metric type, ask the user to clarify\n\n### High Cardinality Detection\n- **Conservative approach**: The script flags metrics without label selectors, but some use cases legitimately query all series\n- **Recording rules**: Queries using recording rule metrics (e.g., `job:http_requests:rate5m`) are valid without label filters\n- **Recommendation**: Use judgment - if the user knows their cardinality is manageable, the warning can be safely ignored\n\n### Semantic Validation\n- **No runtime context**: The scripts cannot verify if metrics actually exist or if label values are valid\n- **Schema-agnostic**: No knowledge of specific Prometheus deployments or metric schemas\n- **Recommendation**: For production validation, test queries against actual Prometheus instances\n\n### Script Detection Coverage\nThe scripts detect common anti-patterns but cannot catch:\n- Business logic errors (e.g., calculating the wrong KPI)\n- Context-specific optimizations (depends on scrape interval, retention, etc.)\n- Custom function behavior from extensions\n\n## Remember\n\nThe goal is not just to validate queries, but to help users write better PromQL and understand their monitoring data. Always be educational, interactive, and helpful!\n","## How This Skill Works\n\nThis skill performs multi-level validation and provides interactive query planning:\n\n1. **Syntax Validation**: Checks for syntactically correct PromQL expressions\n2. **Semantic Validation**: Ensures queries make logical sense (e.g., rate() on counters, not gauges)\n3. **Anti-Pattern Detection**: Identifies common mistakes and inefficient patterns\n4. **Optimization Suggestions**: Recommends performance improvements\n5. **Query Explanation**: Translates PromQL to plain English\n6. **Interactive Planning**: Helps users clarify intent and refine queries\n\n## Workflow\n\nWhen a user provides a PromQL query, follow this workflow:\n\n### Working Directory Requirement\n\nRun validation commands from the repository root so relative paths resolve correctly:\n\n```bash\ncd \"$(git rev-parse --show-toplevel)\"\n```\n\nIf running from another location, use absolute paths to `scripts\u002F` files.\n\n### Step 1: Validate Syntax\n\nRun the syntax validation script to check for basic correctness:\n\n```bash\npython3 devops-skills-plugin\u002Fskills\u002Fpromql-validator\u002Fscripts\u002Fvalidate_syntax.py \"\u003Cquery>\"\n```\n\nOutput parsing notes:\n- Exit `0`: syntax valid\n- Exit non-zero: syntax failure; include stderr and pinpoint token\u002Fposition\n- Prefer quoting the smallest failing fragment, then provide corrected query\n\nThe script will check for:\n- Valid metric names and label matchers\n- Correct operator usage\n- Proper function syntax\n- Valid time durations and ranges\n- Balanced brackets and quotes\n- Correct use of modifiers (offset, @)\n\n### Step 2: Check Best Practices\n\nRun the best practices checker to detect anti-patterns and optimization opportunities:\n\n```bash\npython3 devops-skills-plugin\u002Fskills\u002Fpromql-validator\u002Fscripts\u002Fcheck_best_practices.py \"\u003Cquery>\"\n```\n\nOutput parsing notes:\n- Treat script sections as independent findings (cardinality, metric-type misuse, regex misuse, etc.)\n- If script output is empty but query is complex, add a manual sanity pass and mark it as `manual-review`\n- Preserve script wording for finding labels, then add remediation in plain English\n\nThe script will identify:\n- High cardinality queries without label filters\n- Inefficient regex matchers that could be exact matches\n- Missing rate()\u002Fincrease() on counter metrics\n- rate() used on gauge metrics\n- Averaging pre-calculated quantiles\n- Subqueries with excessive time ranges\n- irate() over long time ranges\n- Opportunities to add more specific label filters\n- Complex queries that should use recording rules\n\n### Step 3: Explain the Query\n\nParse and explain what the query does in plain English:\n- What metrics are being queried\n- What type of metrics they are (counter, gauge, histogram, summary)\n- What functions are applied and why\n- What the query calculates\n- What labels will be in the output\n- What the expected result structure looks like\n\n**Required Output Details** (always include these explicitly):\n\n```\n**Output Labels**: [list labels that will be in the result, or \"None (fully aggregated to scalar)\"]\n**Expected Result Structure**: [instant vector \u002F range vector \u002F scalar] with [N series \u002F single value]\n```\n\nExample:\n```\n**Output Labels**: job, instance\n**Expected Result Structure**: Instant vector with one series per job\u002Finstance combination\n```\n\n### Line-Number Citation Method (Required)\n\nWhen citing examples\u002Fdocs in recommendations, include file path + 1-based line numbers:\n\n```text\nexamples\u002Fgood_queries.promql:42\ndocs\u002Fbest_practices.md:88\n```\n\nRules:\n- Cite the most relevant single line (or start line if multi-line snippet)\n- Keep citations tight; do not cite full files\n- If line numbers are unavailable, state `line number unavailable` and provide file path\n\n### Step 4: Interactive Query Planning (Phase 1 - STOP AND WAIT)\n\nAsk the user clarifying questions to verify the query matches their intent:\n\n1. **Understand the Goal**: \"What are you trying to monitor or measure?\"\n   - Request rate, error rate, latency, resource usage, etc.\n\n2. **Verify Metric Type**: \"Is this a counter (always increasing), gauge (can go up\u002Fdown), histogram, or summary?\"\n   - This affects which functions to use\n\n3. **Clarify Time Range**: \"What time window do you need?\"\n   - Instant value, rate over time, historical analysis\n\n4. **Confirm Aggregation**: \"Do you need to aggregate data across labels? If so, which labels?\"\n   - by (job), by (instance), without (pod), etc.\n\n5. **Check Output Intent**: \"Are you using this for alerting, dashboarding, or ad-hoc analysis?\"\n   - Affects optimization priorities\n\n> **IMPORTANT: Two-Phase Dialogue**\n>\n> After presenting Steps 1-4 results (Syntax, Best Practices, Query Explanation, and Intent Questions):\n>\n> **⏸️ STOP HERE AND WAIT FOR USER RESPONSE**\n>\n> Do NOT proceed to Steps 5-7 until the user answers the clarifying questions.\n> This ensures the subsequent recommendations are tailored to the user's actual intent.\n\n### Step 5: Compare Intent vs Implementation (Phase 2 - After User Response)\n\n**Only proceed to this step after the user has answered the clarifying questions from Step 4.**\n\nAfter understanding the user's intent:\n- Explain what the current query actually does\n- Highlight any mismatches between intent and implementation\n- Suggest corrections if the query doesn't match the goal\n- Offer alternative approaches if applicable\n\nWhen relevant, mention known limitations:\n- Note when metric type detection is heuristic-based (e.g., \"The script inferred this is a gauge based on the `_bytes` suffix. Please confirm if this is correct.\")\n- Acknowledge when high-cardinality warnings might be false positives (e.g., \"This warning may not apply if you're using a recording rule or know your cardinality is low.\")\n\n### Step 6: Offer Optimizations\n\nBased on validation results:\n- Suggest more efficient query patterns\n- Recommend recording rules for complex\u002Frepeated queries\n- Propose better label matchers to reduce cardinality\n- Advise on appropriate time ranges\n\n**Reference Examples**: When suggesting corrections, cite relevant examples using this format:\n\n```\nAs shown in `examples\u002Fbad_queries.promql` (lines 91-97):\n❌ BAD: `avg(http_request_duration_seconds{quantile=\"0.95\"})`\n✅ GOOD: Use histogram_quantile() with histogram buckets\n```\n\nCitation sources:\n- `examples\u002Fgood_queries.promql` - for well-formed patterns\n- `examples\u002Foptimization_examples.promql` - for before\u002Fafter comparisons\n- `examples\u002Fbad_queries.promql` - for showing what to avoid\n- `docs\u002Fbest_practices.md` - for detailed explanations\n- `docs\u002Fanti_patterns.md` - for anti-pattern deep dives\n\n**Citation Format**: `file_path (lines X-Y)` with the relevant code snippet quoted\n\n### Step 7: Let User Plan\u002FRefine\n\nGive the user control:\n- Ask if they want to modify the query\n- Offer to help rewrite it for better performance\n- Provide multiple alternatives if applicable\n- Explain trade-offs between different approaches\n\n## Key Validation Rules\n\n### Syntax Rules\n\n1. **Metric Names**: Must match `[a-zA-Z_:][a-zA-Z0-9_:]*` or use UTF-8 quoting syntax (Prometheus 3.0+):\n   - Quoted form: `{\"my.metric.with.dots\"}`\n   - Using __name__ label: `{__name__=\"my.metric.with.dots\"}`\n2. **Label Matchers**: `=` (equal), `!=` (not equal), `=~` (regex match), `!~` (regex not match)\n3. **Time Durations**: `[0-9]+(ms|s|m|h|d|w|y)` - e.g., `5m`, `1h`, `7d`\n4. **Range Vectors**: `metric_name[duration]` - e.g., `http_requests_total[5m]`\n5. **Offset Modifier**: `offset \u003Cduration>` - e.g., `metric_name offset 5m`\n6. **@ Modifier**: `@ \u003Ctimestamp>` or `@ start()` \u002F `@ end()`\n\n### Semantic Rules\n\n1. **rate() and irate()**: Should only be used with counter metrics (metrics ending in `_total`, `_count`, `_sum`, or `_bucket`)\n2. **Counters**: Should typically use `rate()` or `increase()`, not raw values\n3. **Gauges**: Should not use `rate()` or `increase()`\n4. **Histograms**: Use `histogram_quantile()` with `le` label and `rate()` on `_bucket` metrics\n5. **Summaries**: Don't average quantiles; calculate from `_sum` and `_count`\n6. **Aggregations**: Use `by()` or `without()` to control output labels\n\n### Performance Rules\n\n1. **Cardinality**: Always use specific label matchers to reduce series count\n2. **Regex**: Use `=` instead of `=~` when possible for exact matches\n3. **Rate Range**: Should be at least 4x the scrape interval (typically `[2m]` minimum)\n4. **irate()**: Best for short ranges (\u003C5m); use `rate()` for longer periods\n5. **Subqueries**: Avoid excessive time ranges that process millions of samples\n6. **Recording Rules**: Use for complex queries accessed frequently\n\n## Anti-Patterns to Detect\n\n### High Cardinality Issues\n\n❌ **Bad**: `http_requests_total{}`\n- Matches all time series without filtering\n\n✅ **Good**: `http_requests_total{job=\"api\", instance=\"prod-1\"}`\n- Specific label filters reduce cardinality\n\n### Regex Overuse\n\n❌ **Bad**: `http_requests_total{status=~\"2..\"}`\n- Regex is slower and less precise\n\n✅ **Good**: `http_requests_total{status=\"200\"}`\n- Exact match is faster\n\n### Missing rate() on Counters\n\n❌ **Bad**: `http_requests_total`\n- Counter raw values are not useful (always increasing)\n\n✅ **Good**: `rate(http_requests_total[5m])`\n- Rate shows requests per second\n\n### rate() on Gauges\n\n❌ **Bad**: `rate(memory_usage_bytes[5m])`\n- Gauges measure current state, not cumulative values\n\n✅ **Good**: `memory_usage_bytes`\n- Use gauge value directly or with `avg_over_time()`\n\n### Averaging Quantiles\n\n❌ **Bad**: `avg(http_request_duration_seconds{quantile=\"0.95\"})`\n- Mathematically invalid to average pre-calculated quantiles\n\n✅ **Good**: `histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket[5m])))`\n- Calculate quantile from histogram buckets\n\n### Excessive Subquery Ranges\n\n❌ **Bad**: `rate(metric[5m])[90d:1m]`\n- Processes millions of samples, very slow\n\n✅ **Good**: Use recording rules or limit range to necessary duration\n\n### irate() Over Long Ranges\n\n❌ **Bad**: `irate(metric[1h])`\n- irate() only looks at last two samples, range is wasted\n\n✅ **Good**: `rate(metric[1h])` or `irate(metric[5m])`\n- Use rate() for longer ranges or reduce irate() range\n\n### Mixed Metric Types\n\n❌ **Bad**: `avg(http_request_duration_seconds{quantile=\"0.95\"}) \u002F rate(node_memory_usage_bytes[1h]) + sum(http_requests_total)`\n- Combines summary quantiles, gauge metrics, and counters in arithmetic\n- Produces meaningless results\n\n✅ **Good**: Keep each metric type in separate, purpose-specific queries:\n- Latency: `histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket[5m])))`\n- Memory: `node_memory_usage_bytes{instance=\"prod-1\"}`\n- Request rate: `rate(http_requests_total{job=\"api\"}[5m])`\n\n## Output Format\n\nProvide validation results in this structure:\n\n```\n## PromQL Validation Results\n\n### Syntax Check\n- Status: ✅ VALID \u002F ⚠️ WARNING \u002F ❌ ERROR\n- Issues: [list any syntax errors with line\u002Fposition]\n\n### Semantic Check\n- Status: ✅ VALID \u002F ⚠️ WARNING \u002F ❌ ERROR\n- Issues: [list any logical problems]\n\n### Performance Analysis\n- Status: ✅ OPTIMIZED \u002F ⚠️ CAN BE IMPROVED \u002F ❌ INEFFICIENT\n- Issues: [list optimization opportunities]\n- Suggestions: [specific improvements]\n\n### Query Explanation\nYour query: `\u003Cquery>`\n\nThis query does:\n- [Plain English explanation]\n- Metrics: [list metrics and their types]\n- Functions: [explain each function]\n- Output: [describe result structure]\n\n### Intent Verification\nLet me verify this matches your needs:\n\n1. What are you trying to measure? [your goal here]\n2. Is this a counter\u002Fgauge\u002Fhistogram\u002Fsummary? [metric type]\n3. What time range interests you? [time window]\n4. Do you need aggregation? If so, by which labels? [aggregation needs]\n5. Is this for alerting, dashboarding, or analysis? [use case]\n\n### Recommendations\n[Based on the analysis, suggest improvements or alternatives]\n```\n\n## Interactive Dialogue\n\nAfter validation, engage in dialogue:\n\n**Claude**: \"I've validated your query. It's syntactically correct, but I notice it queries `http_requests_total` without any label filters. This could match thousands of time series. What specific service or endpoint are you trying to monitor?\"\n\n**User**: [provides intent]\n\n**Claude**: \"Great! Based on that, here's an optimized version: `rate(http_requests_total{job=\"api-service\", path=\"\u002Fusers\"}[5m])`. This calculates the per-second rate of requests to the \u002Fusers endpoint over the last 5 minutes. Does this match what you need?\"\n\n**User**: [confirms or asks for changes]\n\n**Claude**: [provides refined query or alternatives]\n\n## Examples\n\nSee the `examples\u002F` directory for:\n- `good_queries.promql`: Well-written queries following best practices\n- `bad_queries.promql`: Common mistakes and anti-patterns (with corrections)\n- `optimization_examples.promql`: Before\u002Fafter optimization examples\n\n## Documentation\n\nSee the `docs\u002F` directory for:\n- `best_practices.md`: Comprehensive PromQL best practices guide\n- `anti_patterns.md`: Detailed anti-pattern reference with explanations\n\n## Important Notes\n\n1. **Be Interactive**: Always ask clarifying questions to understand user intent\n2. **Be Educational**: Explain WHY something is wrong, not just THAT it's wrong\n3. **Be Helpful**: Offer to rewrite queries, don't just criticize\n4. **Be Context-Aware**: Consider the user's use case (alerting vs dashboarding)\n5. **Be Thorough**: Check all four levels (syntax, semantics, performance, intent)\n6. **Be Practical**: Suggest realistic optimizations, not theoretical perfection\n\n## Integration\n\nThis skill can be used:\n- Standalone for query review\n- During monitoring setup to validate alert rules\n- When troubleshooting slow Prometheus queries\n- As part of code review for recording rules\n- For teaching PromQL to team members\n\n## Validation Tools\n\nThe skill uses two main Python scripts:\n\n1. **validate_syntax.py**: Pure syntax checking using regex patterns\n2. **check_best_practices.py**: Semantic and performance analysis\n\nBoth scripts output JSON for programmatic parsing and human-readable messages for display.\n\n## Success Criteria\n\nA successful validation session should:\n1. Identify all syntax errors\n2. Detect semantic problems\n3. Suggest at least one optimization (if applicable)\n4. Clearly explain what the query does\n5. Verify the query matches user intent\n6. Provide actionable next steps\n\n## Known Limitations\n\nThe validation scripts have some limitations to be aware of:\n\n### Metric Type Detection\n- **Heuristic-based**: Metric types (counter, gauge, histogram, summary) are inferred from naming conventions (e.g., `_total`, `_bytes`)\n- **Custom metrics**: Metrics with non-standard names may not be correctly classified\n- **Recommendation**: When the script can't determine metric type, ask the user to clarify\n\n### High Cardinality Detection\n- **Conservative approach**: The script flags metrics without label selectors, but some use cases legitimately query all series\n- **Recording rules**: Queries using recording rule metrics (e.g., `job:http_requests:rate5m`) are valid without label filters\n- **Recommendation**: Use judgment - if the user knows their cardinality is manageable, the warning can be safely ignored\n\n### Semantic Validation\n- **No runtime context**: The scripts cannot verify if metrics actually exist or if label values are valid\n- **Schema-agnostic**: No knowledge of specific Prometheus deployments or metric schemas\n- **Recommendation**: For production validation, test queries against actual Prometheus instances\n\n### Script Detection Coverage\nThe scripts detect common anti-patterns but cannot catch:\n- Business logic errors (e.g., calculating the wrong KPI)\n- Context-specific optimizations (depends on scrape interval, retention, etc.)\n- Custom function behavior from extensions\n\n## Remember\n\nThe goal is not just to validate queries, but to help users write better PromQL and understand their monitoring data. Always be educational, interactive, and helpful!\n",{"name":5,"description":7},"master","c73386b305dec167db7654e0e6feacb462d4f9dc","assets\u002Fskills\u002Fdevops\u002Fpromql-validator",1,"https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code","https:\u002F\u002Fgithub.com\u002FAntifragileTech","2026-10-02 14:22:14",{"source":8,"skillName":5,"commands":41,"prompt":51,"zipAvailable":52},[42,45,48],{"tool":43,"command":44},"npx","npx skills add AntifragileTech\u002Fantifragile-claude-code --skill promql-validator",{"tool":46,"command":47},"bunx","bunx skills add AntifragileTech\u002Fantifragile-claude-code --skill promql-validator",{"tool":49,"command":50},"pnpm","pnpm dlx skills add AntifragileTech\u002Fantifragile-claude-code --skill promql-validator","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fdevops\u002Fpromql-validator\u002FSKILL.md",true,[54,60,66,70,74,78,82,88,92],{"path":55,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":58,"sourceHtmlUrl":59},".gitignore","OTHER","其他",390,"https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fdevops\u002Fpromql-validator\u002F.gitignore",{"path":61,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":64,"sourceHtmlUrl":65},"docs\u002Fanti_patterns.md","REFERENCE","参考文档",16110,"https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fdevops\u002Fpromql-validator\u002Fdocs\u002Fanti_patterns.md",{"path":67,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":68,"sourceHtmlUrl":69},"docs\u002Fbest_practices.md",17480,"https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fdevops\u002Fpromql-validator\u002Fdocs\u002Fbest_practices.md",{"path":71,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":72,"sourceHtmlUrl":73},"examples\u002Fbad_queries.promql",9465,"https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fdevops\u002Fpromql-validator\u002Fexamples\u002Fbad_queries.promql",{"path":75,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":76,"sourceHtmlUrl":77},"examples\u002Fgood_queries.promql",6869,"https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fdevops\u002Fpromql-validator\u002Fexamples\u002Fgood_queries.promql",{"path":79,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":80,"sourceHtmlUrl":81},"examples\u002Foptimization_examples.promql",12242,"https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fdevops\u002Fpromql-validator\u002Fexamples\u002Foptimization_examples.promql",{"path":83,"resourceType":84,"resourceTypeDesc":85,"sizeBytes":86,"sourceHtmlUrl":87},"scripts\u002Fcheck_best_practices.py","SCRIPT","脚本",49451,"https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fdevops\u002Fpromql-validator\u002Fscripts\u002Fcheck_best_practices.py",{"path":89,"resourceType":84,"resourceTypeDesc":85,"sizeBytes":90,"sourceHtmlUrl":91},"scripts\u002Ftest_validators.py",19215,"https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fdevops\u002Fpromql-validator\u002Fscripts\u002Ftest_validators.py",{"path":93,"resourceType":84,"resourceTypeDesc":85,"sizeBytes":94,"sourceHtmlUrl":95},"scripts\u002Fvalidate_syntax.py",20150,"https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fdevops\u002Fpromql-validator\u002Fscripts\u002Fvalidate_syntax.py",[97,123,138,152,165,178],{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":116,"publishedAt":28},"01M6DT9Q6VYA615SCXR757TZZ7","writing-skills","Use when creating new skills, editing existing skills, or verifying skills work before deployment","https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fthinking\u002Fwriting-skills\u002FSKILL.md",[103,108,111],{"categoryNo":104,"categoryName":105,"taxonomyType":106,"taxonomyTypeDesc":107},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",{"categoryNo":109,"categoryName":110,"taxonomyType":106,"taxonomyTypeDesc":107},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":112,"categoryName":113,"taxonomyType":114,"taxonomyTypeDesc":115},"01JBSEEDCAT000000000000036","内容创作者","PROFESSION","适用职业",[117,118,119,120,121,122],"writing skills","writing","use","editing","work","deployment",{"skillNo":124,"name":125,"nameZh":6,"description":126,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":127,"categories":128,"keywords":131,"publishedAt":28},"01M6DT9GFHDNY90P41WGAE1TV0","writing-plans","Use when you have a spec or requirements for a multi-step task, before touching code","https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fthinking\u002Fwriting-plans\u002FSKILL.md",[129,130],{"categoryNo":109,"categoryName":110,"taxonomyType":106,"taxonomyTypeDesc":107},{"categoryNo":112,"categoryName":113,"taxonomyType":114,"taxonomyTypeDesc":115},[132,133,118,134,135,119,136,137],"plans","writing plans","requirements","task","code","spec",{"skillNo":139,"name":140,"nameZh":6,"description":141,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":142,"categories":143,"keywords":146,"publishedAt":28},"01M6DT9C6PFGD86WS3HY7YE3XG","docs:write-concisely","Apply writing rules to any documentation that humans will read. Makes your writing clearer, stronger, and more professional.","https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fthinking\u002Fwrite-concisely\u002FSKILL.md",[144,145],{"categoryNo":109,"categoryName":110,"taxonomyType":106,"taxonomyTypeDesc":107},{"categoryNo":112,"categoryName":113,"taxonomyType":114,"taxonomyTypeDesc":115},[147,148,149,150,23,151,118],"docs:write concisely","write","docs","read","documentation",{"skillNo":153,"name":154,"nameZh":6,"description":155,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":156,"categories":157,"keywords":158,"publishedAt":28},"01M6DT98AWQ27P0N1CG97WAG66","kaizen:why","Iterative Five Whys root cause analysis drilling from symptoms to fundamentals","https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fthinking\u002Fwhy\u002FSKILL.md",[],[154,159,160,161,162,163,164],"why","kaizen","issue","five whys","analysis","root cause analysis",{"skillNo":166,"name":167,"nameZh":6,"description":168,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":169,"categories":170,"keywords":171,"publishedAt":28},"01M6DT93EH25NAX19R3WGE1P53","verification-loop","A comprehensive verification system for Claude Code sessions.","https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fthinking\u002Fverification-loop\u002FSKILL.md",[],[172,173,174,175,136,176,177],"verification loop","verification","loop","sessions","claude code sessions","system",{"skillNo":179,"name":180,"nameZh":6,"description":181,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":182,"categories":183,"keywords":184,"publishedAt":28},"01M6DT90GW7Z7VCN98P9DVYSNC","verification-before-completion","Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always","https:\u002F\u002Fgithub.com\u002FAntifragileTech\u002Fantifragile-claude-code\u002Fblob\u002Fmaster\u002Fassets\u002Fskills\u002Fthinking\u002Fverification-before-completion\u002FSKILL.md",[],[185,173,186,121,119,187,188,189],"verification before completion","commands","evidence","claim","complete"]