SurveyCTO Agent Skill

An Agent Skill that gives AI agents SurveyCTO domain expertise: designing, editing, and debugging SurveyCTO forms (XLSForm .xlsx files), server datasets (XML definitions), Data Explorer workbook definitions, and field plug-ins (.fieldplugin.zip bundles).

Use this skill in an agent host such as Claude or OpenAI Codex that supports skills, code execution, and file access. It is also best paired with the SurveyCTO MCP server for built-for-purpose XLSForm file operations and live knowledge-base search; without those tools the skill still imparts the expertise the agent needs, falling back to generic xlsx tooling, web fetches of the live docs, or conversational guidance.

Please note: The SurveyCTO AI Agent Skill is currently in public beta. We are sharing this skill to gather feedback from our community, but please be aware of the following:

• The full form-editing workflow requires an agent host with skills, code execution, file access, and an MCP connection. See the installation steps below for Claude and Codex.
• While this skill is designed to assist with form design and field plug-in development, it can make mistakes. Always review, test, and validate any code or assets generated by the AI before deploying them to a production environment.
• We highly encourage you to review your organization’s compliance, data security, and AI usage policies prior to using this skill.
• As the open-source home of this skill, we encourage you to explore, fork, and test it. We value your feedback and bug reports to help us improve the skill for everyone.

Where to download

Latest stable release (always up to date):

surveycto-skill.zip

This URL always points to the most recent release. You can also browse all releases on the releases page. The same zip is used for every host below. Pair it with the SurveyCTO MCP server at https://assistant-be.surveycto.net/mcp for the best experience — the per-host steps below cover both pieces.

How to install

For the best experience, install both the skill and the SurveyCTO MCP server in your agent host. The skill works on its own, but the MCP server adds purpose-built XLSForm tools and live knowledge-base search.

For the full install guide — including detailed network-egress setup and troubleshooting — see references/install.md. The per-host steps below are a shorter summary.

Claude (formerly Cowork)

Cowork is now part of Claude, so there is no separate Cowork tab to select in the integrated interface. See the illustrated Claude walkthrough for screenshots and details.

1. Download surveycto-skill.zip.

2. Open Customize → Skills → Add → Upload skill. Select the zip, review the preview, and click Upload to start the security scan. Follow any scan prompts, then confirm surveycto is enabled under Yours.

3. Open Customize → Connectors → Add → Add custom connector.

4. Enter SurveyCTO tools as the name and https://assistant-be.surveycto.net/mcp as the MCP server URL. Click Continue, keep No sign-in, then click Add. On the connector page, click Connect if shown.

5. Open the connector’s Tool permissions. Choose Always allow to approve its tool calls automatically, or Needs approval to approve calls individually. Other kinds of actions may still require approval.

6. In Settings → Capabilities, enable Cloud code execution and file creation and Allow network egress. With Package managers only selected, add *.surveycto.net under Additional allowed domains. If All domains is already selected, no additional domain is needed.

Start a new chat, open + → Connectors, and ensure SurveyCTO tools is enabled for that conversation. Run the setup check to verify the skill and XLSForm uploads and downloads. Labels and availability can vary by account and rollout; the full guide covers alternate menus and organization restrictions.

OpenAI Codex

Extract the downloaded zip into ~/.agents/skills/surveycto. On macOS or Linux, run this from the directory containing the zip:

mkdir -p ~/.agents/skills/surveycto
unzip surveycto-skill.zip -d ~/.agents/skills/surveycto

Confirm ~/.agents/skills/surveycto/SKILL.md exists. Codex discovers skills in this directory; restart the app or session if it does not appear. The desktop app also has a Skills view.

For MCP, open Settings → MCP servers → Add server, use surveycto as the name, select Streamable HTTP, and enter https://assistant-be.surveycto.net/mcp as the URL. No authentication is required. Save and restart when prompted. Alternatively, use the CLI:

codex mcp add surveycto --url https://assistant-be.surveycto.net/mcp

Approve tool calls and any file-transfer network requests according to your policy. Codex’s command sandbox can restrict uploads and downloads independently of the MCP connection. See the full Codex guide for Windows paths, invocation, and verification.

Other Agent Skills-compatible tools

This skill follows the Agent Skills open standard. For tools like Claude Code, Cursor, VS Code Copilot, Gemini CLI, Roo Code, and others, consult the host’s documentation for installing skills and MCP servers. In general:

• Skill: extract surveycto-skill.zip into the host’s skills directory (often ~/./skills/surveycto or similar).

• MCP server: register https://assistant-be.surveycto.net/mcp (Streamable HTTP, no auth). For stdio-only clients, wrap it with mcp-remote:

  {
    "surveycto": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://assistant-be.surveycto.net/mcp"]
    }
  }
  

How to use

In principle, the skill activates automatically when you:

• Ask about SurveyCTO, XLSForm, or survey form design
• Work with .xlsx files containing survey/choices/settings worksheets
• Work with XML files containing `` elements
• Mention data collection forms, skip logic, constraints, or choice lists
• Ask about field plug-ins

In practice, automatic activation is unreliable — agents often answer SurveyCTO questions from their generic training data without ever loading the skill, which defeats the point. To guarantee the skill is used, invoke it explicitly:

• In the Codex CLI or IDE extension, invoke the skill with $surveycto.
• In any host, prefix your request with something like “Using the SurveyCTO skill, …” or “Load the SurveyCTO skill and then …”.

After sending the request, check the agent’s response (or its tool-use trace) to confirm it actually loaded the skill — most hosts show a “Skill: surveycto” badge, a skill tool call, or a similar indicator. If you don’t see one, the agent is winging it, and the answer is likely to disappoint. Re-prompt explicitly until the skill is loaded.

What’s included

The files in references/ split into two categories:

• Primers (overview.md, xlsform.md, expressions.md, datasets-xml.md, data-explorer.md, field-plugins.md) are the canonical bundled SurveyCTO knowledge set. The XLSForm, expressions, dataset, and Data Explorer primers are also vendored by the SurveyCTO MCP server and served via its get_surveycto_primer tool, so callers without the skill installed can still retrieve them; the field-plug-in primer is not yet vendored on the server (see Syncing primers to the MCP server).
• MCP server reference (mcp.md) documents the SurveyCTO MCP server itself — its tool surface, patch semantics, concurrency contract, error codes, and limits. It is required reading for the agent before any MCP tool call. It is not vendored back to the MCP server (it would be circular) and is maintained separately (see Maintaining the MCP server reference).

SurveyCTO MCP server

The skill recommends the SurveyCTO MCP server (public, no auth, Streamable HTTP) when it’s available. It provides:

• XLSForm file tools — start_xlsform_session, get_xlsform_summary, xls_get_rows, xls_get_row, xls_apply_patches, export_xlsform, end_xlsform_session. SurveyCTO-aware parsing, atomic patches with conflict detection, common column-alias normalization, formula recalculation on export, and formatting preservation. Explicit session cleanup is available but normal workflows can let sessions expire by TTL.
• Knowledge-base tools — kb_search over indexed SurveyCTO docs/support content; get_surveycto_primer for these primers.
• Discovery — get_surveycto_mcp_capabilities for the canonical tool list, recommended workflows, concurrency contract, and primer topic inventory.

Endpoint: https://assistant-be.surveycto.net/mcp

stdio-only clients can wrap with mcp-remote:

{
  "surveycto": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://assistant-be.surveycto.net/mcp"]
  }
}

The full integration reference — tool surface, xls_apply_patches semantics, concurrency contract, error codes, and limits — lives in references/mcp.md. SKILL.md keeps only the workflow that uses these tools.

Development

This repo uses a develop → main branching model:

• develop — active development; pushes here produce a surveycto-skill-dev.zip build artifact (GitHub Actions workflow artifact, not committed)
• main — stable releases; pushes here create a GitHub Release with surveycto-skill.zip attached (built and published by the release workflow; not committed to the repo)

Versioning

The skill version lives in two places that must be kept in sync:

1. The metadata.version field in SKILL.md frontmatter — read by the release workflow and by skill hosts.
2. A “Skill version” line near the top of SKILL.md’s body — visible to the agent at runtime (agents do not see frontmatter), so the agent can answer “which version am I running?” honestly.

metadata:
  author: Dobility, Inc. (SurveyCTO)
  version: "1.0.0-beta"

...
**Skill version: 1.0.0-beta.** - ...

Before merging develop into main, bump the version in both places first. The release workflow reads the frontmatter to create the Git tag and GitHub Release name (e.g., "1.0.0-beta" → tag v1.0.0-beta, release v1.0.0-beta); the body line is what the agent reports to users.

Use semantic versioning:

• Pre-release (1.0.0-beta, 1.0.0-beta.2, 1.0.0-rc.1): Public beta and release-candidate builds before the first stable 1.0.0
• Patch (1.0.0 → 1.0.1): Fix incorrect information, typos, or clarify existing guidance
• Minor (1.0.0 → 1.1.0): Add new content (new reference sections, new patterns, template updates)
• Major (1.x → 2.0.0): Structural changes that may affect how agents use the skill

Broadcasting versions through the MCP server

Skills do not auto-update and there is no separate update channel, so the SurveyCTO MCP server announces the current skill-version policy to connected agents (it serves the recommended and deprecated versions, and agents prompt users to update). The editorial half of that policy lives in version-policy.source.json:

• deprecated_below_version: versions below this are announced as deprecated. Raise it only when an older release becomes genuinely problematic.
• recommended_min_version (optional): defaults to the released version, so each release recommends itself. Pin it only to recommend an older floor than the latest.
• latest_updates: a short, newest-first summary shown to agents.

Update version-policy.source.json in the same PR that bumps the version when the deprecation floor or the update summary should change. On release, scripts/build_version_policy.py derives latest_version from the tag, validates that deprecated_below ≤ recommended_min ≤ latest, and publishes version-policy.json as a release asset; the MCP server bakes that asset into its next image. latest_version is never hand-edited.

Building the zip locally

The release zip is produced by GitHub Actions on push to main (and a matching dev zip is produced as a workflow artifact on push to develop); neither is committed to the repo. To smoke-test a build locally, mirror what the workflows do — include only what’s part of the skill bundle:

rm -f surveycto-skill.zip
zip -r surveycto-skill.zip SKILL.md references assets \
  -x '**/.DS_Store' -x '**/Thumbs.db' \
  -x '**/__pycache__/*' -x '**/*.pyc' -x '**/*.pyo'

The skill bundle is exactly SKILL.md + references/ + assets/; everything else in the repo (this README, LICENSE, AGENTS.md, .github/, .kilo/, planning/, scripts/, tests/, etc.) is repo tooling and stays out of the zip by virtue of not being included.

Maintaining XLSX assets

The bundled XLSForm template is edited in Excel, but Excel may write machine-local package metadata into the .xlsx archive, including the last editor’s name and an absolute local filesystem path. After any edit to assets/xlsform-template.xlsx or another public XLSX asset, run:

python3 scripts/sanitize_xlsx_assets.py
python3 tests/validate_xlsx_assets.py

The sanitizer rewrites workbook package metadata to remove local author and path leaks. The validator checks for those leaks and also asserts the XLSForm template invariants that are easy for an Excel round-trip to silently damage: sheet structure, survey / choices / settings headers, survey conditional-formatting coverage, and the settings!C2 version formula.

The validation script requires openpyxl; CI installs the pinned version with python3 -m pip install openpyxl==3.1.5 before running it.

Making changes

1. Create a feature branch from develop
2. Make your changes
3. Open a PR to develop
4. Once merged and tested, bump the version in SKILL.md and merge develop into main to create a release

Maintaining references/

references/ contains six primers (maintained as described below) plus the MCP server reference mcp.md (maintained from a separate source — see Maintaining the MCP server reference). The primers themselves split into two maintenance models depending on whether the public documentation actually covers the topic.

Docs-derived primers (regenerated periodically)

overview.md, xlsform.md, expressions.md, and field-plugins.md cover material that is documented in public SurveyCTO sources. The first three are primarily derived from docs.surveycto.com; field-plugins.md is primarily derived from the SurveyCTO field-plug-in-resources GitHub developer docs, with product docs and support articles as secondary sources. They are intended to be refreshed periodically from a careful read of the live sources as the underlying product changes and as more capable AI agents become available. The prompts below are designed for a very capable AI agent with web-fetch and file-write capabilities — paste one into a fresh session, let it run, and replace the corresponding materials with the result. (The initial versions were built by ChatGPT Codex with GPT-5.5 High in VS Code.)

Order matters for the core SurveyCTO primers. Generate them top-down so each lower-level primer can rely on the higher-level ones:

1. overview.md (highest-level — generate first)
2. xlsform.md
3. expressions.md

field-plugins.md can be refreshed independently after those are stable, but should cross-link to xlsform.md and expressions.md where it discusses appearance, parameters, and plug-in-metadata().

Each primer should be self-contained enough to be served standalone via the MCP get_surveycto_primer tool, but should cross-link to the others where helpful. Use Markdown, prefer tables for column/option/function reference content, and link back to canonical pages on docs.surveycto.com, support.surveycto.com, and the relevant SurveyCTO GitHub repositories so a reader can always go deeper.

Source-code-derived primers (bespoke, occasional)

datasets-xml.md and data-explorer.md cover material that the public documentation does not adequately describe:

• The Data Explorer docs page explicitly tells readers to “export a workbook and take a look, consulting the four help worksheets as needed” — there is no public column-by-column reference for summary types, options, or exclusion syntax.
• The dataset XML support article is fairly thorough but is missing elements (e.g. ``) and contains at least one apparent inconsistency with how the format is actually used in the field.

These primers were originally derived by inspecting the SurveyCTO server source code (and validating against real exported files), not by reading documentation. There is no Cowork prompt for regenerating them, because no agent reading public docs can produce something as accurate as what’s already in the repo. When they need to change — because the underlying schema changes, or because a missing element comes to light — update them by re-deriving from the source code in a bespoke pass, then sync the result here.

Prompt 1 — overview.md

You are writing the highest-level primer for an AI agent (and the humans
reading the same content as a skill reference) on SurveyCTO. Target audience:
a capable LLM agent that has just been told it needs to help a user with
SurveyCTO, knows nothing specific about the product, and needs orientation
before diving into details.

Read the SurveyCTO documentation and produce a single Markdown file
to save as `references/overview.md` in the surveycto-agent-skill repo.

Primary sources to read carefully:
- https://docs.surveycto.com/ (the docs home; survey the top-level table of contents)
- https://docs.surveycto.com/02-designing-forms/01-core-concepts/ (forms intro)
- https://docs.surveycto.com/05-exporting-and-publishing-data/04-advanced-publishing-with-datasets/01.datasets-intro.html (datasets intro)
- https://docs.surveycto.com/04-monitoring-and-management/02-managing-for-quality/04.advanced-data-explorer.html (Data Explorer intro)
- https://www.surveycto.com/ (high-level product positioning)

The primer must cover, at a high level only:
- What SurveyCTO is and what problem it solves.
- Its relationship to XLSForm and ODK, and the most important ways SurveyCTO
  has diverged from generic ODK behavior (list the highest-impact gotchas
  briefly; full coverage belongs in expressions.md and xlsform.md).
- The three definition file types an agent will encounter: XLSForm form
  definitions (.xlsx with survey/choices/settings sheets), server dataset
  definitions (.xml with  root), and Data Explorer workbook
  definitions (.xlsx with summaries/settings/global_filters/global_exclusions
  sheets). For each: what it is, how to recognize it, what it's for.
- How forms and datasets relate: forms publish to datasets via dataLinks;
  datasets pre-load into forms via formLinks; pulldata() and search() consume
  pre-loaded data; case management is a special dataset configuration.
- The authoritative sources hierarchy: docs.surveycto.com, then
  support.surveycto.com, then www.surveycto.com.
- A "where to go next" section pointing to the four lower-level primers
  (xlsform.md, expressions.md, datasets-xml.md, data-explorer.md) with one
  sentence each describing when to read it.

Constraints:
- This is a high-level primer. Do NOT include exhaustive column lists, field
  type catalogs, expression function reference, or XML element reference —
  those belong in the lower-level primers.
- Keep it concise, but note that we are less concerned with token efficiency 
  than with building effective and accurate expertise in the agent.
- Open with an HTML comment block: ``.
- Use Markdown headings starting at H1 ("# SurveyCTO Overview").
- Use tables for the file-type recognition matrix.
- Cross-link to the other primers using relative links: [`xlsform.md`](xlsform.md), etc.
- Link back to canonical docs URLs whenever you assert a product fact.
- Do NOT invent product behavior. If a source is ambiguous, say so or omit.

Save as `references/overview.md`. Produce only the file contents.

Before you conclude, double-check everything for accuracy. Mistakes in these
primers can affect vital work done by SurveyCTO users.

Prompt 2 — xlsform.md

You are writing the XLSForm mechanics primer for the SurveyCTO agent skill.
The reader has already read overview.md and knows what an XLSForm is at a high
level. They now need to be able to read, edit, and reason about every part of
a SurveyCTO XLSForm.

Read the following SurveyCTO documentation thoroughly. Walk every subsection
under "Designing forms: core concepts" and pull in any other pages linked
from there that describe XLSForm structure or columns:

Primary sources:
- https://docs.surveycto.com/02-designing-forms/01-core-concepts/ (entire section)
- https://docs.surveycto.com/02-designing-forms/01-core-concepts/01.design-tab.html
- https://docs.surveycto.com/02-designing-forms/01-core-concepts/02.field-types.html
- https://docs.surveycto.com/02-designing-forms/01-core-concepts/03.fields.html
- https://docs.surveycto.com/02-designing-forms/01-core-concepts/04.choices.html
- https://docs.surveycto.com/02-designing-forms/01-core-concepts/06.groups.html
- https://docs.surveycto.com/02-designing-forms/01-core-concepts/07.constraints.html
- https://docs.surveycto.com/02-designing-forms/01-core-concepts/08.relevance.html
- https://docs.surveycto.com/02-designing-forms/01-core-concepts/10.appearances.html
  (and any sibling pages on appearances, languages, settings)
- Any pages describing the `settings` worksheet, encryption, languages, and
  form-level metadata.
- Pages describing pulldata(), search(), and field plug-ins as they relate to
  XLSForm columns/appearances (link them to expressions.md for syntax detail).

Also consult support.surveycto.com for any clarifications on edge cases.

The primer must cover, comprehensively:
- The three worksheets (`survey`, `choices`, `settings`) and their roles.
- The `survey` worksheet: every standard column (type, name, label, hint,
  relevance, constraint, constraint message, required, required message,
  calculation, default, repeat_count, choice_filter, appearance, read only,
  disabled, label/hint:Language variants, media columns, etc.) — what each
  one does and how to use it. Use a table.
- Label, hint, note, constraint-message, and required-message formatting:
  SurveyCTO does not render Markdown in these strings. Tell agents to prefer
  plain text; use simple inline HTML only when formatting is genuinely helpful;
  never use full HTML documents; and note that hints should remain plain
  because they are already client-styled helper text. Keep this aligned with
  `references/xlsform.md#label-hint-and-message-formatting`.
- All XLSForm field types SurveyCTO supports — text, integer, decimal,
  select_one, select_multiple, date/time/datetime, geopoint/geotrace/geoshape,
  image/audio/video/file, barcode, calculate, note, acknowledge, deviceid,
  start/end/today, begin group / end group, begin repeat / end repeat,
  username/email, and any SurveyCTO-specific types. Use a table.
- The `choices` worksheet: list_name, value, label, label:Language, filter
  columns, image/media columns, ordering rules.
- Group and repeat semantics: nesting, scoping of relevance, repeat_count
  and repeat_count expressions, fixed vs. dynamic repeats, references into
  and out of repeats.
- Choice filter and cascading select patterns.
- Appearance options — list every appearance SurveyCTO documents, grouped by
  the field type(s) they apply to (text, select_one, select_multiple, date,
  group, repeat). Use tables.
- The `settings` worksheet: form_title, form_id, version, default_language,
  encryption keys (public_key), and any other documented settings.
- Field plug-ins and search() / pulldata() at a structural level (where they
  go, what columns they affect) — defer expression syntax to expressions.md
  with a cross-link.
- The XLSForm template that ships with the skill: what's in it, why it's the
  required starting point, what would break if someone built a workbook from
  scratch.

Constraints:
- Open with an HTML comment block: ``.
- Use Markdown, lots of tables.
- Cross-link to expressions.md for any expression-syntax details.
- Cross-link to datasets-xml.md when discussing pulldata/search and dataset
  attachment.
- Length: as long as needed for completeness, but tight. Aim for accuracy
  and structure over prose.
- Link to the canonical docs page for every section.
- If a column or field type is SurveyCTO-specific (not standard XLSForm),
  call it out explicitly.

Save as `references/xlsform.md`. Produce only the file contents.

Before you conclude, double-check everything for accuracy. Mistakes in these
primers can affect vital work done by SurveyCTO users.

Prompt 3 — expressions.md

You are writing the expression-language primer for the SurveyCTO agent skill.
The reader knows what an XLSForm is and where expressions go (relevance,
constraint, calculation, choice_filter, appearance, default). They now need
to be able to read, write, and debug any SurveyCTO expression.

Read the following SurveyCTO documentation thoroughly:

Primary sources:
- https://docs.surveycto.com/02-designing-forms/01-core-concepts/09.expressions.html (the canonical expressions page — read every section)
- Any sibling/linked pages on operators, functions, dates, strings, repeats,
  randomization, and references between fields.
- https://support.surveycto.com — search for expression-related articles for
  edge cases and worked examples.

The primer must cover:
- The expression model: XPath-derived, evaluated against the form instance,
  what `${field}` and `.` resolve to in different columns (constraint,
  calculation, relevance, choice_filter), and scoping inside groups/repeats.
- All operators SurveyCTO supports — arithmetic (`+ - * div mod`), comparison
  (`= !=  =`), boolean (`and or not()`), string concatenation, and
  any platform-specific operators. Note `=` (not `==`), `div` (not `/`).
- Every documented function, grouped by category: math, string, date/time,
  selection (selected, selected-at, count-selected), choice (choice-label,
  jr:choice-name where it differs), repeat (index, count, sum, etc.),
  randomization (random, once), pulldata, search, regex, conditional (if,
  coalesce), node-set/aggregate (count, sum, min, max), and any others.
  Use tables with: name, signature, return type, brief description, link to
  the docs section that defines it, and a one-line example.
- The SurveyCTO-vs-ODK divergence list, in full: at minimum `=` vs `==`,
  `index()` vs `position()`, `choice-label()` vs `jr:choice-name()`,
  `relevance` column vs `relevant`, `div` vs `/`, `selected()` requirement
  for `select_multiple`, string-quoting rules, anything else the docs call
  out.
- String-literal quoting rules and escaping (single quotes preferred,
  double quotes when the literal contains a single quote, no character
  escaping inside single-quoted strings).
- Common patterns with worked examples: skip logic, range constraints,
  age from DOB, conditional values, pulldata lookups, search() for dynamic
  lists, once() for stable randomization, treatment assignment, regex
  validation, date comparisons (with date()), repeat-instance referencing.
- Common pitfalls and how to recognize them.

Constraints:
- Open with an HTML comment block: ``.
- Length: as long as needed for completeness, but tight. Aim for accuracy
  and structure over prose.
- This primer is about *language*, not *placement*. If a function relates to
  a specific XLSForm column or feature, link to xlsform.md or
  datasets-xml.md rather than re-explaining it.
- Use heavy tables for the function reference.
- Link to the canonical docs anchor for every function/operator.
- If SurveyCTO behavior diverges from generic ODK/XPath, call it out inline
  AND in the divergence summary.
- Do NOT invent functions. If you can't find docs for a function, omit it.

Save as `references/expressions.md`. Produce only the file contents.

Before you conclude, double-check everything for accuracy. Mistakes in these
primers can affect vital work done by SurveyCTO users.

Prompt 4 — Field plug-in materials

You are refreshing the SurveyCTO agent skill's field plug-in authoring
materials. The goal is to keep the bundled reference and scaffolding aligned
with the current SurveyCTO field plug-in developer documentation, without
regressing the skill's offline usefulness for IDE-based coding agents.

Work in the `surveycto-agent-skill` repo. Read the current files first:
- `references/field-plugins.md`
- `SKILL.md` sections that mention field plug-ins
- `assets/field-plugin-template/`
- `assets/field-plugin-test-harness/README.md`
- `assets/field-plugin-test-harness/validate.mjs`
- `assets/field-plugin-test-harness/preview.html`

Then read the live authoritative sources carefully:
- https://github.com/surveycto/field-plug-in-resources/blob/master/docs/developer-docs-home.md
- https://github.com/surveycto/field-plug-in-resources/blob/master/docs/plug-in-definition.md
- https://github.com/surveycto/field-plug-in-resources/blob/master/docs/api-reference.md
- https://docs.surveycto.com/02-designing-forms/03-advanced-topics/06.using-field-plug-ins.html
- https://docs.surveycto.com/02-designing-forms/03-advanced-topics/07.testing-field-plug-ins.html
- https://support.surveycto.com/hc/en-us/articles/360045235134-Field-plug-in-catalog
- https://support.surveycto.com/hc/en-us/articles/360052426933-Guide-to-creating-field-plug-ins
- https://support.surveycto.com/hc/en-us/articles/360045234534-Guide-to-field-plug-ins-how-to-customize-fields
- https://www.surveycto.com/data-collection-quality/build-field-plugins-genai/

Also inspect the current SurveyCTO baseline and feature-demo repositories for
changes in conventions, examples, or packaging assumptions:
- https://github.com/surveycto/baseline-text
- https://github.com/surveycto/baseline-integer
- https://github.com/surveycto/baseline-decimal
- https://github.com/surveycto/baseline-select_one
- https://github.com/surveycto/baseline-select_multiple
- https://github.com/surveycto/feature-demo-parameters
- https://github.com/surveycto/feature-demo-metadata
- https://github.com/surveycto/feature-demo-intents

Update only what the sources justify. Preserve concise, agent-usable guidance;
do not expand into a verbatim copy of the upstream docs. In particular:
- Refresh `references/field-plugins.md` so it accurately covers the current
  bundle anatomy, manifest schema, supported field types, packaging rules,
  Mustache/template behavior, form API, runtime CSS classes, provided and
  called JavaScript functions, parameter and metadata behavior, using a
  plug-in in an XLSForm, testing workflow, recommended baselines, sharing
  conventions, and common pitfalls.
- Keep the primer self-contained for offline agent use, but include canonical
  links back to the GitHub developer docs, product docs, and support articles.
- Open the primer with an HTML comment block like:
  ``.
- Check whether `SKILL.md` still gives the right minimal routing and workflow
  guidance for field plug-ins. Keep `SKILL.md` brief; defer detailed API
  content to `references/field-plugins.md`.
- Check whether `assets/field-plugin-template/` still matches current baseline
  conventions. Update the template only when the upstream docs or baselines
  show a concrete change. Keep it minimal and generic.
- Check whether `assets/field-plugin-test-harness/validate.mjs` and
  `preview.html` still validate and simulate the current documented runtime
  behavior. Update them only for concrete doc/API changes or clear bugs. Do
  not add npm dependencies; the harness should remain zero-dependency and
  usable offline.
- Keep all edited files ASCII unless an existing file or upstream API name
  requires otherwise.

Invariants to preserve (do not regress these regardless of what the
upstream docs emphasize or omit):
- The "preview by default while authoring" behavior in `SKILL.md`'s
  field plug-in *Testing* subsection: when an agent creates or edits a
  plug-in, it should render
  `assets/field-plugin-test-harness/preview.html` immediately and
  re-render after every revision.
- The proactive "recommend testing as a next step" behavior rule: after
  authoring or revising plug-in source files, the agent should
  re-render the harness and recommend the in-product field plug-in
  console as the required next step before deployment, plus a
  real-device pass before going live.
- An accurate description of the in-product field plug-in console flow
  per https://docs.surveycto.com/02-designing-forms/03-advanced-topics/07.testing-field-plug-ins.html:
  *Test* is a form-level action (Design tab button or top-right toggle
  in the form designer); the user navigates to the field that uses the
  plug-in and clicks the plug-in console icon on the left edge of the
  form area; the panel shows plug-in details, current values of dynamic
  parameters and metadata, and three editable HTML/CSS/JS boxes with a
  *Reload* button; edits are session-scoped and not saved to the zip.
- Do not assert that the in-product console exposes the full
  `fieldProperties` payload, persisted-metadata storage, or a generic
  JS message/log surface unless a future revision of the docs page
  above actually documents them. For log-level debugging, point
  readers at the local harness or browser devtools.

Validation:
- Run the field plug-in harness validator against `assets/field-plugin-template/`.
- If the repo has tests or lint/build scripts relevant to the changed files,
  run them.
- Manually check that every field plug-in source link in
  `references/field-plugins.md` still resolves.
- Verify the in-product field plug-in console description in
  `SKILL.md` and `references/field-plugins.md` against the live
  *Testing field plug-ins* docs page before finishing.
- Summarize which upstream changes were incorporated and which files changed.

Before you conclude, double-check everything for accuracy. Mistakes in these
materials can affect production SurveyCTO forms and user-facing data collection
workflows.

Maintaining the MCP server reference

references/mcp.md documents the SurveyCTO MCP server’s tool surface, patch semantics, concurrency contract, error envelope, and limits. Unlike the primers, it is not derived from public SurveyCTO documentation — it is derived from the MCP server’s own implementation in the private scto-assistant-be repo. The canonical sources are the tool definitions, capability discovery payload, and error-handling code in that repo.

Update mcp.md whenever the server’s tool surface changes:

• Tools added, removed, or renamed
• Tool signatures (parameter names, defaults, caps) changed
• Patch op support changed (new ops, new column aliases, new validation behavior)
• Error codes added, removed, or repurposed
• Limits changed (upload size, session TTL, page size, top_k cap)
• Concurrency rules changed

There is no AI-agent prompt for regenerating this file because no agent reading public sources can produce it accurately — the truth lives in scto-assistant-be. When the server changes, update mcp.md by hand from the relevant source files in that repo, then bump the skill version per the rules in Versioning (typically a minor bump for additive changes, major for breaking changes since the agent’s MCP workflow depends on this content).

This file is not vendored back to the MCP server via get_surveycto_primer — it would be circular, and the server already exposes its current tool surface live via get_surveycto_mcp_capabilities.

Syncing primers to the MCP server

The SurveyCTO MCP server vendors these primers under src/mcp_server/primers/ and serves them via its get_surveycto_primer tool. After updating any primer here — whether by regenerating from docs or by re-deriving from source — sync the change to the MCP server repo (manual until automated) so callers without the skill installed get the updated content. As of this writing, the field-plug-in primer is not yet vendored by the MCP server; once it is, include it in the same sync process.

Links

• SurveyCTO Documentation
• SurveyCTO Support Center
• Agent Skills Specification
• Using expressions in your forms

License

Apache-2.0