CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

railway-troubleshooting

Railway debugging and issue resolution. Use when deployments fail, builds error, services crash, performance degrades, or networking issues occur.

Quality

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./skills/railway-troubleshooting/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

65%Weight 40%Scale 1-5

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

A well-structured overview with concrete CLI commands, real bundle-file references, and clear per-operation routing. The main weaknesses are duplicated boilerplate sections, a hardcoded machine-specific script path, and missing verification steps after the destructive operations (force rebuild, database restart/emergency recovery), the last of which caps workflow clarity at 3.

Suggestions

Add explicit validation steps after destructive/risky actions, e.g., after `force-rebuild.sh` and the Emergency Recovery restarts: re-check `railway status` and health before declaring the issue resolved, and verify data integrity before scaling a database plan.

Remove the redundant sections — "When to Use This Skill" (restates the description), "Quick Diagnostic" (duplicates Operation 2's diagnose.sh usage), and "Additional Resources" (duplicates the per-operation "See:" pointers) — and fix the hardcoded path `/mnt/c/data/github/skrillz/...` to a relative path like `scripts/diagnose.sh`.

Replace the placeholder API pseudocode in Operation 1 with a real, executable GraphQL example or point directly to the specific section of references/debug-workflow.md that contains it.

DimensionReasoningScore

Conciseness

The bulk is efficient actionable steps, but there is real duplication: the opening decision tree repeats the operation routing, the "When to Use This Skill" section restates the frontmatter triggers, "Quick Diagnostic" repeats the diagnose.sh usage already shown in Operation 2, and "Additional Resources" repeats the per-operation "See:" pointers. This matches anchor 3 (mostly efficient but could be tightened) rather than 2, since there is no concept-explanation padding aimed at things Claude already knows.

3 / 5

Actionability

Operations give concrete, mostly executable commands (`railway status`, `railway logs --tail 500`, `railway run psql $DATABASE_URL -c "SELECT 1"`, `./scripts/diagnose.sh [service-id] --verbose`) plus specific fixes keyed to concrete symptoms (exit code 137 = OOM, port must bind `process.env.PORT`). Minor gaps keep it below anchor 5: the API block is placeholder pseudocode ("# Query deployment status and recent deploys"), and the Quick Diagnostic hardcodes a machine-specific absolute path (/mnt/c/data/github/skrillz/...).

4 / 5

Workflow Clarity

Each operation has a clear numbered sequence and Operation 1 includes verify steps ("Monitor deployment logs", "Verify service healthy"), but the risky operations lack validation checkpoints: the force-rebuild workflow ("./scripts/force-rebuild.sh [service-id] --no-cache") and the Emergency Recovery section ("Restart database service", "Scale vertically") proceed with no post-action verification. Per the guideline capping destructive/batch workflows without validation at 3, this cannot score 4 even though the sequencing itself is good.

3 / 5

Progressive Disclosure

The body is a genuine overview: a routing decision tree, five compact operations, and clearly signaled one-level-deep pointers to existing bundle files (references/common-errors.md, references/debug-workflow.md, references/recovery-procedures.md, scripts/diagnose.sh, scripts/force-rebuild.sh) — all verified to exist, with the error catalog and debug methodology correctly split out of SKILL.md. This matches the anchor for a clear overview with well-signaled, one-level-deep references.

5 / 5

Total

15

/

20

Passed

Description

65%Weight 40%Scale 1-5

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 has an explicit and well-phrased trigger clause with natural failure-mode keywords, but the capability statement is a generic abstract ("debugging and issue resolution") rather than a list of concrete actions. Adding the specific diagnostics it performs (build failures, runtime crashes, networking, database issues) would raise both specificity and completeness toward the top anchors.

Suggestions

Replace the generic "Railway debugging and issue resolution" with the concrete actions the skill performs, e.g., "Diagnoses Railway deployment and build failures, debugs runtime crashes and OOM kills, troubleshoots networking and database issues."

Add database-related trigger phrases (e.g., "database connection refused, slow queries, connection pool exhausted") to the 'Use when...' clause, since database troubleshooting is a major operation but is absent from the triggers.

Clarify the boundary with sibling skills (railway-deployment, railway-logs) so deployment-workflow requests don't trigger this troubleshooting skill unnecessarily.

DimensionReasoningScore

Specificity

"Railway debugging and issue resolution" names the domain but the stated actions ("debugging", "issue resolution") are generic abstractions with no concrete capabilities listed. It matches anchor 2 rather than 3+ because the description never enumerates specific actions like diagnosing build failures or resolving database connection issues, which the skill actually performs.

2 / 5

Completeness

Both parts are present: the "what" ("Railway debugging and issue resolution") and an explicit "Use when..." trigger clause covering five scenarios. It is not a 5 because the "what" is vague (no concrete actions enumerated), matching anchor 4 where either half could be more specific.

4 / 5

Trigger Term Quality

"deployments fail, builds error, services crash, performance degrades, or networking issues occur" provides good natural phrases users would say. A few common terms are missing — notably database/connection problems (a whole operation in the skill) and synonyms like "deploy errors" or "restart loop" — so it falls short of comprehensive anchor 5 but above anchor 3's partial coverage.

4 / 5

Distinctiveness Conflict Risk

"Railway" pins a clear platform niche with distinct failure-mode triggers, so conflict risk with generic skills is minimal. However, the body lists closely related skills (railway-deployment, railway-logs) whose territories overlap triggers like "deployments fail" — minor overlap with closely related skills, matching anchor 4.

4 / 5

Total

14

/

20

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

fernandezbaptiste/Skrillz

Path

skills/railway-troubleshooting/SKILL.md

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.