gateway-diagnose
Diagnose gateway failures by reading daemon logs, session transcripts, Redis state, and OTEL telemetry. Full Telegram path triage: daemon process → Redis channel → command queue → pi session → model API → Telegram delivery. Use when: 'gateway broken', 'telegram not working', 'why is gateway down', 'gateway not responding', 'check gateway logs', 'what happened to gateway', 'gateway diagnose', 'gateway errors', 'review gateway logs', 'fallback activated', 'gateway stuck', or any request to understand why the gateway failed. Distinct from the gateway skill (operations) — this skill is diagnostic.
90
88%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is an excellent skill description that hits all the marks. It provides highly specific capabilities (reading daemon logs, Redis state, OTEL telemetry), includes a comprehensive set of natural trigger terms, explicitly separates 'what' from 'when', and proactively distinguishes itself from a related gateway operations skill. The description is thorough without being padded, and uses proper third-person voice throughout.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: reading daemon logs, session transcripts, Redis state, OTEL telemetry, and describes the full triage path (daemon process → Redis channel → command queue → pi session → model API → Telegram delivery). | 3 / 3 |
Completeness | Clearly answers both 'what' (diagnose gateway failures by reading logs, Redis state, telemetry, full Telegram path triage) and 'when' (explicit 'Use when:' clause with extensive trigger phrases). Also distinguishes itself from a related skill. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms users would say: 'gateway broken', 'telegram not working', 'why is gateway down', 'gateway not responding', 'check gateway logs', 'fallback activated', 'gateway stuck', etc. These are realistic phrases a user would type. | 3 / 3 |
Distinctiveness Conflict Risk | Explicitly distinguishes itself from the gateway operations skill by stating 'Distinct from the gateway skill (operations) — this skill is diagnostic.' The specific diagnostic focus and Telegram path triage create a clear niche. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a highly actionable and well-structured diagnostic skill with excellent workflow clarity — the layered approach with concrete commands and error pattern tables is exemplary. Its main weakness is length: at 400+ lines, it packs detailed failure scenarios, architecture references, and interpretation guidance that could be progressively disclosed via separate files. The content is accurate and useful but could be more token-efficient by moving reference material out of the main body.
Suggestions
Move 'Known Failure Scenarios' (sections 0-7) into a separate FAILURE-SCENARIOS.md file, keeping only a summary table with one-line descriptions and links in the main skill.
Move 'Fallback Controller State', 'Architecture Reference', and 'Key Code' sections into a GATEWAY-INTERNALS.md reference file to reduce the main diagnostic workflow to its essential layers.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is very long and detailed, which is appropriate for a complex diagnostic workflow, but includes some verbose interpretation guidance (e.g., lengthy explanations of what channel-health/operator-tracing/interruptibility mean in Layer 1) and known failure scenarios that could be more tightly written. Some sections like 2b and 2c feel like they document edge cases that could be in a separate reference file. | 2 / 3 |
Actionability | Excellent actionability throughout — every diagnostic layer has concrete, copy-paste-ready bash commands, specific log patterns to grep for, and clear expected vs failure outputs. The error pattern tables with meaning and root cause are immediately usable. | 3 / 3 |
Workflow Clarity | The diagnostic procedure is clearly sequenced as numbered layers (Layer -1 through Layer 8) with explicit 'stop at first failure' instruction. Each layer has validation criteria, failure patterns, and fix paths. The 'Known Failure Scenarios' section provides detailed error recovery loops. | 3 / 3 |
Progressive Disclosure | The skill correctly references related skills (gateway, joelclaw-system-check, k8s) and ADRs, but the body itself is monolithic at ~400+ lines. The 8 known failure scenarios, fallback controller state, and architecture reference could be split into separate reference files to keep the main diagnostic workflow lean. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
90%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 |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- joelhooks/joelclaw
- Commit
825972c
- 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.