Surveycto

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, globalfilters, globalexclusions | | 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:
6. 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.
7. 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.
8. xls_get_rows / xls_get_row to inspect rows you intend to touch. Parallel calls are fine.
9. 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).
10. 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.
11. 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 — product documentation
• support.surveycto.com — Support Center articles
• 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.

1. 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.
2. 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
• Source: surveycto/surveycto-agent-skill
• License: Apache-2.0

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