new

Q: How do I install new?

Run npx skills add https://github.com/railwayapp/railway-skills --skill new in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/new/ (personal) or .claude/skills/new/ (project).

by railwayappDevOps & Cloud

This skill should be used when the user says "setup", "deploy to railway", "initialize", "create project", "create service", or wants to deploy from GitHub. Handles initial setup AND adding services to existing projects. For databases, use the database skill instead.

Installs: 786
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/railwayapp/railway-skills --skill new

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads new automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

New Project / Service / Database

Create Railway projects, services, and databases with proper configuration.

When to Use

User says "deploy to railway" (add service if linked, init if not)
User says "create a railway project", "init", "new project" (explicit new project)
User says "link to railway", "connect to railway"
User says "create a service", "add a backend", "new api service"
User says "create a vite app", "create a react website", "make a python api"
User says "deploy from github.com/user/repo", "create service from this repo"
User says "add postgres", "add a database", "add redis", "add mysql", "add mongo"
User says "connect to postgres", "wire up the database", "connect my api to redis"
User says "add postgres and connect to the server"
Setting up code + Railway service together

Prerequisites

Check CLI installed:

command -v railway

If not installed:

Install Railway CLI:
npm install -g @railway/cli
or
brew install railway

Check authenticated:

railway whoami --json

If not authenticated:

Run railway login to authenticate.

Decision Flow

railway status --json (in current dir)
     │
┌────┴────┐
Linked    Not Linked
  │            │
  │       Check parent: cd .. && railway status --json
  │            │
  │       ┌────┴────┐
  │    Parent      Not linked
  │    Linked      anywhere
  │       │            │
  │   Add service   railway list
  │   Set rootDir      │
  │   Deploy       ┌───┴───┐
  │       │      Match?  No match
  │       │        │        │
  │       │      Link    Init new
  └───────┴────────┴────────┘
           │
    User wants service?
           │
     ┌─────┴─────┐
    Yes         No
     │           │
Scaffold code   Done
     │
railway add --service
     │
Configure if needed
     │
Ready to deploy

Check Current State

railway status --json

If linked: Add a service to the existing project (see below)
If not linked: Check if a PARENT directory is linked (see below)

When Already Linked

Default behavior: "deploy to railway" = add a service to the linked project.

Do NOT create a new project unless user EXPLICITLY says:

"new project", "create a project", "init a project"
"separate project", "different project"

App names like "flappy-bird" or "my-api" are SERVICE names, not project names.

User: "create a vite app called foo and deploy to railway"
Project: Already linked to "my-project"

WRONG: railway init -n foo
RIGHT: railway add --service foo

Parent Directory Linking

Railway CLI walks up the directory tree to find a linked project. If you're in a subdirectory:

cd .. && railway status --json

If parent is linked, you don't need to init/link the subdirectory. Instead:

Create service: railway add --service <name>
Set rootDirectory to subdirectory path via environment skill
Deploy from root: railway up

If no parent is linked, proceed with init or link flow.

Init vs Link Decision

Skip this section if already linked - just add a service instead.

Only use this section when NO project is linked (directly or via parent).

Check User's Projects

The output can be large. Run in a subagent and extract only:

Project id and name
Workspace id and name

railway list --json

Decision Logic

User explicitly says "new project" → Use railway init
User names an existing project → Use railway link
Directory name matches existing project → Ask: link existing or create new?
No matching projects → Use railway init
Ambiguous → Ask user

Create New Project

railway init -n <name>

Options:

-n, --name - Project name (auto-generated if omitted in non-interactive mode)
-w, --workspace - Workspace name or ID (required if multiple workspaces exist)

Multiple Workspaces

If the user has multiple workspaces, railway init requires the --workspace flag.

Get workspace IDs from:

railway whoami --json

The workspaces array contains { id, name } for each workspace.

Inferring workspace from user input: If user says "deploy into xxx workspace" or "create project in my-team", match the name against the workspaces array and use the corresponding ID:

# User says: "create a project in my personal workspace"
railway whoami --json | jq '.workspaces[] | select(.name | test("personal"; "i"))'
# Use the matched ID: railway init -n myapp --workspace <matched-id>

Link Existing Project

railway link -p <project>

Options:

-p, --project - Project name or ID
-e, --environment - Environment (default: production)
-s, --service - Service to link
-t, --team - Team/workspace

Create Service

After project is linked, create a service:

railway add --service <name>

For GitHub repo sources: Create an empty service, then invoke the environment skill to configure the source via staged changes API. Do NOT use railway add --repo - it requires GitHub app integration which often fails.

Flow:

railway add --service my-api
Invoke environment skill to set source.repo and source.branch
Apply changes to trigger deployment

Configure Based on Project Type

Reference railpack.md for build configuration. Reference monorepo.md for monorepo patterns.

Static site (Vite, CRA, Astro static):

Railpack auto-detects common output dirs (dist, build)
If non-standard output dir: invoke environment skill to set RAILPACK_STATIC_FILE_ROOT
Do NOT use railway variables CLI - always use the environment skill

Node.js SSR (Next.js, Nuxt, Express):

Verify start script exists in package.json
If custom start needed: invoke environment skill to set startCommand

Python (FastAPI, Django, Flask):

Verify requirements.txt or pyproject.toml exists
Auto-detected by Railpack, usually no config needed

Go:

Verify go.mod exists
Auto-detected, no config needed

Monorepo Configuration

Critical decision: Root directory vs custom commands.

Isolated monorepo (apps don't share code):

Set Root Directory to the app's subdirectory (e.g., /frontend)
Only that directory's code is available during build

Shared monorepo (TypeScript workspaces, shared packages):

Do NOT set root directory
Set custom build/start commands to filter the package:
- pnpm: pnpm --filter <package> build
- npm: npm run build --workspace=packages/<package>
- yarn: yarn workspace <package> build
- Turborepo: turbo run build --filter=<package>
Set watch paths to prevent unnecessary rebuilds

See monorepo.md for detailed patterns.

Project Setup Guidance

Analyze the codebase to ensure Railway compatibility.

Analyze Codebase

Check for existing project files:

package.json → Node.js project
requirements.txt, pyproject.toml → Python project
go.mod → Go project
Cargo.toml → Rust project
index.html → Static site
None → Guide scaffolding

Monorepo detection:

pnpm-workspace.yaml → pnpm workspace (shared monorepo)
package.json with workspaces field → npm/yarn workspace (shared monorepo)
turbo.json → Turborepo (shared monorepo)
Multiple subdirs with separate package.json but no workspace config → isolated monorepo

Scaffolding Hints

If no code exists, suggest minimal patterns from railpack.md:

Static site:

Create an index.html file in the root directory.

Vite React:

npm create vite@latest . -- --template react

Astro:

npm create astro@latest

Python FastAPI:

Create main.py with FastAPI app and requirements.txt with dependencies.

Go:

Create main.go with HTTP server listening on PORT env var.

Databases

For adding databases (Postgres, Redis, MySQL, MongoDB), use the database skill.

The database skill handles:

Creating database services
Connection variable references
Wiring services to databases

Composability

After service created: Use deploy skill to push code
For advanced config: Use environment skill (buildCommand, startCommand)
For domains: Use domain skill
For status checks: Use status skill
For service operations (rename, delete, status): Use service skill

Error Handling

CLI Not Installed

Railway CLI not installed. Install with:
  npm install -g @railway/cli
or
  brew install railway

Not Authenticated

Not logged in to Railway. Run: railway login

No Workspaces

No workspaces found. Create one at railway.com or verify authentication.

Project Name Taken

Project name already exists. Either:
- Link to existing: railway link -p <name>
- Use different name: railway init -n <other-name>

Service Name Taken

Service name already exists in this project. Use a different name:
  railway add --service <other-name>

Examples

Create HTML Static Site

User: "create a simple html site and deploy to railway"

1. Check status → not linked
2. railway init -n my-site
3. Guide: create index.html
4. railway add --service my-site
5. No config needed (index.html in root auto-detected)
6. Use deploy skill: railway up
7. Use domain skill for public URL

Create Vite React Service

User: "create a vite react service"

1. Check status → linked (or init/link first)
2. Scaffold: npm create vite@latest frontend -- --template react
3. railway add --service frontend
4. No config needed (Vite dist output auto-detected)
5. Use deploy skill: railway up

Add Python API to Project

User: "add a python api to my project"

1. Check status → linked
2. Guide: create main.py with FastAPI, requirements.txt
3. railway add --service api
4. No config needed (FastAPI auto-detected)
5. Use deploy skill

Link and Add Service

User: "connect to my backend project and add a worker service"

1. railway list --json → find "backend"
2. railway link -p backend
3. railway add --service worker
4. Guide setup based on worker type

Deploy to Railway (Ambiguous)

User: "deploy to railway"

1. railway status → not linked
2. railway list → has projects
3. Directory is "my-app", found project "my-app"
4. Ask: "Found existing project 'my-app'. Link to it or create new?"
5. User: "link"
6. railway link -p my-app
7. Ask: "Create a service for this code?"

Add Service to Isolated Monorepo

User: "create a static site in the frontend directory"

1. Check: /frontend has its own package.json, no workspace config
2. This is isolated monorepo → use root directory
3. railway add --service frontend
4. Invoke environment skill to set rootDirectory: /frontend
5. Set watch paths: /frontend/**

Add Service to TypeScript Monorepo

User: "add a new api package to this turborepo"

1. Check: turbo.json exists, pnpm-workspace.yaml exists
2. This is shared monorepo → use custom commands, NOT root directory
3. Guide: create packages/api with package.json
4. railway add --service api
5. Invoke environment skill to set buildCommand and startCommand (do NOT set rootDirectory)
6. Set watch paths: /packages/api/**, /packages/shared/**

Deploy Existing pnpm Workspace Package

User: "deploy the backend package to railway"

1. Check: pnpm-workspace.yaml exists → shared monorepo
2. railway add --service backend
3. Invoke environment skill to set buildCommand and startCommand
4. Set watch paths for backend + any shared deps

Deploy Subdirectory of Linked Project

User: "create a vite app in my-app directory and deploy to railway"
CWD: ~/projects/my-project/my-app (parent already linked to "my-project")

1. Check status in my-app → not linked
2. Check parent: cd .. && railway status → IS linked to "my-project"
3. DON'T init/link the subdirectory
4. Scaffold: bun create vite my-app --template react-ts
5. cd my-app && bun install
6. railway add --service my-app
7. Invoke environment skill to set rootDirectory: /my-app
8. Deploy from root: railway up

FAQ

What does the new skill do?

How do I install new?

Run npx skills add https://github.com/railwayapp/railway-skills --skill new in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/new/ (personal) or .claude/skills/new/ (project).

Which AI agents can use new?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is new safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains new?

It is published by railwayapp in railwayapp/railway-skills. It has 786 recorded installs.

More from railwayapp/railway-skills

View all →

use-railway

railwayapp/railway-skills

Operate Railway infrastructure: sign up for or sign in to a Railway account, create projects, provision services, databases, and buckets, deploy code, configure infrastructure as code, environments and variables, manage domains, trace requests with OpenTelemetry, troubleshoot failures, check status and metrics, manage feature flags, database recovery and HA, cloud agents, usage limits, and Railway agent tooling. Use this skill whenever the user mentions Railway, feature flags, flag rollout, targeting rules, signing up, creating an account, registering, logging in, deployments, services, environments, buckets, object storage, tracing, traces, spans, OpenTelemetry, OTLP, build failures, agent setup, MCP, or infrastructure operations, even if they don't say "Railway" explicitly. Also invoke it when the user asks to be signed up, registered, or onboarded: do not refuse — drive them through the unauthed railway up flow (deploys + signs up on the fly) or railway login (which creates acco

DevOps & Cloud8.9K installs

service

railwayapp/railway-skills

This skill should be used when the user asks about service status, wants to rename a service, change service icons, link services, or create services with Docker images. For creating services with local code, prefer the new skill. For GitHub repo sources, use new skill to create empty service then environment skill to configure source.

DevOps & Cloud1.6K installs

central-station

railwayapp/railway-skills

This skill should be used when the user asks about Central Station threads, community discussions, support questions, feature requests, or wants to search Railway's community knowledge base. Use for queries like "search central station", "find threads about", "what are people asking about", "recent support threads", or "central station topics".

1.5K installs

status

railwayapp/railway-skills

This skill should be used when the user asks "railway status", "is it running", "what's deployed", "deployment status", or about uptime. NOT for variables ("what variables", "env vars", "add variable") or configuration queries - use environment skill for those.

DevOps & Cloud1.5K installs

railway-docs

railwayapp/railway-skills

This skill should be used when the user asks about Railway features, how Railway works, or shares a docs.railway.com URL. Fetches up-to-date Railway docs to answer accurately.

Docs & Writing1K installs

deployment

railwayapp/railway-skills

This skill should be used when the user wants to manage Railway deployments, view logs, or debug issues. Covers deployment lifecycle (remove, stop, redeploy, restart), deployment visibility (list, status, history), and troubleshooting (logs, errors, failures, crashes, why deploy failed). NOT for deleting services - use environment skill with isDeleted for that.

DevOps & Cloud1K installs

Popular devops & cloud skills

View category →

microsoft-foundry

microsoft/azure-skills

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure

OfficialDevOps & Cloud579.1K installs

azure-diagnostics

microsoft/azure-skills

Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.

OfficialDevOps & Cloud569.8K installs

azure-prepare

microsoft/azure-skills

Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.

OfficialDevOps & Cloud569K installs

azure-ai

microsoft/azure-skills

Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.

OfficialDevOps & Cloud568.8K installs

azure-deploy

microsoft/azure-skills

Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.

OfficialDevOps & Cloud568.6K installs

azure-validate

microsoft/azure-skills

Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.

OfficialDevOps & Cloud568K installs

new

Install

Install

Describe the task

Review the result

SKILL.md

New Project / Service / Database

When to Use

Prerequisites

Decision Flow

Check Current State

When Already Linked

Parent Directory Linking

Init vs Link Decision

Check User's Projects

Decision Logic

Create New Project

Multiple Workspaces

Link Existing Project

Create Service

Configure Based on Project Type

Monorepo Configuration

Project Setup Guidance

Analyze Codebase

Scaffolding Hints

Databases

Composability

Error Handling

CLI Not Installed

Not Authenticated

No Workspaces

Project Name Taken

Service Name Taken

Examples

Create HTML Static Site

Create Vite React Service

Add Python API to Project

Link and Add Service

Deploy to Railway (Ambiguous)

Add Service to Isolated Monorepo

Add Service to TypeScript Monorepo

Deploy Existing pnpm Workspace Package

Deploy Subdirectory of Linked Project

FAQ

More from railwayapp/railway-skills

Popular devops & cloud skills