Skip to content

potato-skill: 코딩 에이전트로 빠른 시작

라벨링이 필요한 것을 Claude Code, Codex, Cursor에 설명하면 potato-skill이 어노테이션 연구를 설계하고, 실행되는 Potato 작업으로 만든 다음, 어노테이터에게 제대로 렌더링되는지까지 확인합니다.

Potato 프로젝트를 시작하는 방법은 두 가지입니다. 빠른 시작에서 보여 주듯 작업을 직접 작성하거나, 연구 내용을 코딩 에이전트에게 설명하고 potato-skill이 설계하고 만들도록 맡길 수 있습니다. 이 페이지는 두 번째 방법을 다룹니다. 어느 쪽이든 도착하는 곳은 같습니다. 실행하고, 고치고, 공유할 수 있는 Potato 어노테이션 작업입니다.

스킬이 정하는 것

potato-skill은 에이전트 스킬입니다. 요청에 필요할 때 코딩 에이전트가 불러오는 지침과 보조 스크립트의 묶음입니다. 참고 파일 28개와 보조 스크립트 9개가 들어 있고, 작업을 만드는 일뿐 아니라 연구의 설계까지 다룹니다.

  • 어노테이터에게 무엇을 어떤 척도로 물을지
  • 항목마다 어노테이터가 몇 명 필요한지
  • 어노테이터를 어떻게 교육하고 작업을 어떻게 점검할지
  • 어노테이터가 보게 되는 인터페이스
  • 다음 단계에 필요한 형식으로 결과 내보내기

이 가운데 일부는 스킬이 스스로 정하고, 일부는 사람에게 돌려줍니다. 기준은 이렇습니다. 틀렸을 때 고치는 비용이 싼 결정은 그 자리에서 내리고, 틀렸을 때 비용이 크거나 되돌릴 수 없거나 애초에 에이전트가 내릴 결정이 아니면 사람에게 넘깁니다. 모든 점에 라벨이 붙은 5점 척도, 라벨이 9개 이하인 질문의 키보드 단축키, random_seed를 고정한 무작위 항목 순서, 모든 질문 필수는 스킬이 알아서 정합니다. 어노테이션 단위, 일치도를 보고할 예정일 때 항목당 어노테이터 수, 동의서 문구, "불명확" 선택지가 없는 라벨 집합은 사람에게 묻습니다.

만들어진 작업은 Potato에서 실행되므로 Potato가 이미 하는 일을 그대로 얻습니다. 어노테이터별 로그인, 항목당 여러 명의 어노테이터, 일치도 통계, Prolific과 MTurk 연동, 그리고 후속 도구가 읽는 형식으로의 내보내기입니다.

준비 사항

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

bash
pip install potato-annotation

코딩 에이전트도 필요합니다. 이 스킬은 Claude Code용으로 작성되었고, Codex와 Cursor에도 설치됩니다.

스킬 설치

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

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

Codex와 Cursor에서는 skills CLI가 작업 중인 프로젝트 안에 설치해 줍니다.

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

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를 쓰세요.

연구 설명하기

무엇에 라벨을 붙여야 하는지, 누가 라벨을 붙이는지, 라벨을 어디에 쓰는지 말해 주세요. Potato의 어노테이션 유형이나 설정 형식을 알 필요는 없습니다. 요청은 이 정도로 짧아도 됩니다.

트윗 200개에 대해 어노테이터 3명이 각각 5점 척도로 감정 라벨을 붙이게 하고 싶어. 동의 페이지와 주의력 확인 문항 2개를 넣어 줘. 만들어서 시작해 줘.

스킬이 질문 문구, 척도, 항목 배정 방식, 어노테이터 점검 방식을 정합니다. 확인받고 싶은 질문이 있다고 해서 제작을 멈추지는 않습니다. 가정을 밝히고, 작업을 만들고, 검증한 뒤, 이미 클릭해 볼 수 있는 결과물과 함께 질문을 내놓습니다.

인계 전에 에이전트가 실행하는 검사

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

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

--strict는 인식되지 않는 설정 키를 경고가 아니라 실패로 바꿔, 그대로 두면 기능을 조용히 꺼 버렸을 오타를 잡아냅니다. --screenshot은 실제 Potato 서버를 띄우고 헤드리스 Playwright로 조작하면서 콘솔 오류, 처리되지 않은 페이지 예외, 400 이상의 HTTP 응답을 기록합니다. 세 목록이 모두 비어 있을 때만 0으로 종료합니다.

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

다른 사람을 초대하기 전에 브라우저에서 작업을 열어 직접 몇 개 항목에 라벨을 붙여 보세요.

만들어지는 작업

Potato 작업은 작업의 설정, 데이터, 지침이 든 프로젝트 폴더입니다. 빠른 시작의 내용이 모두 그대로 적용됩니다. potato start config.yaml로 시작하고, 직접 고치고, 어노테이터를 추가하고, 라벨을 내보내면 됩니다.

결과가 Potato 작업 폴더이므로 다른 사람도 쓸 수 있습니다. 동료가 새 데이터로 같은 연구를 실행할 수도 있고, 내년에 다시 실행할 수도 있으며, 그 작업을 사용한 논문과 함께 공개할 수도 있습니다. 쇼케이스는 이런 방식으로 공유된 작업을 발표된 논문에서 모은 것입니다.

기존 설계와 어노테이션

  • 발표된 설계. 스킬은 발표된 논문에서 가져온 어노테이션 설계 440개 중 하나에서 시작할 수 있으며, 라벨 집합과 질문 문구와 지침이 함께 딸려 옵니다. 쇼케이스에서 둘러볼 수 있고, find_design.py가 설명한 것과 가까운 설계를 여기서 찾아 줍니다.
  • 다른 도구의 어노테이션. potato import가 Labelbox, CVAT, COCO를 포함해 형식 20가지를 읽으므로, 중간까지 진행된 프로젝트를 Potato에서 이어 갈 수 있습니다.
  • 이미 진행 중인 연구. study_status.py가 어노테이터별 진행 상황과 질문별 일치도를 보고하고, 스킬은 연구 도중에 어떤 수정이 안전하고 어떤 수정이 이미 수집된 데이터를 망가뜨리는지 말해 줍니다.

Potato의 MCP 서버

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

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

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

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

참고 자료는 davidjurgens.github.io/potato-skill에 공개되어 있어서 아무것도 설치하지 않고 읽어 볼 수 있습니다. Anthropic은 어떤 스킬이든 설치하기 전에 검토할 것을 권고합니다.

두 방법 비교

두 방법은 무엇에서 시작하느냐가 다를 뿐, 무엇으로 끝나느냐는 같습니다.

작업 직접 작성코딩 에이전트에게 설명
시작점YAML 설정평범한 말로 쓴 설명
적합한 경우Potato 익히기, 소규모 작업새 연구, 교육과 점검이 포함된 크라우드소싱 연구, 써 본 적 없는 어노테이션 유형
결과Potato 작업Potato 작업

언제든지 방법을 바꿀 수 있습니다. 직접 작성한 작업을 에이전트가 고칠 수도 있고, 에이전트가 만든 작업을 직접 고칠 수도 있습니다.

질문

아래 질문은 코딩 에이전트에서 potato-skill을 설정하는 방법과 소스를 찾는 곳을 다룹니다.

코딩 에이전트로 Potato를 쓰려면 어떻게 하나요?

에이전트가 명령을 실행하는 곳에 Potato와 potato-skill을 설치한 다음, 평범한 말로 에이전트에게 연구를 설명하면 됩니다. Potato는 pip install potato-annotation으로 설치합니다. Claude Code에서는 /plugin marketplace add davidjurgens/potato-skill에 이어 /plugin install potato-skill@potato를 실행하면 스킬이 설치되고, Codex나 Cursor에서는 npx skills add davidjurgens/potato-skill --agent codex cursor가 설치합니다. 무엇에 라벨을 붙여야 하는지, 누가 라벨을 붙이는지, 라벨을 어디에 쓰는지 에이전트에게 알려 주세요. potato-skill은 작업을 만들고, 렌더링해서 제대로 동작하는지 확인한 뒤, 대신 내린 결정 목록을 돌려줍니다.

GitHub에서 potato-skill은 어디에 있나요?

potato-skill은 github.com/davidjurgens/potato-skill에 있으며 GPL-3.0-or-later로 배포됩니다. 참고 자료는 davidjurgens.github.io/potato-skill에 공개되어 있으므로, 설치하기 전에 스킬이 에이전트에게 무엇을 지시하는지 읽어 볼 수 있습니다.

다음 단계