# Surveycto

> >

- **Type:** Skill
- **Install:** `agentstack add skill-surveycto-surveycto-agent-skill-surveycto-agent-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [surveycto](https://agentstack.voostack.com/s/surveycto)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [surveycto](https://github.com/surveycto)
- **Source:** https://github.com/surveycto/surveycto-agent-skill

## Install

```sh
agentstack add skill-surveycto-surveycto-agent-skill-surveycto-agent-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SurveyCTO Form, Plug-in, and Dataset Authoring

**Skill version: 1.0.0-beta.7.** SurveyCTO MCP tool responses publish the current skill-version policy: `start_xlsform_session` returns a `skill_advisory`, and `get_surveycto_mcp_capabilities` returns `intended_skill.versions`. When you see one, compare it against this skill's version above (semantic-version ordering, pre-release aware) and act: if this version is below the response's `deprecated_below_version`, warn the user that their installed SurveyCTO skill is deprecated and should be updated now from the response's `download_url`; if it is below `recommended_min_version`, mention a newer version is available and offer to help update. Say nothing about versions when this skill is current, and raise it at most once per conversation. Skills do not auto-update, so this is the only update signal users get. See [`references/mcp.md`](references/mcp.md) for the exact comparison rules.

SurveyCTO is a mobile data collection platform built on the XLSForm and ODK standards, with platform-specific extensions and divergences. This skill provides SurveyCTO domain expertise for the four definition file types you may encounter:

1. **XLSForm form definitions** (`.xlsx`) — survey instruments
2. **Dataset definitions** (`.xml`) — server dataset structure and publishing rules
3. **Data Explorer workbook definitions** (`.xlsx`) — monitoring dashboards
4. **Field plug-in bundles** (`.fieldplugin.zip`) — custom HTML/CSS/JS that takes over rendering of a single field

For a high-level orientation, read [`references/overview.md`](references/overview.md) first.

## Identifying SurveyCTO files

| File type | Format | How to recognize |
| --- | --- | --- |
| XLSForm | `.xlsx` | Worksheets named `survey`, `choices`, `settings` |
| Dataset definition | `.xml` | Root element `` with `` child |
| Data Explorer workbook | `.xlsx` | Worksheets named `summaries`, `settings`, `global_filters`, `global_exclusions` |
| Field plug-in bundle | `.fieldplugin.zip` | Zip with `manifest.json`, `template.html`, `style.css`, `script.js` at the root; referenced from a field's `appearance` as `custom-` |

## XLSForm starting point

Before choosing tools, before writing code, before reading further:

- **New form** → Step 1 is ALWAYS a literal file copy from `assets/xlsform-template.xlsx` to the output path (for example, `cp assets/xlsform-template.xlsx ` in a Unix shell). The template is bundled with this skill at `assets/xlsform-template.xlsx` (resolve relative to the skill's root directory). Then proceed with the tooling rules below, uploading or opening the *copied* file.
- **Existing form** → load the user's workbook as-is; do not regenerate it.
- **NEVER** create an `.xlsx` from scratch. This rule applies regardless of which tools are available — it is not an MCP-only requirement and there is no fallback exemption. See [Anti-pattern: building the workbook from scratch](#anti-pattern-building-the-workbook-from-scratch) for the specific tools and idioms to avoid.

This rule is the most commonly-skipped step in this skill. If you are about to call `openpyxl.Workbook()`, `pandas.ExcelWriter` against a new path, `libreoffice --headless` to create a new file, or any code that writes XLSX bytes from scratch, stop and copy the template instead.

## Tools you may have available

This skill is fully usable with no special tools — you have enough SurveyCTO knowledge embedded here and at the live documentation links to advise the user, describe edits in prose, and reason about forms. If additional tools are present, use them in the priority order below.

**Tool-selection rule for XLSForm work:** if the SurveyCTO MCP server tools are connected, you MUST use them for nontrivial XLSForm inspection, editing, validation, and export. Do not choose generic `bash`, `python`, `openpyxl`, LibreOffice, or spreadsheet tooling as the primary authoring path when SurveyCTO MCP tools are available. Generic tooling is only a fallback if MCP tools are unavailable, disconnected, or return an unrecoverable error.

### SurveyCTO MCP server (preferred when available)

The **SurveyCTO MCP server** is a public, no-auth MCP server with capabilities built for this domain (XLSForm session inspect/edit/export and SurveyCTO knowledge-base search). Endpoint: `https://assistant-be.surveycto.net/mcp` (Streamable HTTP, stateless, no auth). If the server isn't connected when the user is editing XLSForms or asking factual SurveyCTO questions, mention it exists and offer to help install it; don't insist.

If the MCP tools are connected but XLSForm uploads or downloads are failing with network errors, see [`references/install.md`](references/install.md) for details to guide the user. Claude Cowork in particular requires explicit network-egress configuration, and the symptom is usually a sandbox that's already cached the "blocked" state and needs a fresh chat after the setting is changed.

Before using any SurveyCTO MCP tool, read [`references/mcp.md`](references/mcp.md). It is mandatory for MCP usage; do not guess tool signatures, patch semantics, concurrency rules, error handling, or limits from this abbreviated overview. Read its "Preflight" section before your first XLSForm session in a chat; if the preflight fails, fix egress before proceeding.

#### Recommended workflow

1. **Before any MCP tool call**: read [`references/mcp.md`](references/mcp.md), then call `get_surveycto_mcp_capabilities` when unsure to learn the current tool list and primer topics. If the work involves XLSForms, you must also have read [`references/xlsform.md`](references/xlsform.md) first — see [Prerequisite: read the XLSForm reference](#prerequisite-read-the-xlsform-reference).
2. **Factual SurveyCTO questions**: `kb_search` → quote the returned URLs in your answer.
3. **Create a new XLSForm**: follow the [Workflow: create a new form](#workflow-create-a-new-form) below — it is the canonical sequence and enforces the template-first rule.
4. **Add, update, or verify form-label translations**: see [Workflow: translate form labels](#workflow-translate-form-labels) below, which points to [`references/translation.md`](references/translation.md).
5. **Inspect or edit an existing XLSForm**:
   1. Load the user's workbook (do not regenerate). `start_xlsform_session` for a fresh upload, or `get_xlsform_summary` if resuming an existing `session_id`.
   2. **Take a starting inventory from `form_summary` before patching or paging rows.** Note existing column names, choice lists (especially reusable ones like `yesno`), settings values, and any warnings. Do not assume spellings or values from memory.
   3. `xls_get_rows` / `xls_get_row` to inspect rows you intend to touch. Parallel calls are fine.
   4. `xls_apply_patches` — **batch all related edits into one call**. Use `validate_only=true` on the full batch for risky changes. Update settings via `change_setting`, not `edit_row`. For large batches set `return_form_summary=false` and `include_details=false`, and trust a successful response — verify once at the end of the build, not after each batch (see [`references/mcp.md`](references/mcp.md) → *Trust patch success; verify once at the end*).
   5. `export_xlsform` as soon as a form is in a deliverable state — **especially when more forms remain in the same chat**, so the user has each finished file in hand before you move on. Hand the file, `download_url`, or resource link to the user. Avoid `format="base64"` for real workbooks. **If the form references any `custom-` appearances, remind the user to attach the matching `.fieldplugin.zip` files in the SurveyCTO console at upload time** — this skill and the MCP server only edit local files.
   6. Usually leave the session open until TTL expiry; only call `end_xlsform_session` for explicit cleanup.

### Generic spreadsheet/xlsx tooling

Use generic xlsx, Excel, Python/openpyxl, LibreOffice, or spreadsheet tools only when SurveyCTO MCP tools are not available or have failed in a way you cannot recover from. These tools can read and edit `.xlsx` files cell by cell, but they do not understand SurveyCTO form semantics, MCP session concurrency, or server-side formula recalculation. If you must use generic tooling, explicitly tell the user you are falling back because the MCP tools are unavailable or failed, then follow the editing rules in the *Working with XLSForm .xlsx files* section below.

### Web fetch

If you can fetch URLs, the most authoritative live sources are:

- [docs.surveycto.com](https://docs.surveycto.com) — product documentation
- [support.surveycto.com](https://support.surveycto.com) — Support Center articles
- [www.surveycto.com](https://www.surveycto.com) — site/marketing content

Prefer these over the bundled primers when verifying current product behavior.

### No file tooling at all

You can still help: describe edits in prose ("add a row to the `survey` worksheet with `type=integer`, `name=age`, `label=Age in years`, `constraint=. >= 0 and . = 0 and . ` in a Unix shell; resolve `assets/` relative to the skill's root directory). Do not regenerate the file.
2. If MCP tools are available, pass the copied file to `start_xlsform_session` via the upload URL flow and apply edits with `xls_apply_patches`.
3. If MCP tools are unavailable, open the copied file and edit it in place — add your content into the existing worksheets.

**Never do any of the following:**
- Do NOT create a new `.xlsx` file from scratch.
- Do NOT create new worksheets and build the structure yourself.
- Do NOT delete and recreate worksheets from the template.
- Do NOT "rebuild" the form "properly" — the template IS the proper starting point.

#### Anti-pattern: building the workbook from scratch

Never run any of these for a new form:

- `from openpyxl import Workbook; wb = Workbook()` (or any other code that constructs a fresh workbook object and adds `survey`/`choices`/`settings` sheets to it)
- `pandas.ExcelWriter()` or `pandas.DataFrame.to_excel()` against a path that doesn't already contain the template's contents
- `libreoffice --headless --convert-to xlsx` starting from a non-template source
- Writing XLSX bytes directly (zipfile + `xl/worksheets/*.xml`)

These produce a technically valid but unusable form: no conditional formatting, no `help-survey`/`help-choices`/`help-settings` sheets, no `caseid` row, no hidden audit calculations, no reusable `yesno` choice list, no auto-updating `version` formula, and no color-coded row styling. The user has to redo the work in Excel by hand. Copy `assets/xlsform-template.xlsx` instead — this is true even when MCP tools are unavailable and you fall back to `openpyxl` for editing. The fallback is for *editing*, not for *creation from scratch*.

#### Workflow: create a new form

Follow these steps in order:

1. Make a literal file copy from `assets/xlsform-template.xlsx` to the output path. Do not create a new workbook object, generate worksheets, or convert from another source.
2. **Read [`references/xlsform.md`](references/xlsform.md) before designing any form content.** This is mandatory — not a lookup to do if confused later. Column conventions, multi-language structure, group/repeat rules, and expression syntax all have SurveyCTO-specific details that differ from general ODK knowledge. See [Prerequisite: read the XLSForm reference](#prerequisite-read-the-xlsform-reference).
3. If MCP tools are available, read [`references/mcp.md`](references/mcp.md), then upload the copied file via `start_xlsform_session`. If MCP is unavailable, open the copied workbook directly with the best available spreadsheet/XLSX tooling.
4. Read the starting structure fully before editing. With MCP, use the returned `form_summary`; without MCP, inspect the workbook sheets directly. Note next append location, exact column names already present, existing reusable choice lists, and current settings values.
5. Apply related edits in one batch. With MCP, use a single `xls_apply_patches` call and `change_setting` for `form_id`, `form_title`, `default_language`, and/or `instance_name` (the only patch-addressable settings keys); without MCP, write directly into the copied workbook's existing worksheets.
6. Export or save the result. With MCP, use `export_xlsform` and hand the `download_url` to the user. Remind the user to attach any required `.fieldplugin.zip` files in the SurveyCTO console at upload time.

**Why the template is mandatory:** It contains conditional formatting rules, help worksheets, column headers, starter metadata fields, formula-based versioning, and pre-formatted rows that cannot be reliably recreated programmatically. Skipping the template produces files that are technically valid but painful for humans to edit in Excel.

The template provides:
- **survey** worksheet with correct column headers and starter metadata fields, including hidden audit calculations and a `caseid` row
- **choices** worksheet with headers and a `yesno` choice list
- **settings** worksheet with headers and an auto-updating `version` formula
- **help-survey**, **help-choices**, **help-settings** worksheets with reference documentation
- Conditional formatting rules that color-code rows by field type

**Template starter content is a helpful starting point, not a fixed requirement.** The starter rows (metadata fields, `caseid`, audit calculations) and the `yesno` choice list are included as conveniences for common cases. Keep standard metadata and audit rows by default because they are generally useful and not user-facing clutter; remove or replace them only when the source form or user request gives you a reason. Treat `caseid` as context-dependent: keep it for case-management work, but delete it when it would confuse a non-case draft. The `yesno` choice list is just an example choice list — drop or replace it freely when the form uses a different yes/no convention or no row references it. What's worth preserving is the *tooling*: the auto-updating `version` formula, the conditional formatting, the help worksheets, and the column-header structure. When you change starter content (e.g., rewrite a choice's `value`), be consistent — also update everything that references it.

#### Workflow: translate form labels

Adding a language, updating translations after the source changes, or verifying existing translations is its own workflow. **Read [`references/translation.md`](references/translation.md) before starting** — don't improvise from the column-convention sketch in [`references/xlsform.md`](references/xlsform.md).

#### Workflow: convert a form from another platform

Converting a form definition exported from another data collection platform — KoboToolbox or ODK (XLSForm `.xlsx`), CommCare (XForms `.xml`), Qualtrics (`.qsf` JSON), or anything else — into a SurveyCTO XLSForm is its own workflow. Note that the conversion is **best-effort and agent-driven**, and the SurveyCTO MCP XLSForm tools work **only on SurveyCTO-shaped XLSForms** (do not point them at the source file). **Read [`references/form-conversion.md`](references/form-conversion.md) before starting**, then load the matching platform-specific reference (`form-conversion-qualtrics.md`, `form-conversion-kobo.md`, `form-conversion-odk.md`, `form-conversion-commcare.md`) if one exists for the source platform; for platforms without a dedicated reference, the base workflow still applies.

### Editing rules (apply to every path)

- **Preserve all existing worksheets** — including `help-survey`, `help-choices`, `help-settings` and any other sheets present in the template or existing form.
- **Preserve existing formatting** — do not clear or overwrite conditional formatting, column widths, or cell styles.
- **Only write to rows that contain or will contain data.** Don't touch unused rows below your content; don't write empty strings or `None` to clear already-empty cells.
- **Append new rows after existing data.** Do not assume a fixed starter-row count — the template ships wi

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [surveycto](https://github.com/surveycto)
- **Source:** [surveycto/surveycto-agent-skill](https://github.com/surveycto/surveycto-agent-skill)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-surveycto-surveycto-agent-skill-surveycto-agent-skill
- Seller: https://agentstack.voostack.com/s/surveycto
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.