Skip to content

Set Up potato-skill in Codex

Add potato-skill to a Codex project with one npx command, start the skill with $potato-skill, and approve the commands the default sandbox holds back.

Codex reads skills from .agents/skills/ in your repository, and npx skills add davidjurgens/potato-skill --agent codex copies potato-skill there. Codex picks up the skill without a restart, and $potato-skill starts the skill in the CLI and the IDE extension. Quick Start with a Coding Agent covers what the skill does with a study, and Install potato-skill in Your Coding Agent covers the other agents.

Before you install

Potato goes in the Python environment that Codex's shell uses. The skill's helper scripts import Potato's registries and call the potato command, and the skill's first step checks that Potato imports. The browser extra and Chromium let potato preview --screenshot and the skill's walk-through script open the task in a headless browser:

bash
pip install 'potato-annotation[preview]'
playwright install chromium

Codex's default sandbox has no network access. Install both before you start to save a round of approvals. The skills CLI runs through npx and needs Node.js 22.20 or later.

Installing the skill

Run the install in your repository:

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

The command copies SKILL.md, the 30 reference files, and the nine helper scripts into .agents/skills/potato-skill/, and records the source in skills-lock.json at the repository root. Codex scans .agents/skills/ in every folder from the current one up to the repository root, so a session started in a subfolder of the repository finds the skill too. Committing .agents/skills/ gives collaborators the skill with no install step.

Add -g to install the skill for every repository on the machine instead:

bash
npx skills add davidjurgens/potato-skill --agent codex -g

A global install goes to ~/.agents/skills/potato-skill/, the user-level skills folder Codex reads. Codex detects a new skill without a restart. If the skill does not appear, restart Codex.

Checking the install

In Codex CLI or the IDE extension, /skills lists the skills Codex found, and potato-skill appears in the list. In the ChatGPT desktop app, Skills in the sidebar shows the skills across your projects.

Starting a study

Mention the skill with $potato-skill and describe the study:

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

Codex also loads the skill without a mention when a request matches the skill's description, such as a request to build an annotation task, edit a Potato config.yaml, or check on a running study.

Sandbox and approvals

Codex runs commands in a sandbox. The default mode, workspace-write, lets commands write inside the workspace with network access turned off. The setting behind the network is sandbox_workspace_write.network_access, which defaults to false. Under the on-request approval policy, Codex works inside the sandbox and asks before a command goes beyond the sandbox.

During a build, the skill has Codex validate the config, start a Potato server on your machine, open the task in a headless browser, and run the skill's helper scripts. A pip install needs the network, and the default sandbox has none. Approve a command outside the sandbox when Codex asks, after reading the command. In the CLI, /permissions opens the permissions picker. In the IDE extension and the app, the same choices sit under the composer as Ask for approval, Approve for me, and Full access. Codex's sandboxing documentation describes each mode.

AGENTS.md

Codex reads AGENTS.md by filename. The potato-skill repository has an AGENTS.md at the repository root, a short summary of the skill's rules. Copying that file into your repository root gives Codex the rules with no install step. The file points at reference files and scripts that only a full install puts on disk. Use the skills CLI install for building a study. If your repository already has an AGENTS.md, add the summary to that file rather than replacing the file.

Updating and removing the skill

The skills CLI updates and removes the skill by name. Add -g to either command for a global install:

bash
npx skills update potato-skill
npx skills remove potato-skill

update checks the installed copy against the GitHub repository and replaces the copy when the repository has changed. remove deletes .agents/skills/potato-skill/ and the skill's entry in skills-lock.json.

To turn the skill off without deleting the skill, add an entry to ~/.codex/config.toml with the absolute path of the skill's SKILL.md, and restart Codex. Codex's skills documentation lists the other settings an entry takes:

toml
[[skills.config]]
path = "/path/to/your/repo/.agents/skills/potato-skill/SKILL.md"
enabled = false

Further reading