# potato-skill: Quick Start with a Coding Agent

Source: https://www.potatoannotator.com/docs/getting-started/quick-start-with-a-coding-agent

**You can start a Potato project in two ways. Write the task yourself, as the [Quick Start](/docs/getting-started/quick-start) shows, or describe the study to a coding agent and let [potato-skill](https://github.com/davidjurgens/potato-skill) design and build it.** This page covers the second route. Both end in the same place: a Potato annotation task you can run, change and share.

## Design decisions the skill makes

potato-skill is an [agent skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview), a package of instructions and helper scripts that a coding agent loads when a request needs them. It handles the design of the study as well as the build, from the label set to the exported data:

- what to ask annotators, and on what scale
- how many annotators each item needs
- how to train annotators and check their work
- the interface annotators see
- starting the task and going through it the way an annotator would
- exporting the results in the format the next step needs

It also works on studies that are already running. It reports progress and agreement, and it says which changes are safe to make after annotators have started.

The task it builds runs on Potato, so it gets what Potato already does: a login for each annotator, several annotators per item, [agreement statistics](/docs/guides/inter-annotator-agreement), [Prolific and MTurk](/docs/guides/crowdsourcing-prolific-mturk) integration, and export to the formats downstream tools read.

## Requirements

Potato has to be installed where the agent runs commands, because the skill's helper scripts import Potato and call the `potato` command:

```bash
pip install potato-annotation
```

You also need a coding agent. The skill was written for Claude Code, and the next section covers other agents.

## Install the skill

In [Claude Code](https://code.claude.com/docs/en/discover-plugins):

```
/plugin marketplace add davidjurgens/potato-skill
/plugin install potato-skill@potato
```

For Codex, Cursor and other agents, the [`skills` CLI](https://github.com/vercel-labs/skills) installs it into your project:

```bash
npx skills add davidjurgens/potato-skill --agent codex cursor
```

With `--agent codex cursor` it copies the skill into `.agents/skills/potato-skill/`. Codex and Cursor can also read the `AGENTS.md` file at the root of the potato-skill repository.

## Describe the study

Say what needs labelling, who will label it and what the labels are for. You do not need to know Potato's annotation types or its config format. A request can be this short:

> I want 200 tweets labelled for sentiment on a 5-point scale by three annotators each, with a consent page and two attention checks. Build it and start it.

The skill works out the question wording, the scale, how items are assigned and how annotators are checked. The agent then builds the task, starts it, and goes through it the way an annotator would before handing it back. Open it in your browser and label a few items yourself before you invite anyone.

## The task it produces

A Potato task: a project folder holding the task's config, its data and its instructions. Everything in the [Quick Start](/docs/getting-started/quick-start) applies to it. You start it with `potato start config.yaml`, edit it by hand, add annotators and export the labels.

Because the result is a Potato task folder, other people can use it too. A colleague can run the same study on new data, you can rerun it next year, and you can publish it with the paper that used it. The [showcase](/showcase) is a collection of tasks shared this way, taken from published papers.

## Existing designs and annotations

- **A published design.** The skill can start from one of 440 annotation designs taken from published papers, with their label sets, question wording and instructions. You can browse them in the [showcase](/showcase).
- **Another tool's annotations.** It imports existing annotations from Label Studio, CVAT or COCO, so a half-finished project can carry on in Potato.
- **A study that is already running.** It reports progress for each annotator and agreement for each question, and it says which fixes are safe mid-study and which would corrupt the data already collected.

## Tests against Potato's registries

The skill's CI checks that every annotation type, config key and sample config its instructions name exists in Potato. Sample YAML goes through Potato's validator, and the worked example boots a real Potato server. Three of its references are generated from Potato's own registries, so the types and keys the agent reads are the ones the server enforces.

Its reference material is published at [davidjurgens.github.io/potato-skill](https://davidjurgens.github.io/potato-skill/), readable without installing anything. Anthropic [recommends reviewing any skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#security-considerations) before you install it.

## Comparing the two routes

| | Write the task yourself | Describe it to a coding agent |
|---|---|---|
| You start with | a YAML config | a description in plain language |
| Suits | learning Potato, small tasks | new studies, crowdsourced studies with training and checks, annotation types you have not used |
| You end with | a Potato task | a Potato task |

You can switch routes at any point. An agent can change a task you wrote, and you can edit one the agent built.

## Next steps

- [Quick Start](/docs/getting-started/quick-start), for writing a task by hand
- [Configuration Basics](/docs/getting-started/configuration-basics)
- [Crowdsourcing on Prolific and MTurk](/docs/guides/crowdsourcing-prolific-mturk)
- [Measuring inter-annotator agreement](/docs/guides/inter-annotator-agreement)
- [Configs your coding agent can check](/docs/guides/configs-your-coding-agent-can-check)
- [potato-skill on GitHub](https://github.com/davidjurgens/potato-skill)