2026 年 6 月下旬，PaaS（Platform as a Service）部署平台 Railway 在官方博客先后发表两篇文章：《State of Railway: Agents》 盘点 agent 使用现状，《Skill Issue》 则完整复盘了他们编写官方 Agent Skills 的过程。简单说，他们把部署排障经验写成了 agent 可执行的操作手册，让"AI 帮我部署"从开盲盒变成走流水线。本文按"翻车背景 → 技能演进 → 结构拆解 → 安装方式 → 设计原则 → 借鉴"组织全文。
1、Agent 部署的翻车现场
先看一组 Railway 支持工单里的原话：
"Why did Claude send my replica to Tahiti?" "Why did Cursor say Railway storage was 2 cents?" "Why did my agent delete my whole project!?!"
数据库副本被建到塔希提、存储报价 2 美分、整个项目被误删——这些是 agent 直接上手生产环境后的真实求助。
Railway 的诊断很直接：agent 缺的不是工具，而是教育。平台早已提供 CLI、API 和 MCP（Model Context Protocol）服务器，但 agent 缺少平台心智模型，只能装上 CLI 猜命令行参数。他们的 MCP 服务器约有 30 个工具，但用户不知道它存在，而且"你得明确告诉 agent 去调用它们"。
规模放大了痛感。《State of Railway: Agents》给出数字：每周有数以万计的用户完全通过 agent 操作管理 Railway，MCP 驱动的 agent 活跃用量一个月内涨了 5 倍以上。agent 用得越多，翻车工单越多，技能因此立项。
2、十二个技能的教训
第一版方案把平台能力拆成十二个技能：railway-docs、service、deployment、deploy、database、projects、environment、metrics、domain、status、new、central-station。设计假设是 agent 会按需加载、用完卸载。
结果很快被打脸，原话是"agents turned out to be pretty bad at that"——agent 根本不擅长自主决定何时加载哪个技能，拆得越细，路由越乱。
第二版收敛成一个大技能 use-railway，所有场景入口收进一份 SKILL.md。这个少即是多的转折最有工程味：砍掉十一个技能后，agent 表现反而更稳定。
3、use-railway 的内部结构
第二版技能的目录结构如下（综合博文与开源仓库）：
use-railway/
├── SKILL.md # 路由入口：判定意图、声明工具边界
├── references/ # 按场景拆分的操作手册
│ ├── setup.md # 初始化与登录
│ ├── deploy.md # 部署类请求读这份
│ ├── operate.md # 排障调试读这份
│ ├── configure.md # 配置变更读这份
│ ├── analyze-db.md # 数据库体检总入口
│ └── analyze-db-postgres.md # 另有 mysql/mongo/redis 三份
└── scripts/ # 结构化分析脚本
├── analyze-postgres.py # 同样覆盖四种数据库
├── dal.py # 数据访问层
├── enable-pg-stats.py # 打开 Postgres 统计开关
├── pg-extensions.py # 列出 Postgres 扩展
└── railway-api.sh # GraphQL API 包装
设计核心是让 SKILL.md 当路由器：定义何时该用 Railway、允许调用哪些工具、平台资源模型是什么，再把意图分发到对应参考文件。官方原话是"SKILL.md is the router"。
路由关系大致如下：
| 用户意图 | 加载的文件 |
|---|---|
| 部署一个新服务 | references/deploy.md |
| 服务挂了要排查 | references/operate.md |
| 改环境变量或配置 | references/configure.md |
| 数据库健康体检 | references/analyze-db.md |
这样拆避免了"一份巨型指令块"：每次请求通常只加载一两个参考文件，上下文占用小，指令互不干扰。脚本层兜底结构化任务——数据库分析这类精确输出交给 Python，概念性指导留给 Markdown。
4、安装与自动更新
安装走两条路。第一条是官方一键脚本，同时装好 CLI、技能和 MCP 配置：
# 一键安装 CLI、技能与 MCP 配置
curl -fsSL agents.railway.com | sh
# 已有 CLI 时补装技能，可指定目标 agent
railway skills install --agent claude-code
--agent 参数支持 claude-code、codex、cursor、opencode、copilot、factory-droid 等目标，技能会同时落到 ~/.agents/skills 通用目录和各工具自己的技能目录。第二条路是各 agent 的插件市场，命令如下：
Claude Code 里执行：/plugin install railway@claude-plugins-official
Cursor 里执行：/add-plugin railway
插件包捆绑 use-railway 技能和 Railway 托管 MCP 服务器的配置。运维细节值得抄：CLI 自带健康检查，技能缺失、过期或不匹配时会主动提示并告诉 agent 怎么修，新版 CLI 还会后台自动更新技能。更多细节见官方的 Agent Skills 文档。
5、设计原则与取舍
博文里总结了几条原则，条条像踩过坑才写得出来：
- 技能宜少不宜多，一个大路由技能胜过一堆小技能
- 路由优于堆料，一个意图只分发到一份参考文件
- 该写代码就写代码，结构化分析交给脚本
- 内部要求"一切皆技能，装不进技能的进 MCP"
- 指令要经得起"凌晨三点测试"：高压之下也能照做
最扎心的结论是这一句：
"The thing that makes a model good at your product is not a better model. It's a document." （让模型用好你的产品的，不是更好的模型，而是一份文档。）
配上"Text is the universal interface"（文本是通用接口），价值观就齐了：竞争点从"接入更强的模型"转向"把领域知识写成机器可读的文本"。
6、写给平台方的启示
这件事对做平台、做内部工具的团队都有直接参考价值。
第一，排障经验是资产，写成结构化文本才能被 agent 复用。Railway 把"部署看什么日志、数据库怎么体检"沉淀进 references 目录，本质是面向 agent 的知识工程。文中的比喻很准：CLI 是工具面，agent skills 才是操作手册。
第二，别高估 agent 的自主调度能力。十二技能的失败说明，路由决策交给模型不如写进文档。做团队 agent 工作流时，同样先保证"入口唯一、分发明确"。
第三，文档与脚本要分层。概念性指导用 Markdown，精确操作用代码，分界线就是"需不需要结构化输出"。
想上手的读者可以直接读 Skill Issue 原文，再翻 railway-skills 开源仓库。仓库遵循 Agent Skills 开放格式，MIT 协议，完全可以当模板抄。
7、总结
Railway 的 Agent Skills 不是炫技的 AI 功能，而是一次务实的知识沉淀：把 PaaS 多年积累的部署与排障经验，写成 agent 可复用的工作流。从十二个技能收敛到一个 use-railway，用 SKILL.md 做路由、references 做手册、scripts 做工具，再配合 CLI 的健康检查与自动更新，整套方案朴素但完整。
对于正在做平台或内部工具的团队，建议先把自己领域的高频翻车点列出来，挑最痛的三个写成一份路由式技能文档，跑通之后再扩展。模型会一直换，但那份写清楚的平台说明书会一直增值。
