diff --git a/skills/modules/SKILL.md b/skills/modules/SKILL.md new file mode 100644 index 0000000..f7d046b --- /dev/null +++ b/skills/modules/SKILL.md @@ -0,0 +1,158 @@ +--- +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: + +- for the docs index. +- 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 . +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//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" --yes +coder templates versions list "$TEMPLATE_NAME" +``` + +The `versions list` output confirms the new version is registered. +If the user wants the new version to become active automatically, +add `--activate` to `push`; otherwise leave the existing active +version alone. + +## Common Modules + +Curated shortlist of the most-requested categories. Full catalogue at +. + +- 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. diff --git a/skills/modules/agents/openai.yaml b/skills/modules/agents/openai.yaml new file mode 100644 index 0000000..3911a0e --- /dev/null +++ b/skills/modules/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + 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." diff --git a/skills/templates/SKILL.md b/skills/templates/SKILL.md new file mode 100644 index 0000000..9282ab1 --- /dev/null +++ b/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: + +- for the docs index. +- only when the index is not + enough. +- 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 +: + +- `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 . 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. diff --git a/skills/templates/agents/openai.yaml b/skills/templates/agents/openai.yaml new file mode 100644 index 0000000..2039b23 --- /dev/null +++ b/skills/templates/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + 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."