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

70%

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 ./.claude/skills/railway-troubleshooting/SKILL.md

The canonical home for this skill is railway-troubleshooting in fernandezbaptiste/Skrillz

SKILL.md
Quality
Evals
Security

Quality

Content

61%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 troubleshooting guide with a strong decision tree and concrete CLI commands for all five failure domains, backed by real bundle files. The main weaknesses are redundant trailing sections, inconsistent validation steps for risky recovery operations, and a hardcoded local path that breaks portability.

Suggestions

Add explicit verification checkpoints to every operation and the Emergency Recovery list (e.g. 'after restart, confirm health check passes and logs show no crash before declaring resolved'), which would lift the workflow-clarity cap.

Remove the duplicated 'Quick Diagnostic' and 'Additional Resources' sections (keep one navigation block) and cut 'When to Use This Skill', which restates the frontmatter description and the decision tree.

Replace the machine-specific absolute path '/mnt/c/data/github/skrillz/.claude/skills/railway-troubleshooting/scripts' with a relative path ('./scripts/diagnose.sh') so the instructions work on any machine.

DimensionReasoningScore

Conciseness

The decision tree and operation workflows are dense and free of concept explanations Claude already knows, but three sections are redundant: 'Quick Diagnostic' repeats the diagnose.sh usage from Operation 2, 'Additional Resources' repeats the per-operation See pointers, and 'When to Use This Skill' restates the description and decision tree. Mostly efficient but with several trimmable sections, matching anchor 3 rather than the minor-trim anchor 4.

3 / 5

Actionability

Mostly executable commands with placeholders that are copy-paste ready after substitution ('railway logs --tail 500', 'railway run psql $DATABASE_URL -c "SELECT 1"', './scripts/diagnose.sh [service-id] --verbose', 'railway restart [service-id]'). Minor gaps keep it below anchor 5: the GraphQL block is comment-only ('# Query deployment status and recent deploys') and 'railway metrics' is asserted without example usage.

4 / 5

Workflow Clarity

The decision tree routes symptoms to operations and each operation has a numbered sequence with a 'When to use' precondition; Operation 1 ends with 'Verify service healthy'. However, validation is inconsistent across operations, and the Emergency Recovery steps (restart, rollback, force rebuild with --no-cache) plus database recovery lack explicit verify-after-recovery checkpoints. Per the rubric, destructive/batch workflows without validation are capped at 3.

3 / 5

Progressive Disclosure

The body is an overview with one-level-deep references that all exist in the bundle (common-errors.md, debug-workflow.md, recovery-procedures.md, diagnose.sh, force-rebuild.sh), each signposted per-operation. Not 5 because the Quick Diagnostic section hardcodes a machine-specific absolute path (/mnt/c/data/github/skrillz/...) instead of a relative path, and the 'Additional Resources' section duplicates the in-body See pointers rather than serving as a single navigation point.

4 / 5

Total

14

/

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 covering the main failure scenarios, but the capability half is generic ('debugging and issue resolution') without concrete actions. It is clearly scoped to the Railway platform, keeping conflict risk low.

Suggestions

Replace the generic 'Railway debugging and issue resolution' with concrete actions, e.g. 'Diagnose build and deploy failures, debug runtime crashes and OOM kills, resolve networking and database issues on Railway.com.'

Add missing natural trigger terms users would say: 'restart loop', 'exit code 137', 'logs', 'service down', 'database connection refused', 'SSL errors'.

Mention the deliverables that distinguish this from adjacent railway-* skills (decision tree, diagnostic script, error catalogue) to further reduce overlap risk.

DimensionReasoningScore

Specificity

"Railway debugging and issue resolution" names the domain but the actions are entirely generic; no concrete actions are listed (unlike 'diagnose build failures, debug crashes, resolve database issues'). Matches the anchor 'Names the domain but actions are minimal or generic' rather than anchor 3, which requires 1-2 concrete actions.

2 / 5

Completeness

Both 'what' ("Railway debugging and issue resolution") and an explicit 'when' ("Use when deployments fail, builds error, services crash...") with concrete trigger phrases are present. Not 5 because the 'what' half is generic and lacks concrete action verbs; not 3 because the when-clause is explicit and specific.

4 / 5

Trigger Term Quality

"deployments fail, builds error, services crash, performance degrades, networking issues occur" are natural phrases users would say and cover the main trigger categories. Not 5 because common variations like 'logs', 'restart loop', 'database errors', 'downtime', and 'SSL' are missing.

4 / 5

Distinctiveness Conflict Risk

Railway is a specific platform niche with distinct deployment/build/networking triggers, so broad conflict risk is low. Minor overlap remains with closely related skills like railway-deployment and railway-logs referenced in the body, matching anchor 4 rather than the minimal-conflict anchor 5.

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

.claude/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.