Tally Survey Deployment

This reference file handles deploying a survey to Tally — creating the form via the Tally MCP, retrieving the shareable link, and updating the survey file with the live form details.

It is loaded by the surveys skill when the founder wants to activate a survey in Tally: either immediately after the initial-survey-questions workflow, or standalone when an existing questions-only survey is ready to deploy. It is not a skill and should not be invoked independently.

---

Context

You already have:

• A survey file at startup/surveys/{slug}.md with mode: questions-only and a complete ## Questions section
• The founder's confirmed question set, distribution plan, and respondent value prop

Goal

Create a live Tally form from the existing question set, retrieve the public shareable URL, and update the survey file to reflect the active deployment.

---

The single most important rule

Ask exactly one question at a time. Always.

Do not stack questions. Do not ask a question and then add a follow-up in the same message. One question. Wait. Then respond.

---

How to run the workflow

Step 1 — Check Tally MCP configuration

Check whether the Tally MCP is available. The Tally MCP is configured when:

• TALLY_API_KEY is set in the environment, or
• The Tally MCP server (https://api.tally.so/mcp) is connected in the current session

If not configured, stop here and provide setup instructions:

---

To connect Tally:

1. Get an API key:

   • Log into your Tally account at tally.so
   • Go to Settings → API Keys
   • Create a new API key and copy it

2. Add the Tally MCP to Claude Code:

   claude mcp add --transport http tally https://api.tally.so/mcp --header "Authorization: Bearer YOUR_API_KEY"
   

   Replace YOUR_API_KEY with the key you just copied.

3. Verify it's connected:

   claude mcp list
   

   You should see tally in the list.

Note: Tally's UI and API change occasionally. If these steps don't match what you see or something isn't working, let me know and I'll look up the current instructions.

Once you've done this, come back and I'll create the survey.

---

If the founder says the steps didn't work or something looks different in the Tally UI, do a web search for current Tally MCP or API setup instructions before retrying — Tally's UI and API surface change and the instructions here may be stale.

If configured, proceed to Step 2.

Step 2 — Confirm the question source

Identify which survey to deploy:

• If arriving from initial-survey-questions.md: the question set is already confirmed — proceed with those questions.

• If entering standalone: ask which survey to activate if multiple questions-only surveys exist. Load the file and show the question set:

  "Here are the questions from '{Survey Title}'. Ready to create this in Tally?"

  Wait for confirmation.

Step 3 — Map questions to Tally block types

Before creating the form, map each question to the appropriate Tally block type:

Question annotation	Tally block type
multiple choice	MULTIPLE_CHOICE
rating scale	LINEAR_SCALE
open-ended	TEXTAREA
yes/no	MULTIPLE_CHOICE with two options
short text	INPUT_TEXT

Step 4 — Create the survey in Tally

Use the Tally MCP to create the form. The form should include:

• A title derived from the survey's H1 heading
• All questions in order, with correct block types and options
• A closing screen that includes the respondent value prop from ## Distribution Plan (e.g., "We'll share the results back with everyone who completes this survey" or a link to the MVP/waitlist)

If the Tally MCP create_form call fails, report the error verbatim and suggest checking the API key or retrying.

Step 5 — Retrieve and display the shareable URL

Get the public Tally form URL from the API response (format: https://tally.so/r/{formId}).

Display it clearly:

"Your survey is live: {tally_url}

Copy this link and post it to the channels in your distribution plan."

Step 6 — Update the survey file

Read the existing survey file. Update the frontmatter:

status: active
mode: tally
tally_form_id: {formId from API response}
tally_url: https://tally.so/r/{formId}

Leave all other frontmatter fields and all sections unchanged.

Propose the updated frontmatter before writing. Get confirmation. Write the file back.

After writing: "Updated startup/surveys/{slug}.md — status is now active."

Step 7 — Close and hand off

Remind the founder of the two things that matter now:

1. Post the link — to the distribution channels in the survey file; the survey only generates signal if it reaches the right audience
2. Check back — when they want to see how it's going, they can ask: "How is the [survey name] survey going?" and the agent will fetch the current response count from Tally

Optional: if startup/interviews/*.md is sparse (fewer than 5 interviews), suggest running interviews in parallel — surveys and interviews answer different questions and the combination is stronger than either alone.

---

Completion criteria

• Tally form created successfully
• Public URL retrieved and displayed to founder
• startup/surveys/{slug}.md updated with tally_form_id, tally_url, status: active, mode: tally
• Founder confirmed the file update

---

What comes next

• Post the link to every channel in the Distribution Plan — this is on the founder
• Run interviews in parallel — qualitative and quantitative together give the strongest signal
• Check results — when the founder asks how the survey is going, the agent fetches the current Tally submission count and any available aggregate data
• Analyze results — once enough responses are in, the agent will be able to dispatch a survey analyst to map responses to hypotheses and suggest state updates (coming in a future update to this skill)