feat: add modules and templates skills

skills/modules/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: modules
+description: >
+  Add a Coder module from registry.coder.com/modules to an existing
+  Coder template, or update one that is already there. Use for
+  requests like "add the Cursor IDE to my template", "give workspaces
+  JetBrains access", "set up code-server", "wire in dotfiles",
+  "install Claude Code in this template", or "pin module versions".
+  Do not use for installing or upgrading Coder itself (use the setup
+  skill), authoring a brand-new template from scratch (use the
+  templates skill), or publishing a custom module to the registry.
+---
+
+# Modules
+
+Add or update Coder modules inside an existing Coder template.
+Modules are Terraform snippets published at registry.coder.com that
+extend a workspace with IDEs, AI agents, secrets, login flows, cloud
+regions, and other tools.
+
+## Source of Truth
+
+Read current upstream docs before applying anything topic-specific:
+
+- <https://coder.com/docs/llms.txt> for the docs index.
+- <https://coder.com/docs/llms-full.txt> only when the index is not
+  enough.
+- Each module's page on registry.coder.com has the canonical Terraform
+  snippet and version. Prefer that over a memorized version.
+
+This skill keeps only the integration workflow, user interaction
+rules, and a few module-specific gotchas.
+
+## User Interaction
+
+The user wants a working module integration, not a Terraform lesson.
+
+- Confirm which template you are editing when the user has more than
+  one.
+- Show the proposed snippet before writing it. Ask for one yes/no.
+- Never bump a module version silently. Call out version changes.
+- Do not lecture the user on Coder concepts unless they ask.
+
+## Workflow
+
+### 1. Identify the module
+
+Search for what the user described. Try these in order and stop at
+the first hit:
+
+1. The registry MCP server at `https://registry.coder.com/mcp` with
+   the `search_modules` tool.
+2. The website at <https://registry.coder.com/modules>.
+3. `find registry/coder/modules -maxdepth 1 -type d` against a local
+   clone of `coder/registry`.
+
+If the request is ambiguous, list two or three matching options with
+one-line descriptions and ask the user to pick one.
+
+### 2. Locate the target template
+
+Coder modules go inside a Coder template, which is Terraform code on
+disk. Confirm:
+
+- A directory with `main.tf`.
+- A `coder_agent` resource. Most modules need an `agent_id`.
+- A `data "coder_workspace" "me"` data source. Most modules gate on
+  `data.coder_workspace.me.start_count`.
+
+If no template directory exists, stop and offer the templates skill.
+
+### 3. Read the module page
+
+Fetch the canonical snippet:
+
+- From the module's README on registry.coder.com.
+- Or from `registry/coder/modules/<name>/README.md` in a local clone
+  of `coder/registry`.
+
+Always pin the version shown on the page. Never use `latest`. Never
+fabricate a version that is not listed.
+
+### 4. Insert the module
+
+Add the snippet to `main.tf`. Common rules:
+
+- Set `agent_id` to the existing `coder_agent` resource. Templates
+  usually have exactly one.
+- Keep `count = data.coder_workspace.me.start_count` for modules that
+  should only run while the workspace is started.
+- Match the surrounding indentation and quoting style.
+- Modules with extra inputs (JetBrains IDE selection, Vault auth,
+  JFrog instance URL, MCP config) take additional arguments. Read the
+  module README's Examples section before guessing.
+
+### 5. Validate
+
+In the template directory:
+
+```sh
+terraform init
+terraform fmt
+terraform validate
+```
+
+`terraform fmt` may reformat unrelated parts of the file the user has
+not touched. If that happens, ask before committing.
+
+### 6. Push
+
+If the user wants the change live on a Coder deployment:
+
+```sh
+coder templates push "$TEMPLATE_NAME" -d "$TEMPLATE_DIR"
+```
+
+Confirm the new version with `coder templates list`.
+
+## Common Modules
+
+Curated shortlist of the most-requested categories. Full catalogue at
+<https://registry.coder.com/modules>.
+
+- IDEs: `cursor`, `jetbrains`, `code-server`, `vscode-desktop`,
+  `vscode-web`, `windsurf`, `zed`, `kiro`.
+- AI agents: `claude-code`, `aider`, `goose`, `amazon-q`, `agentapi`.
+- Dev environment: `dotfiles`, `git-clone`, `git-config`,
+  `personalize`, `coder-login`.
+- Secrets: `hcp-vault-secrets`, `vault-cli`, `vault-github`,
+  `vault-jwt`, `vault-token`.
+- Apps: `filebrowser`, `jupyterlab`, `jupyter-notebook`,
+  `rstudio-server`, `kasmvnc`.
+- Cloud regions: `aws-region`, `azure-region`, `gcp-region`,
+  `fly-region`.
+
+## Safeguards
+
+- Do not add a module to a template that has no `coder_agent`. The
+  module will not function and the workspace will silently miss the
+  integration.
+- Do not add a module that needs admin-level configuration (Vault
+  backend, JFrog instance, external auth providers) without
+  confirming the deployment has that side configured.
+- Do not run `coder templates push` without telling the user which
+  template version they will get.
+- Do not edit `main.tf` if the user has uncommitted changes; offer to
+  stash or commit first.
+- Do not invent module names or versions. If you cannot find the
+  module on registry.coder.com, say so.
+
+## Bundled Resources
+
+No per-module recipes ship with this skill. Defer to each module's
+README on registry.coder.com and to upstream Coder docs.

skills/modules/agents/openai.yaml

@@ -0,0 +1,6 @@
+  display_name: "Coder Modules"
+  short_description: "Add or update Coder modules in an existing template"
+  icon_small: "../../../assets/icon.png"
+  icon_large: "../../../assets/logo.png"
+  brand_color: "#000000"
+  default_prompt: "Use $modules to add a Coder module to my template."

skills/templates/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: templates
+description: >
+  Create, edit, push, or version a Coder template. Use for requests
+  like "scaffold a Docker template", "build a Kubernetes template",
+  "add a coder_parameter for the Git repo URL", "push my template to
+  this Coder deployment", "update the existing aws-linux template to
+  add JetBrains", or "deprecate this template version". Do not use
+  for installing or upgrading Coder itself (use the setup skill),
+  adding a single module to a template that already builds (use the
+  modules skill), or authoring custom Terraform providers unrelated
+  to Coder.
+---
+
+# Templates
+
+Author or update Coder templates. A template is Terraform code that
+Coder runs to build a workspace; one template can back many
+workspaces.
+
+## Source of Truth
+
+Read current upstream docs before applying anything topic-specific:
+
+- <https://coder.com/docs/llms.txt> for the docs index.
+- <https://coder.com/docs/llms-full.txt> only when the index is not
+  enough.
+- <https://registry.coder.com/templates> for the canonical starter
+  templates and their import IDs.
+
+This skill keeps only the authoring workflow, user interaction rules,
+and a few template-specific gotchas.
+
+## User Interaction
+
+The user wants a working workspace, not a Terraform crash course.
+
+- Default to a sensible starter for their infrastructure. Ask only to
+  confirm.
+- Show the planned tree (template name, files, parameters) before
+  writing anything. Ask for one yes/no.
+- Do not ask for cloud credentials in chat. Use the deployment's
+  provisioner authentication; bring it up only when it is missing.
+
+## Workflow
+
+### 1. Pick a starter
+
+Map the user's intent to one of the official starters at
+<https://registry.coder.com/templates>:
+
+- `docker`, `docker-devcontainer`, `docker-rstudio`: container hosts.
+- `kubernetes`, `kubernetes-devcontainer`, `kubernetes-envbox`: K8s
+  clusters.
+- `aws-linux`, `aws-windows`, `aws-devcontainer`: AWS EC2.
+- `gcp-linux`, `gcp-windows`, `gcp-vm-container`, `gcp-devcontainer`:
+  GCP Compute Engine.
+- `azure-linux`, `azure-windows`: Azure VMs.
+- `digitalocean-linux`: DigitalOcean Droplets.
+- `incus`: LXD/Incus containers.
+- `nomad-docker`: Nomad-driven Docker.
+- `scratch`: empty template for advanced authors only.
+
+Scaffold the chosen starter:
+
+```sh
+TEMPLATE_DIR="$(mktemp -d)/$TEMPLATE_NAME"
+coder templates init --id "$STARTER_ID" "$TEMPLATE_DIR"
+```
+
+For an existing template the user wants to edit, pull instead:
+
+```sh
+TEMPLATE_DIR="$(mktemp -d)/$TEMPLATE_NAME"
+coder templates pull "$TEMPLATE_NAME" "$TEMPLATE_DIR"
+```
+
+### 2. Understand the template anatomy
+
+Every Coder template has these moving parts in `main.tf`:
+
+- `terraform` block: required providers (always `coder/coder`, plus
+  the infrastructure provider).
+- `data "coder_workspace" "me"` and `data "coder_workspace_owner"
+  "me"`: workspace context, including `start_count`.
+- `data "coder_parameter"` blocks: user inputs at workspace creation.
+- One `coder_agent` resource: the agent that runs inside the
+  workspace.
+- `coder_app` resources: dashboard buttons for VS Code, JetBrains,
+  Jupyter, and similar apps.
+- Infrastructure resources: `docker_container`,
+  `kubernetes_deployment`, `aws_instance`, etc., depending on the
+  starter.
+- Optional `module` blocks: Coder modules from registry.coder.com.
+
+### 3. Modify
+
+Apply the change the user asked for. Common patterns:
+
+- Add `coder_parameter`s. Set `mutable = true` when the value should
+  be changeable on rebuild. Use `validation` blocks for regex or
+  range enforcement. Use `option` blocks for enums.
+- Add modules from <https://registry.coder.com/modules>. Defer
+  module-specific syntax to the modules skill or to the module
+  README.
+- Persist data with a dedicated volume resource keyed to the
+  workspace owner. Do not rely on container or VM filesystems to
+  survive a rebuild.
+- Set `count = data.coder_workspace.me.start_count` on resources that
+  should be torn down when the workspace stops.
+
+Never store secrets in `terraform.tfvars` or pass them via plain
+`--variable`. Use Coder's secret variables or external provisioners.
+
+### 4. Validate locally
+
+```sh
+cd "$TEMPLATE_DIR"
+terraform init
+terraform fmt
+terraform validate
+```
+
+### 5. Push
+
+First push:
+
+```sh
+coder templates create "$TEMPLATE_NAME" -d "$TEMPLATE_DIR" --yes
+```
+
+Update an existing template:
+
+```sh
+coder templates push "$TEMPLATE_NAME" -d "$TEMPLATE_DIR" --yes
+coder templates versions list "$TEMPLATE_NAME"
+```
+
+Promote the new version with `--activate` on push, or afterwards with
+`coder templates versions promote`.
+
+### 6. Test
+
+Create one workspace from the new version:
+
+```sh
+coder create "$WORKSPACE_NAME" \
+  --template "$TEMPLATE_NAME" \
+  --yes
+```
+
+Pass every required parameter explicitly. For list parameters with no
+sensible value, use `[]`. For enums, use the first option. Ask the
+user only when no default makes sense.
+
+Wait until the agent reaches `ready`, not just until the build
+finishes. If the agent stays in `connecting`, the workspace cannot
+be used.
+
+### 7. Hand off
+
+If this was the user's first template, end with:
+
+- Where the template lives in the dashboard.
+- One workspace name they can run `coder ssh` into.
+- One sentence about updates: edit `main.tf`, then
+  `coder templates push`.
+
+## Common Parameters
+
+Worth knowing because users ask for them often:
+
+- `git_repo_url`: URL to clone on workspace start. Pair with the
+  `git-clone` module.
+- `region`: provider-specific region picker. Pair with the matching
+  `*-region` module.
+- `instance_type` or `node_size`: provider-specific machine size with
+  an `option` list.
+- `dotfiles_uri`: clone a personal dotfiles repo on start. Pair with
+  the `dotfiles` module.
+- `vscode_binary_version`: optional pin for `code-server`.
+
+## Safeguards
+
+- Do not push a template version that has not passed `terraform
+  validate`.
+- Do not archive or delete an active template version without
+  confirming nothing depends on it.
+- Do not pass `--activate` on `coder templates push` if the user is
+  still iterating. They may want to review the new version first.
+- Do not place cloud credentials, OAuth secrets, or workspace tokens
+  in `main.tf` or `terraform.tfvars`. Use secret variables.
+- Do not recommend `scratch` to a user who does not already author
+  Terraform.
+
+## Bundled Resources
+
+No per-template recipes ship with this skill. Defer to each
+template's README on registry.coder.com and to upstream Coder docs
+for provider-specific detail.

skills/templates/agents/openai.yaml

@@ -0,0 +1,6 @@
+  display_name: "Coder Templates"
+  short_description: "Author, edit, push, or version a Coder template"
+  icon_small: "../../../assets/icon.png"
+  icon_large: "../../../assets/logo.png"
+  brand_color: "#000000"
+  default_prompt: "Use $templates to scaffold or update a Coder template."