agents/

agents/pitch-deck

app_data

app_files

agents/proposals

.docx

apps/

$create-railcode-app

"Railcode provides an example that already generates client proposals from meeting notes. Should I use that as a starting point, or build from scratch?"

git clone

.git

mkdir -p my-proposals
curl -fsSL https://github.com/Railcode-HQ/railcode-examples/archive/refs/heads/main.tar.gz \
  | tar -xz --strip-components=3 -C my-proposals railcode-examples-main/agents/proposals

--strip-components=3

railcode-examples-main/agents/<example>/

my-proposals/

https://raw.githubusercontent.com/Railcode-HQ/railcode-examples/main/agents/proposals/agents/proposal-writer/agent.yaml

agents/<agent-name>/agent.yaml

railcode.json

manifest.yaml

• Rename each

  agents/<name>/

  directory and the manifest's

  name

  , so the copy doesn't collide with an agent that already exists in the org.
• Point

  tools.app_data

  /

  app_files

  /

  app_data_write

  at the renamed companion app slug, and keep

  visibility

  right for the tools declared (

  personal_connectors

  needs

  personal

  ).
• Cut every tool the new agent doesn't need — a copied manifest carries the example's authority, not the narrowest set for this job — and re-size

  limits

  for the new workload.
• Rewrite the

  system

  prompt and

  input_schema

  for the new contract; the example's prompt encodes its own step-by-step procedure and input shape.
• In the app: set

  app

  in

  railcode.json

  , rename

  package.json

  's

  name

  , run

  npm install

  , update the

  agents:

  list in

  manifest.yaml

  and every

  agents.invoke

  /

  agents.start

  call, and replace the example's

  README.md

  if it ships one.

railcode agent test --file …

railcode db list                       # database/data-source connections
railcode query list                    # admin-published saved queries over those sources
railcode connector list                # org service connectors
railcode personal-connectors list      # per-user bundled and custom toolkits + connection status

railcode connector docs <name>

railcode personal-connectors tools <toolkit>

adhoc_sql

visibility: personal

custom_<slug>

• the job it owns and the output expected;
• the input it accepts — free-form JSON or text; the

  system

  prompt is the input contract;
• the model and tools it needs;
• whether it runs on demand, from an app, on a schedule, or by Slack mention;
• whether it needs a companion app (see Companion Apps);
• whether to start from an example — when one in Start From An Example covers much of the request, ask: "Railcode provides an example that already generates client proposals from meeting notes. Should I use that as a starting point, or build from scratch?";
• what real systems, data, spend, or side effects a test may touch;
• its visibility —

  org

  (the default: shared, invokable by anyone with an invoke grant, managed by its creator or any admin) or

  personal

  (owned and invoked by its creator alone, admins included — no grant makes it shared, and it cannot later become

  org

  ). Pick

  personal

  only when the agent needs

  tools.personal_connectors

  (its owner's own Gmail/Slack/etc.) or should otherwise be usable by exactly one person.

limits

limit_exceeded

limits

tools.*

limits

system

• Corrections phrased as history — "We no longer do X, do Y instead." This agent never did X; the sentence introduces X and asks it to carry both. State only Y.
• Debug leftovers — a temporary "for now, only process the first three rows", or a workaround for a bug that has since been fixed.
• Orphaned steps — instructions naming a tool, app, connector, or field the manifest no longer declares.
• The same rule three times in slightly different words, each added during a different test round. Restatements compete; keep the clearest one.

railcode agent update

system

railcode agent pull

@Railcode $<agent-name> summarize this thread

$

• Authority is unchanged. The Slack caller is resolved by verified email to a live org member and must hold the normal invoke grant — no match, no run. A

  personal

  agent is therefore reachable on Slack only by its owner.
• Input arrives as

  { text: <message> }

  . Agent input is free-form, so any agent can be mentioned; its

  system

  prompt must explain how to interpret that input.
• The platform posts the final reply into the mentioning thread, on success and on failure. Whatever the agent returns IS the Slack reply (a Slack-triggered run is told so in its system prompt and to write Slack mrkdwn); it does not need the

  slack

  connector to answer — that connector, when granted, is for interim progress updates only.

$create-railcode-app

• Storage the agent relies on — the app is the UI for uploading and managing the files and records the agent reads:

  files.upload()

  /

  db

  in the app;

  app_files: [<app-slug>]

  /

  app_data: [<app-slug>]

  in the agent's manifest.
• A surface for results — the agent writes back via

  app_data_write

  (

  app_kv_set

  ,

  publish_artifact_to_app

  ) and the app renders run outputs.
• An easy way to test and trigger — a button wired to

  agents.invoke(name, input)

  (app manifest:

  agents: [<agent-name>]

  ) exercises the agent end-to-end far faster than hand-crafting CLI runs, and doubles as the interactive production trigger.

report-extractor

report-extractor-console

$create-railcode-app

agents/

$create-railcode-app

• Reach the open web. Sandbox egress is an allowlist (PyPI, npm, the presigned download host with

  app_files

  ); the

  connector

  tool reaches only ratified endpoints. No scraping, no arbitrary APIs.
• Run long or continuously. Runs are bounded — at most 300 steps / 1200 s / the token caps in

  limits

  . No daemons, no monitors; recurring work is a cron schedule.
• React to events. Triggers are app/API call, cron, and Slack mention only — no data-change or inbound-webhook triggers.
• Invoke other agents. There is no agent→agent tool; compose pipelines through an app or an external caller instead.
• Use custom MCP personal connectors. A user-added by-URL MCP connector (

  custom_<slug>

  ) works for its owner and for apps, but is not declarable in an agent manifest — ratification checks the static registry. Bundled toolkits only.
• Keep sandbox state. The sandbox filesystem is per-run; anything worth keeping must be published (

  publish_artifact_to_app

  ) or written to KV before the run ends.

• list

  ,

  show

  , and

  pull

  only ever return org agents plus the caller's own personal agents — someone else's personal agent is invisible (a 404, never a 403, to avoid confirming it exists), admins included.
• For an org agent:

  run

  needs an invoke grant for that agent;

  update

  /

  delete

  /

  test

  / schedule mutations are allowed for the agent's own creator, or any org owner/admin — not every member. Creating (or transitioning an existing agent to)

  org

  additionally needs the

  agent:create_org

  capability.
• For a personal agent: invoke and manage are both owner-only, with no admin override — there is no break-glass, so even an org owner/admin can't reach someone else's. Creating one needs the broadly-grantable

  agent:create

  capability, not owner/admin.

• delete

  archives the agent while keeping run history and requires

  --yes

  outside a TTY.
• Use

  $create-railcode-app

  when building a static app that invokes an agent through

  agents.invoke(name, input)

  . A privileged app manifest declares

  agents: [name]

  .
• An app can also run its own agentic loop in the page with

  llm.generate({ tools })

  /

  llm.stream({ tools })

  — no managed agent involved. See When To Use A Managed Agent vs The In-Page LLM at the top of this skill for the split.
• Use

  $manage-railcode-org

  for members, roles/grants, apps/access, connections, service connectors, analytics, and organization logs.