Content
65%Weight 40%Scale 1-5Reviews 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.
| Dimension | Reasoning | Score |
|---|---|---|
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 |