• https://coder.com/docs/llms.txt -- compact index. Every page is also available as raw Markdown by appending

  .md

  to its URL or sending

  Accept: text/markdown

  . Read this once at the start of the install to see what's available.
• https://coder.com/docs/llms-full.txt -- the full corpus in one file when the user asks something the index alone can't answer.

coder.com/docs/...md

• No flags, env-var names, or config keys in user-facing questions.

  --first-user-trial

  ,

  CODER_ACCESS_URL

  ,

  CODER_WILDCARD_ACCESS_URL

  , and

  CODER_EXTERNAL_AUTH_*

  are internal details. They can appear in commands you run, and in the final summary as paths to files you wrote, but not as things the user has to understand.
• Explain the thing before you name it. If you must use a Coder term, say what it does first in one short sentence, then use the term. Example: "a starter project that builds workspaces (Coder calls this a template)".
• Ask one short choice at a time. Never present a decision matrix.
• Default aggressively. Pick the obvious default and ask the user to confirm, instead of making them choose from options.
• Translate errors. Don't paste raw server logs at the user. Read the log yourself, decide what's wrong, and tell them in plain English. Show the raw log only if they ask.
• No "Coder-ese" in the final summary. The handoff at the end is what the user reads first. Use "sign-in page", "the app you can open in a browser", "the example project", not "access URL", "dashboard", "template".
• Do not narrate yourself. The user does not know or care that a "skill" exists. Never say "this skill", "the setup skill", "I ran the skill", "I used the skill", or similar. When you need to refer to what just happened, say "I installed Coder", "the install", or "setup". The handoff messages and any error explanations follow this rule too.
• Pick exactly one option in any user-facing template. When the skill text shows alternatives like

  <one of: tail -f ... | docker compose logs -f ...>

  , that notation is for you, not the user. Resolve it to the single command that matches how Coder is actually running before you show anything to the user. Never paste the alternatives literally.
• Do not point the user at

  coder.com/docs/*.md

  pages or any documentation URL in user-facing text. Those

  .md

  pages exist so the agent (you) can read them and apply the guidance. The user installed Coder so an agent would do this work for them; sending them a doc link is telling them to go read the manual instead. The only URLs that belong in chat are concrete user destinations (the deployment's access URL,

  coder.com/trial

  for license signup, similar). Documentation reading is yours, not theirs.
• Do not hand the user a CLI walkthrough as "what to try next." Lines like

  coder templates init

  ,

  coder templates push

  ,

  coder ssh <name>

  ,

  coder licenses add

  are things the agent runs, not things the user has to learn. If the user might want one of those actions, offer to do it for them in plain English ("want me to add a different starter?" / "want me to wire up Okta sign-in?") and run it when they say yes. The point of the skill is that the user doesn't have to type these commands.

• Coder -> "a thing that gives you and your team cloud development environments you open in the browser or in your editor".
• Access URL -> "the web address people will open to use Coder".
• Wildcard URL -> "a DNS setup that lets apps inside your dev environment have their own subdomain".
• Workspace -> "a single dev environment for one person".
• Template -> "a recipe Coder follows when it builds a workspace; e.g. 'one Linux container with VS Code'".
• Agent / Provisioner -> internals; users normally don't need to know they exist.
• External auth -> "letting workspaces sign in to GitHub / GitLab / etc. so they can clone private repos".
• Owner -> "the admin account; the first person to sign in becomes one automatically".
• Free vs paid -> Coder is open source; nothing the skill does costs money. The upstream CLI has a

  --first-user-trial

  flag that turns on a 30-day enterprise-feature evaluation; the skill always passes

  --first-user-trial=false

  and does not bring it up.

• Don't read reference files you don't need. Three exist:

  • references/first-user-github-device.md

    is only relevant when Phase 4 takes the GitHub device-code path; the protocol is summarized at the call site and the steps are real bundled scripts under

    scripts/

    . Read the reference only when something fails and the failure mode isn't already covered in Phase 4.

  • references/coder-agents.md

    is only relevant when the Phase 7 user accepts the Coder Agents offer. Read it then, not before. If they decline, skip the file entirely.

  • references/troubleshooting.md

    is only relevant when something is actually stalled (see the bullet below).
  Reading any of those proactively to "refresh" wastes a multi-thousand-token tool call the user is waiting on.
• Don't run probes you don't need. The host probe in Phase 1 exists to fill in defaults; if the user already answered the five core questions, you don't need to detect the package manager or the distro version.
• Combine related shell into one tool call. A short multi-line block (

  mkdir; curl; verify

  ) is one round trip; the same three operations as three separate tool calls is three round trips of latency. The exception is the GitHub device flow, which must stay split for the reason documented at the Phase 4 call site.
• Stream long-running commands instead of waiting on their full output.

  coder server

  ,

  coder templates push

  , and

  coder create

  all take a while; tail their logs from a state-dir file rather than blocking the chat on their stdout.
• When something stalls (server won't come up, provisioner can't reach Docker, certificates won't issue, the apex doesn't resolve), check

  references/troubleshooting.md

  before you start diagnosing from scratch. The five recurring failure modes documented there (embedded Postgres on ARM, bundled Terraform's PGP key, fresh Docker group not picked up by the running server, Caddy redirect loops, home-router rebind protection) are not in upstream docs and have known fixes.

1. Discover. Ask the user a small set of questions in plain English. Probe the host afterward to fill in defaults.
2. Install. Use

   install.sh

   (or Helm / compose).
3. Start. Run the server.
4. Sign in. Make the asking user the admin (Owner).
5. Template. Push a starter that matches the chosen infrastructure.
6. Workspace (optional). Build the first dev environment.
7. Hand off. Tell the user how to sign in, how to start / stop, and where to go next.

AskUserQuestion

AskUserQuestion

AskUserQuestion

{
  "questions": [
    {
      "question": "Have you used Coder before?",
      "header": "Familiarity",
      "multiSelect": false,
      "options": [
        {"label": "First time", "description": "Never used Coder; explain concepts as we go."},
        {"label": "Used it before", "description": "Skip the explanations; use Coder terms directly."}
      ]
    },
    {
      "question": "Are you trying Coder out, or setting it up for your team long-term?",
      "header": "Deployment mode",
      "multiSelect": false,
      "options": [
        {"label": "Just trying it out", "description": "Quick-start on this machine; auto-tunnel URL."},
        {"label": "For my team", "description": "Production: real domain, TLS, optional Postgres / OIDC."}
      ]
    },
    {
      "question": "Where do you want Coder to run?",
      "header": "Infrastructure",
      "multiSelect": false,
      "options": [
        {"label": "Docker on this machine", "description": "Easiest if Docker is installed."},
        {"label": "Kubernetes / Helm", "description": "Against a cluster you can reach with kubectl."},
        {"label": "Directly on this machine", "description": "The binary, with systemd."},
        {"label": "Something else", "description": "Rancher, OpenShift, AWS / GCP / Azure Marketplace, air-gapped."}
      ]
    },
    {
      "question": "How do you want to sign in as the admin?",
      "header": "Sign-in",
      "multiSelect": false,
      "options": [
        {"label": "GitHub", "description": "I'll show you a short URL and a code; works from any phone."},
        {"label": "Email and password", "description": "I'll generate a strong password and save it locally."}
      ]
    }
  ]
}

{
  "questions": [
    {
      "question": "Want me to set up a starter dev environment and build the first one?",
      "header": "Dev environment",
      "multiSelect": false,
      "options": [
        {"label": "Yes, match my infrastructure", "description": "Linux container if Docker, Linux pod if Kubernetes."},
        {"label": "Yes, a different kind", "description": "Tell me which (cloud VM, your own Terraform, etc.)."},
        {"label": "Push the starter, but don't build a workspace yet", "description": "I'll do the first build myself."},
        {"label": "Skip this entirely", "description": "Just install Coder; I'll add a template later."}
      ]
    }
  ]
}

AskUserQuestion

claude -p

Before I start, five quick questions:

1. Have you used Coder before, or is this your first time?
2. Are you trying Coder out on this machine, or setting it up for your team to use long-term?
3. Where do you want Coder to run? Docker on this machine, Kubernetes / Helm against a cluster, directly on this machine (binary + systemd), or something else (Rancher, OpenShift, AWS / GCP / Azure, air-gapped)?
4. For sign-in, GitHub (I'll show you a short URL and a code; works from any phone) or just create an email and password for you?
5. After Coder is up, do you want me to push a starter dev environment and build the first one for you (default yes)? If you have a specific kind in mind, say so; otherwise I'll match what you picked in question 3.

AskUserQuestion

1. Map each answer using the tables in the per-question subsections below.
2. Probe the host quietly (what package manager, is Docker installed, is there an existing Coder login, is this itself a Coder workspace).
3. Show the user one short plan paragraph and get a single yes/no before doing anything destructive.

uname -a

which docker

cat /etc/os-release

• The workspace-host guard (don't install a host

  coder

  if this is itself someone's Coder workspace) runs at the start of Phase 2.
• The existing-login guard (only isolate

  CODER_CONFIG_DIR

  when the host already has a Coder session pointing somewhere the user wouldn't want overwritten) runs at the start of Phase 4.

AskUserQuestion

• new. Whenever you reach a Coder-specific concept (workspace, template, agent, provisioner, access URL, wildcard URL, external auth), pause for one sentence in plain English before using the word. Example: "Coder builds your dev environments from a recipe written in Terraform; we call those recipes templates. I'll push a starter template now." Don't belabor it; one sentence, then move on. When you mention Terraform, name it as "the language Terraform uses to describe cloud infrastructure" the first time. The glossary in the "Talking to the user" section is the source of phrasings.
• familiar. Skip the inline explanations. Use the Coder terms directly. Don't gloss "template" or "workspace".

AskUserQuestion

• GitHub. Drive GitHub's standard device-code flow over Coder's API. Print a short URL and an 8-character code; the user opens the URL on whatever device is handy (their phone is fine), pastes the code, approves access on GitHub, and Phase 4 captures the session and finishes setup. No browser on the install machine, no password to record.
• Email and password. Fully scripted, no GitHub round trip. Pick a strong password, create the admin account from the terminal, save the email and password to a file in the install's state directory.

claude -p

default_provider_configured

/users/oauth2/github/device

EMAIL_DEFAULT="$(git config --global --get user.email 2>/dev/null || true)"

• Web address. Default to Coder's automatic

  *.try.coder.app

  address. Tell the user, don't ask. Fall back to a local-only URL only if the auto-tunnel can't initialize (offline host) or the user asks. Phase 3 has the detection recipe.

AskUserQuestion

{
  "questions": [
    {
      "question": "What domain should people open in their browser to use Coder?",
      "header": "Domain",
      "multiSelect": false,
      "options": [
        {"label": "I have a subdomain in mind", "description": "e.g. coder.example.com. I'll ask which one next."},
        {"label": "Use a Tailscale name (tailnet-only)", "description": "Reachable only inside your tailnet; no public DNS or cert."},
        {"label": "Localhost / IP for now", "description": "Skip the domain; revisit once you have one."}
      ]
    },
    {
      "question": "How do you want HTTPS handled?",
      "header": "HTTPS",
      "multiSelect": false,
      "options": [
        {"label": "Caddy in front", "description": "Recommended. Auto-renews Let's Encrypt certs."},
        {"label": "Existing reverse proxy", "description": "nginx, traefik, cert-manager, etc.; I'll generate a config and you slot it in."},
        {"label": "Coder terminates TLS itself", "description": "Single-binary install with cert files I'll point Coder at."},
        {"label": "No TLS", "description": "Tailnet-only or other private network where TLS isn't required."}
      ]
    },
    {
      "question": "Want a wildcard subdomain for in-workspace apps?",
      "header": "Wildcard",
      "multiSelect": false,
      "options": [
        {"label": "Yes, set it up", "description": "Workspace port-forwarded apps get their own *.coder.example.com URL."},
        {"label": "No, skip it", "description": "You can add it later if you start using port-forwarded apps."}
      ]
    },
    {
      "question": "Run Coder under systemd so it auto-starts on reboot?",
      "header": "Service",
      "multiSelect": false,
      "options": [
        {"label": "Yes", "description": "Recommended for any production deployment."},
        {"label": "No, foreground for now", "description": "I'll just background it; you can wire systemd later."}
      ]
    }
  ]
}

"Coder needs a Postgres in production. Do you have one I can point at, or want me to install Postgres on this host? If you have one, paste the connection string (

postgres://user:pass@host:5432/db?sslmode=...

)."

• If the user picked Caddy in front with a real domain, ask which DNS provider hosts the zone (Cloudflare, Route 53, etc.) so the wildcard cert can use DNS-01. The provider's API token is a separate paste; confirm

  [set]

  and never echo it back.
• If the user picked a Tailscale name, mention up front that you'll need Tailscale split-DNS configured for the apex to resolve from non-tailnet contexts (workspace containers in particular). See

  references/troubleshooting.md

  if you hit it.

~/.local/state/coder-install

~/.config/coderv2-quickstart

AskUserQuestion

{
  "questions": [
    {
      "question": "I see a quick-start Coder running on this machine. Want me to take it down before I bring up production?",
      "header": "Quick-start state",
      "multiSelect": false,
      "options": [
        {"label": "Take it down and clean up", "description": "Stop the tunnel server, delete ~/.local/state/coder-install and ~/.config/coderv2-quickstart."},
        {"label": "Take it down but keep the files", "description": "Stop the server; leave the state for me to inspect later."},
        {"label": "Leave it running", "description": "Two Coder servers on one host; production still goes up under different config."}
      ]
    }
  ]
}

pkill coder

$STATE_DIR/server.pid

coder

• Wildcard URL: https://coder.com/docs/admin/networking/wildcard-access-url.md
• GitHub OAuth (default and custom): https://coder.com/docs/admin/users/github-auth.md
• OIDC (Okta, Entra, Google, etc.): https://coder.com/docs/admin/users/oidc-auth.md
• External authentication for workspaces (clone private repos): https://coder.com/docs/admin/external-auth.md
• External provisioners: https://coder.com/docs/admin/provisioners.md

uname -sm
command -v apt-get dnf yum apk brew zypper pacman 2>/dev/null
docker version --format '{{.Server.Version}}' 2>/dev/null
kubectl config current-context 2>/dev/null
helm version --short 2>/dev/null
coder --version 2>/dev/null
systemctl is-active coder 2>/dev/null
test -f "$HOME/.config/coderv2/url" && cat "$HOME/.config/coderv2/url"
env | grep -E '^(CODER_AGENT_TOKEN|CODER_WORKSPACE_NAME)=' || true

• coder --version

  succeeds. Plan to reuse the existing binary; skip the install in Phase 2 unless the user asked for a fresh install or production needs a newer release.
• No Docker, no Helm. If the user picked one of those, walk them through installing it first; otherwise the standalone install is the only option.

• ~/.config/coderv2/url

  exists and points somewhere the user wouldn't want clobbered. Plan to isolate

  CODER_CONFIG_DIR

  in Phase 4. Mention it in the plan paragraph; don't ask.
• No existing config dir. Use the default (

  ~/.config/coderv2

  ). Do not isolate by default. Isolation is only for the conflict case.

• CODER_AGENT_TOKEN

  or

  CODER_WORKSPACE_NAME

  is set. This is itself someone's Coder workspace. Phase 2 will refuse a host install and steer to Docker compose or a separate cluster context. Note this in the plan so the user knows why.

claude -p

CODER_AGENT_TOKEN

CODER_WORKSPACE_NAME

coder

pkill coder

install.sh

/usr/local/bin/coder

• Refuse a host install unless the user explicitly asked for nested Coder.
• Docker compose is fine when scoped to a sub-directory and a non-default port. Workspaces ship Docker; the inner server runs in its own container.
• Kubernetes via Helm is fine when targeted at a separate cluster context, not the workspace's host.

references/troubleshooting.md#never-pkill-coder-on-a-coder-workspace

curl -fsSL https://coder.com/install.sh | sh

curl -fsSL https://coder.com/install.sh \
  | sh -s -- --method standalone --prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"

• Docker: https://coder.com/docs/install/docker.md
• Kubernetes / Helm: https://coder.com/docs/install/kubernetes.md
• Standalone CLI: https://coder.com/docs/install/cli.md
• Rancher / OpenShift / Cloud / Air-gapped: see the install/ index page.

install.sh

--help

• --mainline

  (default) or

  --stable

  : pick the release channel. Use

  --stable

  for production unless the user asked for mainline.

• --version X.Y.Z

  : pin a specific version.

• --with-terraform

  : install Terraform alongside Coder. Use this when the deployment will run Terraform locally (almost every template does).

• --method standalone --prefix DIR

  : user-local install with no package manager and no sudo.

• --dry-run

  : print the commands without running them.

coder --version

environment:

• https://coder.com/docs/install/kubernetes.md for Helm.
• https://coder.com/docs/install/docker.md for compose.
• https://coder.com/docs/admin/setup.md for the env-var matrix (

  CODER_ACCESS_URL

  ,

  CODER_PG_CONNECTION_URL

  ,

  CODER_TLS_*

  ,

  CODER_REDIRECT_TO_ACCESS_URL

  ,

  CODER_WILDCARD_ACCESS_URL

  ).

/healthz

for _ in $(seq 1 120); do
  curl -fsS "$ACCESS_URL/healthz" >/dev/null 2>&1 && break
  sleep 1
done

curl -fsS "https://app-test.${WILDCARD_DOMAIN}/healthz"

DEVICE_OK=true
curl -fsS "$ACCESS_URL/api/v2/users/authmethods" \
  | python3 -c '
import json, sys
d = json.load(sys.stdin)
sys.exit(0 if d["github"].get("default_provider_configured") else 1)
' || DEVICE_OK=false

curl -fsS "$ACCESS_URL/api/v2/users/oauth2/github/device" >/dev/null 2>&1 || DEVICE_OK=false

DEVICE_OK=false

scripts/github-device-fetch.sh

scripts/github-device-poll.sh

references/first-user-github-device.md

1. Fetch. One short shell command:
   sh

   ACCESS_URL="$ACCESS_URL" \
     bash "$SKILL_DIR/scripts/github-device-fetch.sh"

   Returns in ~3 seconds. Writes

   $STATE_DIR/github-device.{jar,env}

   and prints

   USER_CODE

   /

   VERIFY_URI

   /

   EXPIRES_IN

   on stdout. Do NOT include the polling loop in this call; if you do, the command sits for up to 15 minutes and the user never sees the code.
2. Tell the user, in chat (not in a shell command). Read

   $VERIFY_URI

   and

   $USER_CODE

   from

   $STATE_DIR/github-device.env

   (or from the fetch script's stdout) and send the user a chat message like:

   To sign in to Coder, open this on any device (your phone is fine):

   $VERIFY_URI

   Enter this code:

   $USER_CODE

   Say "ok" when you're done and I'll finish setting you up as the admin.

   Wait for the user's acknowledgement ("ok", "done", "entered it"). If they ask for a different sign-in method instead, abandon the device flow and switch to email-and-password.
3. Poll. A separate shell command:
   sh

   ACCESS_URL="$ACCESS_URL" \
     bash "$SKILL_DIR/scripts/github-device-poll.sh"

   Loops until the user finishes on github.com, writes the session token into

   $CODER_CONFIG_DIR/{url,session}

   , removes the cookie jar / env / response scratch files (success or failure), and verifies with

   coder whoami

   and

   coder users list

   .

$SKILL_DIR

SKILL.md

~/.claude/plugins/coder/skills/setup

--plugin-dir

users list

OWNER

server.log

server.pid

<one of: ...>

=== Coder is ready ===

You're signed in as the admin.

Coder is running here as a host process. The binary is at
$(command -v coder); its data lives in
${CODER_CONFIG_DIR:-$HOME/.config/coderv2}.

Open Coder in your browser:
  $ACCESS_URL

To start, stop, or check on Coder later:
  - Logs:  tail -f $STATE_DIR/server.log
  - Stop:  kill $(cat $STATE_DIR/server.pid)

What to try next:

  - Open "$WORKSPACE_NAME" in Coder right now.
  - Use it like any other dev environment from your editor or
    a browser; no extra setup on your end.

Ask me about anything else; I'm still here.

Working files are in $STATE_DIR. Delete that directory to undo
what setup wrote here.

Coder is running in Docker on this machine. The compose file
is at $STATE_DIR/docker-compose.yml.

  - Logs:  docker compose -f $STATE_DIR/docker-compose.yml logs -f coder
  - Stop:  docker compose -f $STATE_DIR/docker-compose.yml down

Coder is running as a systemd service named `coder`.

  - Logs:  journalctl -u coder -f
  - Stop:  sudo systemctl stop coder

Coder is running in Kubernetes as the `coder` Helm release in
the `coder` namespace.

  - Logs:  kubectl logs -n coder deploy/coder -f
  - Stop:  helm uninstall coder -n coder

Sign in at $ACCESS_URL with:

  Email:    $EMAIL
  Password: $PASSWORD

Setup wrote them to $STATE_DIR/credentials (mode 0600). Don't
share that file.

Open $ACCESS_URL in your browser and click "Sign in with GitHub".
You'll be the admin once you finish.

If you ever want to try Premium features (Workspace Proxies,
groups, audit log retention, template ACLs), let me know and
I'll point you at https://coder.com/trial to request a key.
The trial signup collects some company info, so I'll leave
that part to you.

One more thing: Coder has a built-in agents UI that runs AI
coding agents inside your deployment against your own LLM key.
Want me to wire it up?

references/coder-agents.md

/swagger/doc.json

GET /api/experimental/chats/models

"Anything else? OIDC sign-in, GitLab, a custom domain, a different kind of dev environment, or that Coder Agents setup? Just tell me which."

.md

coder.com/docs/...

• Do not write to the user like a sysadmin. If a user-facing message contains a flag (

  --first-user-trial

  ), an env var (

  CODER_ACCESS_URL

  ), or an internal noun ("OAuth provider", "ingress", "terraform"), rewrite it. Decide what they need to know in plain English, pick a default, and ask for one short answer.
• Do not duplicate Coder's docs. If a question is about a topic that lives on coder.com/docs (OIDC, custom OAuth, templates, provisioners, wildcard URL, TLS, upgrades, etc.), point at the docs page and apply what it says. Do not transcribe it into the skill; it will go stale.
• Do not run

  pkill coder

  (or any blanket

  kill

  against the coder binary) when

  CODER_AGENT_TOKEN

  is set. That terminates the workspace agent the user is connected through. See

  references/troubleshooting.md#never-pkill-coder-on-a-coder-workspace

  .
• Do not run destructive cleanup commands without an explicit user request.

  docker compose down -v

  ,

  helm uninstall coder

  , and

  kubectl delete namespace coder

  permanently destroy the database and every workspace built from it.
• Do not pipe

  install.sh

  to

  sudo sh

  unless the user asked for a system-wide install. Default to user-local where possible.
• Do not isolate

  CODER_CONFIG_DIR

  by default. Only isolate when the host already has a Coder login pointing somewhere the user wouldn't want overwritten.
• Do not assume Docker. Ask the infrastructure question. Don't silently default; even when Docker is installed, the user may want Kubernetes or a direct install.
• Do not ask the Phase 1 questions as plain chat text when

  AskUserQuestion

  is available. The structured picker is the supported UX; chat-message fallbacks lose the click-to- answer affordance, options look like prose the user has to parse, and the agent is more likely to drop questions. Use the two

  AskUserQuestion

  calls described in Phase 1 (four questions, then one). Only fall back to chat text if the runner reports the tool as unavailable.
• Do not collapse Phase 1 into a two-question interview. The five core questions (familiarity, mode, infrastructure, sign-in, dev environment) are non-negotiable. Real users have reported agents asking only mode + sign-in and silently guessing the rest, ending up with a Docker install and a workspace they didn't know they were building. Use

  AskUserQuestion

  and ship all five questions across the two documented calls.
• Do not call

  coder create

  before reading the template's required parameters. A blind

  coder create

  against a starter that has required list parameters (e.g.

  jetbrains_ides

  on the Docker template) hangs on stdin or fails outright, then forces a retry.

  coder templates pull

  • a quick scan of

    main.tf

    is cheaper than the wasted retry.
• Do not echo cloud credentials, OAuth client secrets, provisioner keys, or the admin password back to the user. Confirm receipt with

  [set]

  or a redacted form.
• Do not ask the user to paste an LLM API key into chat. Chat transcripts and shell history persist; a key dropped inline is leaked the moment the user says "send this log to support." Have them export it in their shell first (

  read -s LLM_KEY

  or

  export LLM_KEY=...

  ) and then read

  $LLM_KEY

  from your environment without ever printing it. If a user pastes anyway, accept the value, finish the setup, and tell them in the handoff to rotate the key on the provider's dashboard.
• Do not opt the user into the upstream enterprise-trial license flow unless they explicitly asked. Always pass

  --first-user-trial=false

  to

  coder login

  and never set

  CODER_FIRST_USER_TRIAL=true

  . The signup-time path collects PII (name, phone, job title, company, country, dev count) and POSTs it to Coder's licensor; there is no consent UX in the skill for that. If a user later wants Premium features,

  POST /api/v2/licenses

  and

  coder licenses add

  accept a JWT they request themselves.
• Do not skip the

  /healthz

  readiness probe. A successful

  coder server

  exit doesn't mean the API is up.
• Do not run

  coder server

  in a foreground that ties up the chat. Background it and tail the log.
• Do not run the GitHub device-flow scripts back to back in one tool call. Tool runners buffer shell stdout until the command exits. A fetch immediately followed by a poll prints the

  user_code

  early, then sits in a 15-minute polling loop, so the code stays in the buffer until the loop times out and the user never sees it. Run

  scripts/github-device-fetch.sh

  , send the user a chat message with the URL and code from

  $STATE_DIR/github-device.env

  , wait for them to acknowledge, then run

  scripts/github-device-poll.sh

  as a separate tool call. See

  references/first-user-github-device.md

  .
• Do not inline the device-flow shell into the chat. The scripts under

  scripts/

  are the source of truth. Don't paste their contents back into Phase 4 or copy fragments of them inline; call them by path. Inlining drifts from the bundled version on every change and skips the trap-based cleanup.
• Do not narrate "the skill" at the user. They asked you to install Coder; they didn't subscribe to the implementation. Never say "this skill", "the setup skill", "I ran the skill", or "the skill saved ...". Use first person about what was installed ("I installed Coder", "setup wrote credentials to ...") in every user-facing message and in the final handoff.
• Do not paste the

  <one of: ...>

  placeholders at the user. The angle-bracket alternatives in the Phase 7 templates are notes to you. Pick the single command pair that matches how Coder is actually running (host / Docker compose / systemd / Kubernetes) before printing.
• Do not put

  coder.com/docs/*.md

  (or any other docs URL) in user-facing text. Documentation pages are for the agent to read and apply, not for the user to study. If a topic is worth raising, offer to handle it ("want me to wire up Okta sign-in?") and read the docs page yourself when they say yes. Real users have reported the Phase 7 handoff dumping five

  .md

  URLs at them, which made the install feel like homework.
• Do not hand the user a CLI walkthrough as "what to try next."

  coder templates init

  ,

  coder templates push

  ,

  coder ssh

  ,

  coder licenses add

  : those are agent operations, not user instructions. If the user wants one of those, offer it in plain English and run it for them. The point of the skill is that the user doesn't have to learn the CLI.
• Do not leave OAuth scratch files lying around. The GitHub device-flow recipe writes a cookie jar and an env file under

  $STATE_DIR/github-device.*

  . Both step 1 and step 3 must install

  trap

  cleanups; step 3 must always remove them on exit, success or failure. They contain OAuth state and have no value once the session token is captured.
• Do not disable telemetry on the user's behalf. It defaults to on, and Coder strips PII before sending. The user can opt out themselves with

  CODER_TELEMETRY_ENABLE=false

  ; don't ask them and don't decide for them.