docs: add Agentic Skill page and update deployment docs

_quarto.yml

@@ -6,6 +6,7 @@ project:
     browser: true
   render:
     - "!chunks/"
+    - "!docs/resources/"
     - "**/*.qmd"
   resources:
     - js/
@@ -129,6 +130,8 @@ website:
 
         - section: "Other"
           contents:
+            - text: "Agentic Skill"
+              href: docs/agentic-skill.qmd
             - text: "sdstudio package"
               href: docs/sdstudio.qmd
             - text: "Architecture"

_variables.yml

@@ -7,5 +7,4 @@ rproject: "[{{< fa brands r-project >}}](https://CRAN.R-project.org/)"
 rstudio_ide: "[RStudio](https://posit.co/products/open-source/rstudio/)"
 vscode: "[VSCode](https://code.visualstudio.com/)"
 positron: "[Positron](https://github.com/posit-dev/positron)"
-huggingface: "[HuggingFace](https://huggingface.co/)"
 url_package: "https://pkg.surveydown.org"

chunks/deploy-alts.qmd

@@ -1,7 +1,7 @@
-You can deploy shiny apps to other hosting services. Here are some guides for several other alternatives:
+You can deploy a surveydown survey to any service that runs R/Shiny. Here are guides for the three platforms we recommend:
 
 - [Posit Connect Cloud](https://docs.posit.co/connect-cloud/how-to/r/shiny-r.html)
-- [Hugging Face](https://huggingface.co/docs/hub/spaces-sdks-docker-shiny#shiny-for-r)
-- [Heroku](https://medium.com/@gracemwendemicheni/deploy-r-shiny-app-to-heroku-31b48fb6eb39)
+- [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker-shiny#shiny-for-r)
+- [Google Cloud Run](https://cloud.google.com/run/docs/deploying)
 
-You can also install [Posit Connect](https://posit.co/products/enterprise/connect/) on your own server, which is the [recommended approach](https://docs.posit.co/shinyapps.io/guide/security_and_compliance/index.html) for remaining compliant with any security protocols your organization requires.
+You can also install [Posit Connect](https://posit.co/products/enterprise/connect/) on your own server, which is the recommended approach for remaining compliant with any security protocols your organization requires.

docs/agentic-skill.qmd

@@ -0,0 +1,129 @@
+---
+title: "Agentic Skill"
+---
+
+The [**surveydown-skill**](https://github.com/surveydown-dev/surveydown-skill) is an agentic skill that teaches an AI coding agent (like [Claude Code](https://www.anthropic.com/claude-code)) how to work with surveydown surveys end to end. Instead of explaining surveydown's syntax, hosts, and settings to your agent every time, you install the skill once and it knows how to author, host, and demo a survey on its own.
+
+We have implemented the skill to become compatible with Claude Code. If you use Claude Code, you can follow the installation instructions and use it right away. If you use other agents, such as CodeX or Gemini, it is also not hard to convert the skill to make it compatible with those agents.
+
+::: {.callout-note}
+The [templates](/templates.qmd) on this website were built with this skill extensively. Many of them have live demos hosted on Hugging Face Spaces and Posit Connect Cloud, and some include walkthrough video recordings, all made possible by the `/surveydown-skill`.
+:::
+
+## Installation
+
+### Claude Code
+
+The skill installs into [Claude Code](https://www.anthropic.com/claude-code) with a single command:
+
+```bash
+npx skills add surveydown-dev/surveydown-skill -a claude-code -g -y
+```
+
+This installs the skill globally to `~/.claude/skills/`, which can be used in any of your new Claude Code sessions. Re-running the same command pulls the latest version.
+
+To uninstall, run this command:
+
+```bash
+npx skills remove surveydown-dev/surveydown-skill -g
+```
+
+### Other agents
+
+If you work with an agent other than Claude Code, such as Codex or Gemini, you can still use this skill. Visit the skill's GitHub repository at [surveydown-dev/surveydown-skill](https://github.com/surveydown-dev/surveydown-skill) and download or clone it to your computer:
+
+```bash
+git clone https://github.com/surveydown-dev/surveydown-skill.git
+```
+
+The skill is just a set of plain Markdown instructions and helper scripts, so it isn't locked to any one agent. Point your agent at the cloned folder and ask it to adapt the skill to your agent's own format (for example, Codex's `AGENTS.md` or Gemini's instruction files). The agent can read the `SKILL.md` and section guides and rewrite them into whatever structure your tool expects.
+
+## Usage
+
+Once installed, invoke the skill by the `/surveydown-skill` command in your agent. By design, your agent will also look through the installed skills on your computer, so even if you do not invoke a skill yourself, your agent will be smart enough to invoke it automatically.
+
+The skill is organized around four things you can do with a survey: **create a survey**, **connect a database**, **deploy online**, and **record a video walkthrough**.
+
+Here are some example prompts that you can give to your agent:
+
+{{< include resources/agentic-skill-prompts.qmd >}}
+
+## Create a survey
+
+The agent scaffolds a new survey, a folder holding a `survey.qmd` (pages, questions, navigation) and an `app.R` (the Shiny app). It offers three starting points:
+
+- **Minimum starter** — the bare default template: two pages, one multiple-choice and one text question, plus a finish page.
+- **Themed showcase** — a richer survey built from one of the 17 official templates that demonstrate a real feature (varied question types, conditional logic, randomization, reactivity, conjoint, custom Plotly/Leaflet questions, and more).
+- **Custom survey** — you describe the topic, questions, and flow, and the agent composes one from the template patterns.
+
+The agent asks *what* survey you want and *where* to create it, scaffolds the files, and leaves it in `mode: preview` (responses saved to a local `preview_data.csv`) so you can preview it immediately with *Run App* in RStudio.
+
+::: {.callout-tip title="Example prompts"}
+- *"Create a new surveydown survey with a few demographic questions."*
+- *"Scaffold the conditional skipping template into a folder called `pilot-survey`."*
+- *"Build a 3-page customer feedback survey: a rating slider, a multiple-choice, and a comment box."*
+:::
+
+## Connect a database
+
+By default a new survey writes responses to a local CSV, which is fine for testing but lost when the app restarts. This section switches the survey to a durable **PostgreSQL** database (the docs recommend [Supabase](https://supabase.com) as a free option) so responses are collected for real.
+
+The agent locates your survey, asks whether you already have database credentials, and if not, walks you through creating a free Supabase project. It then writes the six `SD_*` credentials into a git-ignored `.env` file (via `sd_db_config()`), confirms `app.R` calls `sd_db_connect()`, flips the survey's setting to `mode: database`, and verifies the connection. Credentials stay in the local `.env` and are never committed or pasted into the chat.
+
+::: {.callout-tip title="Example prompts"}
+- *"Connect my survey to a database so responses are saved durably."*
+- *"I have a Supabase project already, wire `pilot-survey` up to it."*
+- *"Switch this survey to database mode and check that the connection works."*
+:::
+
+## Deploy online
+
+A surveydown survey is a live R/Shiny app, so it needs a host that runs R, not a static host like GitHub Pages or Netlify. The skill supports the three valid hosts, each as its own deployment technique. The tooling treats your survey folder as the source of truth: it *generates* host-specific packaging and pushes it, but never modifies your survey.
+
+For every host the agent always confirms two survey settings first, the data **mode** (local / preview / database) and whether to **use cookies** (per-browser resume), then handles the packaging and push for you.
+
+### Hugging Face Spaces
+
+Deploys the survey as a Docker Space served on a clean URL (`https://<owner>-<space>.hf.space`). The free tier runs roughly **3 surveys at once**. The agent creates the Space if needed, uploads the survey, and for a database-mode survey syncs the `SD_*` credentials to the Space's Secrets automatically. It can also wait for the build and report the live URL.
+
+::: {.callout-tip title="Example prompts"}
+- *"Deploy this survey to Hugging Face Spaces."*
+- *"Push `pilot-survey` to Hugging Face as `myname/pilot` and wait until it's running."*
+:::
+
+### Posit Connect Cloud
+
+Publishes the survey via `rsconnect` to Posit's managed R/Shiny host (the successor to the retiring shinyapps.io), served at `https://<account>-<slug>.share.connect.posit.cloud`. The free plan allows **5 applications**. The agent sets the display title and custom URL slug for you, ships database credentials as content secrets, and tunes the survey for fast cold starts.
+
+::: {.callout-tip title="Example prompts"}
+- *"Deploy this survey to Posit Connect Cloud with the title 'Customer Feedback'."*
+- *"Publish `pilot-survey` to Connect Cloud at the slug `pilot`."*
+:::
+
+### Google Cloud Run
+
+Deploys each survey as its own Cloud Run service with **no limit on the number of surveys**. Services scale to zero when idle, so an unused survey costs about $0, but a **billing card is required** on the project. The agent shows the billing caveat once, builds and deploys the container, stores database credentials in Google Secret Manager, and prints the live URL plus a dashboard link.
+
+::: {.callout-tip title="Example prompts"}
+- *"Deploy this survey to Google Cloud Run."*
+- *"Put `pilot-survey` on Cloud Run in `us-central1` with 2Gi of memory."*
+:::
+
+::: {.callout-note}
+Not sure which host to pick? Just say you want to deploy a survey online and the agent will lay out the three options (and their free-tier limits) before choosing.
+:::
+
+## Record a video walkthrough
+
+When a survey can't be hosted online (for example a free tier is full) but still needs a demo people can watch, the skill records one locally. It renders the survey, opens a **visible** Chrome window, drives a cursor through every question answering each one, and screen-captures the run to an `.mp4` next to the survey.
+
+This reuses surveydown's own browser-automation test helpers as the interaction engine, so every question type is driven correctly. It is currently **macOS only** and needs Chrome, `ffmpeg`, and Screen Recording permission for your terminal. The section also documents how to publish the resulting video in a GitHub README.
+
+::: {.callout-tip title="Example prompts"}
+- *"Record a video walkthrough of the reactive drilldown template."*
+- *"Make an mp4 demo of `pilot-survey` answering every question."*
+:::
+
+::: {.callout-tip}
+The full skill, including each section's guide and tooling, lives on GitHub at [surveydown-dev/surveydown-skill](https://github.com/surveydown-dev/surveydown-skill).
+:::

docs/deployment.qmd

@@ -11,33 +11,24 @@ Before deploying your survey, make sure everything is working locally. You shoul
 
 With these steps completed, you are ready to deploy your survey online.
 
-## Deploying to shinyapps.io
+## Using a skill
 
-Deploying your survey is pretty much the same as deploying any other Shiny app. We recommend using {{< var shinyapps >}} to host your survey as it is designed to work with Shiny Apps, but you can also use [other hosting services](#deploying-to-other-hosting-services).
+If you are familiar with AI or agentive engineering, you can use this skill to expedite your server deployment. Simply install and invoke `/surveydown-skill` in your AI agent, and use it to deploy your survel. Visit the [surveydown agentic skill](agentic-skill.html) page for more information.
 
-::: {.callout-note}
-
-You may have deployed other Quarto documents on [Quarto Pub](https://quartopub.com) before, but this site is only for static websites, so you **SHOULD NOT** use Quarto Pub for your survey deployment.
-
-:::
+## Deploy by hand
 
-To start using {{< var shinyapps >}}, you'll need to create an account and follow the basic instructions to set up your sub-domain and authorize your IDE. See more information [here](https://docs.posit.co/shinyapps.io/guide/getting_started/).
+A surveydown survey is a live {{< var shiny >}} application, not a static website, so it must be hosted on a service that can run R.
 
-Once you have your account and sub-domain ready, make sure you have the [rsconnect](https://rstudio.github.io/rsconnect/) package installed. You should have done this while authorizing your IDE, but in case you didn't, you can install it with:
-
-```{r}
-install.packages('rsconnect')
-```
+::: {.callout-note}
 
-Then to deploy your survey, run:
+You may have deployed other Quarto documents on [Quarto Pub](https://quartopub.com) before, but this service is only for static websites, so you **SHOULD NOT** use Quarto Pub (or other static hosts like GitHub Pages or Netlify) for your survey deployment.
 
-```{r}
-# Define your app name with the appName parameter
-rsconnect::deployApp(appName = "my_survey")
-```
+:::
 
-That's it! Now you should have your survey site deployed on **shinyapps.io**. Congratulations! 🎉
+We recommend three hosting platforms, all of which the agentic skill can deploy to automatically:
 
-## Deploying to Other Hosting Services
+- **[Posit Connect Cloud](https://connect.posit.cloud/)** — Posit's managed home for R/Shiny apps and the recommended successor to the retiring shinyapps.io. The free plan allows **5 applications**, and you publish straight from the [rsconnect](https://rstudio.github.io/rsconnect/) package.
+- **[Hugging Face Spaces](https://huggingface.co/)** — runs your survey as a Docker Space on a clean URL. The free tier can run roughly **3 surveys** at once.
+- **[Google Cloud Run](https://cloud.google.com/run)** — runs each survey as its own container with **no limit** on the number of surveys. Idle services scale to zero (≈ $0 when unused), but a billing card is required on the project.
 
-{{< include ../chunks/deploy-alts.qmd >}}
+You can also install [Posit Connect](https://posit.co/products/enterprise/connect/) on your own server, which is the recommended approach for remaining compliant with any security protocols your organization requires.

docs/getting-started.qmd

@@ -94,6 +94,10 @@ surveydown::sd_create_survey(
 
 The default is `template = "default"`, but you can specify other templates. See the [Templates](../templates.html) page for an overview of all currently available templates.
 
+::: {.callout-tip}
+Prefer to let an AI agent do it? The [`/surveydown-skill`](agentic-skill.html#create-a-survey) can scaffold a survey from any template (or compose a custom one you describe) for you.
+:::
+
 ## 3. Add survey content
 
 Survey content is edited in the **survey.qmd** file. See the [Basic Components](basic-components.qmd) page for more details on how to add more content to a surveydown survey. At a minimum, you can add pages and questions like this:
@@ -159,10 +163,14 @@ In the `server()` function in the **app.R** file, add rich functionality to your
 
 Setup your database connection using the `sd_db_config()` function. Once your configuration credentials are created (they get saved in a `.env` file), make a connection to your database using the `sd_db_connect()` function in the global settings at the top of the **app.R** file. To run the survey locally without storing data to a database, set `mode: preview` in your `survey.qmd` YAML. See the [Storing Data](storing-data.qmd) page for more details on the available modes.
 
+::: {.callout-tip}
+The [`/surveydown-skill`](agentic-skill.html#connect-a-database) can set up this database connection for you, including creating a free Supabase project and writing the `.env`.
+:::
+
 ## 6. Locally preview
 
 Preview your survey by clicking the "Run App" button in RStudio or in your R console running the `runApp()` command.
 
 ## 7. Deploy
 
-Deploy your survey by hosting it on your favorite server, like {{< var shinyapps >}}, {{< var huggingface >}}, [Posit Connect Cloud](https://connect.posit.cloud/), [Heroku](https://www.heroku.com/), etc. See the [Deployment](deployment.html) page for more details.
+Deploy your survey on a host that runs R/Shiny: [Posit Connect Cloud](https://connect.posit.cloud/), [Hugging Face Spaces](https://huggingface.co/), or [Google Cloud Run](https://cloud.google.com/run). See the [Deployment](deployment.html) page for details, or let the [`/surveydown-skill`](agentic-skill.html#deploy-online) deploy it for you.