potato-skill: Claude Code, Codex, Cursor로 어노테이션 연구 만들기

potato-skill은 어노테이션 연구를 평범한 말로 설명한 것을 실행되는 Potato 작업으로 바꿉니다. 설정보다 먼저 내려야 하는 설계 결정, 어노테이터가 보게 되는 인터페이스, 검증은 통과하지만 실제로는 동작하지 않는 작업을 잡아내는 검사를 다루는 참고 파일 28개와 보조 스크립트 9개가 들어 있습니다. Claude Code, Codex, Cursor에 설치할 수 있고 GPL-3.0-or-later로 배포됩니다.

스킬 설치

Claude Code에서는 플러그인 마켓플레이스에서 명령 두 줄로 설치합니다.

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

Codex와 Cursor에서는 skills CLI로 설치하며, 작업 중인 프로젝트 안으로 스킬을 복사합니다.

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

보조 스크립트 9개가 Potato의 레지스트리를 임포트하고 potato 명령을 실행하므로, 에이전트가 명령을 실행하는 곳에는 Potato 자체도 설치되어 있어야 합니다.

pip install potato-annotation

Codex나 Cursor 설치에 들어가는 것

skills CLI는 .agents/skills/potato-skill/에 SKILL.md와 참고 파일 28개, 스크립트 9개를 모두 씁니다. 따라서 Codex나 Cursor 프로젝트도 Claude Code 설치와 같은 자료를 갖게 됩니다. AGENTS.md와 .cursor/rules는 건드리지 않으며, 각 도구가 그 디렉터리의 스킬을 어떻게 찾아내는지는 도구에 달려 있습니다.

저장소 루트에는 AGENTS.md도 있는데, Codex와 Cursor는 설치 단계 없이 파일 이름만 보고 이 파일을 읽습니다. 이 파일은 참고 자료 전체 약 79,000단어에 대한 짧은 요약이며, 전체 설치를 해야만 디스크에 놓이는 참고 파일과 스크립트를 가리킵니다. 에이전트에게 인계 전 검사 루프와 실제로 효력이 있는 규칙을 주고 싶다면 이 파일을 쓰고, 그 뒤에 있는 참고 자료까지 원한다면 skills CLI를 쓰세요.

스킬이 묻지 않고 정하는 기본값

틀렸을 때 고치는 비용이 싼 결정은 그 자리에서 내리고, 틀렸을 때 비용이 크거나 되돌릴 수 없거나 애초에 에이전트가 내릴 결정이 아니면 사람에게 넘깁니다. 키보드 단축키를 바꾸는 데는 비용이 들지 않지만, 어노테이션 단위를 잘못 잡아 항목 5,000개를 다시 돌리면 연구 예산이 날아갑니다. 스킬이 알아서 정하는 기본값은 다음과 같고, 작업을 인계할 때 각각을 가정으로 함께 적어 줍니다.

연구자에게 되돌려 주는 결정

다섯 가지 결정은 한 번에 묶인 메시지로 연구자에게 돌아가며, 각각 제안된 답이 붙어 있어서 한마디로 받아들일 수 있습니다.

• 어노테이션 단위. 데이터만으로 정해지지 않을 때입니다. 문단 단위로 된 파일인데 질문은 사실 문장에 관한 것이라면 연구가 갈라지는 지점이고, 어느 쪽을 고르든 다시 돌려야 할 수 있습니다.
• 항목당 어노테이터 수. 일치도를 보고할 예정일 때입니다. 어노테이터 3명은 1명의 세 배가 들기 때문에, 스킬은 예산을 대신 써 버리는 대신 이유를 붙인 숫자를 제안합니다.
• 동의서 문구. 설명한 내용을 바탕으로 초안을 쓰고, 이 초안은 윤리위원회가 승인한 문구로 바꿔야 한다고 분명히 말합니다.
• 애매한 사례를 놓을 자리가 없는 라벨 집합. "불명확"도 "해당 없음"도 없는 라벨 3개는 대개 빠뜨린 것이고, 그러면 어노테이터는 정말로 모호한 항목을 아무 데나 넣게 되며, 이후 단계에서는 그런 일이 있었다는 것조차 보이지 않습니다. 스킬은 놓을 자리가 없어 보이는 항목을 짚어 줍니다.
• 어노테이터에게 사용자 이름, 얼굴, 위치를 보여 주는 모든 경우.

이 중 무엇도 제작을 멈추게 하지는 않습니다. 스킬은 가정을 밝히고, 작업을 만들고, 검증한 뒤, 이미 클릭해 볼 수 있는 결과물과 함께 질문을 내놓습니다.

인계 전 검사

설정이 검증을 통과한다는 것은 서버가 뜬다는 뜻일 뿐, 사람이 그 작업을 실제로 할 수 있는지에 대해서는 아무것도 말해 주지 않습니다. 그래서 스킬은 에이전트에게 작업을 렌더링해서 직접 보라고 지시합니다.

potato validate config.yaml --strict
potato preview config.yaml --screenshot shot-01.png

--strict는 인식되지 않는 설정 키를 경고가 아니라 실패로 바꿉니다. 이 옵션이 없으면 오타는 그대로 받아들여진 뒤 무시되고, 켰다고 생각한 기능은 꺼진 채로 남습니다. 설정은 제대로 읽히는데 아무 일도 일어나지 않는 경우의 흔한 원인이 이것입니다.

--screenshot은 실제 Potato 서버를 띄우고 헤드리스 Playwright로 조작하면서 콘솔 오류, 처리되지 않은 페이지 예외, 400 이상의 HTTP 응답을 기록합니다. 세 목록이 모두 비어 있을 때만 0으로 종료합니다. 어노테이션 인터페이스는 대부분 HTML이 도착한 뒤에 JavaScript가 만들어 내기 때문에, 이 단계는 검증이 잡을 수 없는 것을 잡습니다. 보이지 않는 라디오 버튼이 전형적인 경우인데, 라벨 텍스트는 그대로 렌더링되어서 언뜻 보면 질문이 멀쩡해 보입니다.

이 두 명령을 도는 사이클은 자동화가 아니라 지침입니다. 참고 자료는 에이전트에게 한 번에 한 가지만 바꾸고, 렌더링 결과를 매번 새 파일 이름으로 저장해 두 장을 나란히 놓으면 무엇이 달라졌는지 보이게 하고, 직접 만든 레이아웃이라면 서너 번은 돌 것으로 예상하라고 알려 줍니다. 또 display_logic 뒤에 있는 것은 첫 렌더링에 나타나지 않으며 나타나지 않는다는 사실만으로는 아무것도 증명되지 않으니, 조건을 주석 처리하고 렌더링한 다음 다시 되돌리라고 알려 줍니다.

보조 스크립트 9개 중 셋은 판단이 아니라 측정으로 답할 수 있는 부분을 자동화합니다. check_ui.py는 1280x900에서 실제 레이아웃을 재어 화면 아래로 밀려난 스킴이나 다음 버튼, 비어 있는 미디어 위젯, 중복된 단축키를 보고합니다. boot_and_check.py는 서버를 띄운 뒤, 설정은 되어 있는데 아무것도 로드하지 않은 기능을 모두 보고합니다. 연습 항목을 하나도 읽지 못한 연습 라운드 같은 것입니다. walk_task.py는 어노테이터가 하듯 실행 중인 작업을 끝까지 진행해 보고 어디서 멈추는지 보고합니다.

어노테이터가 시작한 뒤의 안전한 변경과 위험한 변경

어노테이션 연구에서 잘못되는 일은 대부분 어노테이터가 시작한 뒤에 일어나고, 문제가 되는 실패는 오류 메시지를 남기지 않습니다. 스킬은 그중 둘을 다룹니다.

연구 도중에 질문 이름을 바꾸는 것이 가장 위험합니다. 아무 오류도 나지 않는데, 세 곳이 서로 다른 것을 보고하기 시작합니다. 관리자 개요는 연구가 100% 완료되었다고 하고, 일치도 보고서는 그 스킴에 항목이 하나도 없다고 하고, CSV 내보내기에는 예전 열 이름이 담깁니다. 내보내기는 설정이 아니라 저장된 내용을 따르기 때문입니다. 안전장치는 부팅 로그에 찍히는 WARNING 한 줄이 전부입니다. 질문을 추가하는 것도 같은 문제의 조용한 버전인데, Potato는 완료 여부를 질문별이 아니라 항목별로 추적하므로 나중에 추가한 질문은 이미 말뭉치를 끝낸 사람에게는 영영 닿지 않습니다.

두 번째는 인증입니다. 기본 백엔드는 계정을 메모리에 두기 때문에, 서버를 멈추면 어노테이터 로그인도 함께 사라집니다. 어노테이션 자체는 디스크에 안전하게 남습니다. 어노테이터가 다시 들어와 같은 사용자 이름으로 재등록하면 원래 작업에 다시 연결되므로, 누군가 다른 사용자 이름을 입력해 별개의 사람으로서 말뭉치를 처음부터 다시 시작하기 전까지는 문제가 드러나지 않습니다. authentication.user_config_path를 설정하면 계정이 솔트를 넣은 해시와 함께 파일로 기록됩니다. 잊어버리기 가장 쉬운 곳에서 가장 중요한데, Render와 Hugging Face Spaces는 컨테이너를 알아서 재시작하기 때문입니다.

이미 진행 중인 연구라면 study_status.py가 관리자 라우트를 읽어 진행 상황, 어노테이터별 속도, 질문별 일치도, 주의력 확인에 걸리고 있는 사람, 손댔다가 방치한 항목을 붙들고 있는 사람을 알려 줍니다. 그다음 스킬은 어떤 수정이 아직 안전하고 어떤 수정이 이미 비용을 치른 답변을 망가뜨리는지 말해 줍니다.

Potato의 MCP 서버

Potato에는 MCP 서버가 둘 있어서, 에이전트가 셸 명령을 거치지 않고도 같은 답을 얻을 수 있습니다. potato mcp serve --root .는 CLI와 같은 레지스트리를 읽는 저작 도구 12개를 노출하며, 여기에는 렌더링된 페이지를 이미지로 돌려주는 render_task_screenshot도 있습니다. potato mcp connect는 실행 중인 연구에 다리를 놓아 상태, 진행 상황, 어노테이터, 일치도, 배정, 내보내기를 다루는 실시간 도구 12개를 더합니다. 이 브리지에는 노출할 도구를 나열한 설정의 mcp 블록과 potato mcp issue-token으로 발급한 토큰이 필요합니다.

직접 만든 라벨링 도구와 그 비용

항목 수백 개에 라벨을 붙이는 흔한 방법은 코딩 에이전트에게 간단한 라벨링 도구를 만들어 달라고 하는 것입니다. 항목을 하나씩 보여 주고 답을 CSV에 덧붙이는 Streamlit이나 Flask 페이지 같은 것입니다. 한 사람이 오후 한나절 분량의 데이터에 한 번 라벨을 붙이는 경우라면 만들 만합니다. 비용은 연구에 어노테이터별 로그인, 항목당 어노테이터 3명과 각 항목을 알맞은 사람에게 보내는 배정, 연습 라운드와 주의력 확인, 일치도 통계, Prolific 완료 코드, 다음 스크립트가 기대하는 형식의 내보내기, 또는 다음 달에 똑같이 돌아가는 두 번째 연구가 필요해질 때 생깁니다. 그 하나하나가 연구 하나를 위해 만든 도구 안에서 누군가 작성하고 테스트하고 디버깅해야 하는 기능이고, Potato에는 이미 전부 들어 있습니다.

둘은 연구가 끝난 뒤 무엇이 남는지도 다릅니다. 직접 만든 라벨링 도구는 보통 저장소 하나의 데이터셋 하나에 묶여 있지만, Potato 작업은 설정과 데이터가 든 폴더라서 Potato만 있으면 누구나 시작할 수 있습니다. 쇼케이스에는 그런 작업이 400개 넘게 있고 대부분 발표된 논문에서 가져온 것이며, find_design.py가 설명한 것과 가까운 설계를 여기서 찾아 줍니다.

스킬이 만들어 주는 연구

다섯 가지 사례가 범위를 보여 줍니다. 각각 짧은 설명에서 시작해 실행 가능한 작업으로 끝납니다.

• 크라우드워커의 입장(stance) 라벨. 게시물당 어노테이터 3명, 연습 라운드, 주의력 확인, Prolific 완료 코드, 그리고 라벨이 모인 뒤의 일치도. 크라우드소싱 연구 진행하기와 어노테이터 간 일치도 측정을 참고하세요.
• 챗봇 응답 두 개 비교. 선호 척도와 자유 서술 이유 칸이 있는 나란히 비교 레이아웃. 쌍대 모델 비교와 RLHF 선호 데이터를 참고하세요.
• 에이전트 트레이스에서 실패한 단계 표시. 트레이스가 한 단계씩 펼쳐지고, 작업은 어노테이터가 표시한 단계와 그 설명을 기록합니다. 에이전트 궤적 어노테이션을 참고하세요.
• CVAT 프로젝트 이어 가기. potato import가 형식 20가지를 읽으므로 기존 박스가 라벨과 함께 들어오고, 연구 결과는 COCO로 다시 내보냅니다. 바운딩 박스 일치도 측정을 참고하세요.
• 두 명의 코더와 코드북. 코드북이 그대로 코딩 인터페이스가 되고, 두 코더 모두에게 모든 응답이 배정되며, 판정 단계가 불일치를 처리합니다. 판정과 불일치를 참고하세요.

Potato 레지스트리에 대한 테스트

그럴듯한데 틀린 식별자는 문서가 아예 없는 것보다 나쁩니다. 에이전트가 그것을 그대로 쓰기 때문입니다. 그래서 참고 파일 28개 중 셋은 Potato 자체 레지스트리에서 생성되며, 서버가 실제로 적용하는 것과 어긋날 수 없습니다. 어노테이션 유형 61가지 전부와 각각에 대해 실제 프로젝트에서 가져온 예제, 문서화된 최상위 설정 키, 문서화된 하위 키가 여기에 해당합니다.

CI는 스킬의 핵심 파일을 대상으로, 거기에 이름이 나오는 모든 어노테이션 유형, 표시 유형, 설정 키, 연산자, 전략 이름, 명령이 Potato에 실제로 있는지 확인합니다. 모든 YAML 샘플은 동작하는 설정에 끼워 넣어져 Potato의 실제 검증기를 통과하고, 예제는 실제 서버를 띄워 켜는 기능마다 로그에 0이 아닌 개수가 찍혀야 합니다.

참고 자료는 davidjurgens.github.io/potato-skill에 공개되어 있어서, 설치하기 전에 스킬이 에이전트에게 무엇을 알려 주는지 읽어 볼 수 있습니다. Anthropic은 어떤 스킬이든 먼저 검토할 것을 권고합니다.

질문

아래 질문은 potato-skill과 직접 만든 라벨링 도구 중 무엇을 고를지, 인계 전에 스킬이 무엇을 검사하는지, 스킬이 만든 인터페이스를 어떻게 바꾸는지를 다룹니다.

코딩 에이전트가 맞춤형 어노테이션 도구를 만들어야 하나요, 기존 도구를 써야 하나요?

맞춤형 도구는 한 사람이 항목 수백 개에 한 번 라벨을 붙일 때만 만드세요. 항목을 하나씩 보여 주고 답을 CSV에 덧붙이는 Streamlit이나 Flask 페이지면 그 경우는 충분합니다. 연구에 항목당 어노테이터 여러 명, 연습 라운드, 주의력 확인, 일치도 통계, Prolific 완료 코드 중 하나라도 필요해지면, 그 하나하나를 연구 하나를 위해 만든 도구 안에서 작성하고 테스트해야 하는데, Potato에는 이미 전부 들어 있습니다. potato-skill이 Potato 위에 만들어진 이유가 이것이며, potato-skill이 만드는 작업은 Potato만 있으면 누구나 다시 실행할 수 있는 폴더입니다.

potato-skill은 작업을 인계하기 전에 무엇을 검증하나요?

potato-skill은 작업을 넘기기 전에 에이전트가 Potato 명령 두 개를 실행하게 하고, 보조 스크립트 중 셋이 그 명령들로는 잡을 수 없는 것을 검사합니다. potato validate config.yaml --strict는 인식되지 않는 설정 키가 하나라도 있으면 실패합니다. potato preview config.yaml --screenshot은 헤드리스 Playwright로 실제 서버를 띄우고, 페이지에서 콘솔 오류도, 처리되지 않은 예외도, 400 이상의 HTTP 응답도 나오지 않았을 때만 0으로 종료합니다. check_ui.py는 화면 아래로 밀려난 어노테이션 질문이나 다음 버튼을 보고하고, boot_and_check.py는 설정은 되어 있는데 아무것도 로드하지 않은 기능을 보고하며, walk_task.py는 어노테이터가 하듯 작업을 끝까지 진행해 보고 어디서 멈추는지 보고합니다.

potato-skill이 만든 인터페이스를 원하는 대로 바꿀 수 있나요?

네. 작업은 평범한 Potato 설정이므로 레이아웃을 직접 수정하거나 에이전트에게 바꿔 달라고 할 수 있습니다. 직접 만든 레이아웃이라면 potato-skill은 에이전트에게 한 번에 한 가지만 바꾸고, 렌더링 결과를 매번 새 스크린샷 파일로 저장해 연속된 렌더링을 비교하면 무엇이 달라졌는지 보이게 하고, 서너 번은 돌 것으로 예상하라고 알려 줍니다. display_logic 뒤에 있는 것은 첫 렌더링에 나타나지 않으므로, 에이전트는 조건을 주석 처리하고 렌더링한 다음 다시 되돌립니다.

더 읽을거리

• 코딩 에이전트로 빠른 시작, 설치와 설정을 더 자세히 다룹니다
• GitHub의 potato-skill, 현재 v1.0.1
• 스킬 참고 자료
• 쇼케이스, 연구와 가까운 설계를 찾고 싶다면

참고 문헌

David Jurgens, Michael Chen, and Lina Iyer (2026). Potato 2.0: A Comprehensive Annotation Platform with AI-in-the-Loop Support. Proceedings of the 64th Annual Meeting of the Association for Computational Linguistics (Volume 3: System Demonstrations). https://aclanthology.org/2026.acl-demo.37/