Agent Skill

Claude Code, Codex, Cursor 같은 AI 코딩 어시스턴트를 쓰고 있다면, SpicyAPI Skill이 그 어시스턴트에게 SpicyAPI를 제대로 다루는 법을 가르쳐 줍니다. 설치는 한 번이면 됩니다. 그다음부터는 "내 앱에 SpicyAPI 이미지 생성 기능을 추가해 줘"라고만 말해도 어시스턴트가 짐작에 기대지 않고 SpicyAPI의 규칙을 따릅니다.

이 페이지를 따라 하는 데 개발자일 필요는 없습니다. 터미널에 명령을 붙여 넣을 수 있다면 Skill을 설치할 수 있습니다.

Skill이란

Skill은 사람이 아니라 AI 어시스턴트가 읽도록 쓴 지침을 모아 둔 폴더입니다. 새로 온 동료에게 건네는 업무 매뉴얼이라고 생각하면 됩니다. 매뉴얼이 직접 일을 하지는 않지만, 일을 맡은 사람에게 어떤 단계를 어떤 순서로 밟아야 하는지, 무엇은 절대 하면 안 되는지 알려 줍니다.

AI 어시스턴트는 프로그래밍 전반에 대해서는 많이 알지만, SpicyAPI만의 규칙에 대해서는 믿을 만한 지식이 없습니다. 짐작에 맡겨 두면 어시스턴트가 이런 일을 할 수 있습니다.

• 존재하지 않는 모델 ID나 입력 필드를 지어냅니다.
• API 키를 코드에 그대로 붙여 넣습니다.
• 네트워크가 잠깐 끊긴 뒤 같은 유료 요청을 두 번 보내서 비용을 두 번 냅니다.
• 며칠 뒤면 열리지 않는 결과 링크를 건네줍니다.

Skill을 설치하면 어시스턴트는 일을 시작하기 전에 SpicyAPI의 규칙부터 읽습니다. 실제로는 이렇게 작동합니다.

1. Skill 폴더는 어시스턴트가 세션을 시작할 때 확인하는 위치에 놓입니다.
2. 어시스턴트는 Skill의 한 단락짜리 요약을 읽고, 요청이 SpicyAPI와 관련되면 전체 지침을 엽니다. 요청할 때 Skill 이름을 말할 필요는 없습니다.
3. 코드를 작성하거나 명령을 실행하는 동안 그 지침을 따릅니다.

미리 알아 두면 좋은 사실이 세 가지 있습니다.

• 텍스트뿐입니다. Markdown과 YAML 파일만 들어 있습니다. 프로그램도 스크립트도 없고, 설치할 때 실행되는 것도 없습니다. 모든 파일을 텍스트 편집기로 열어 볼 수 있습니다. 구성 파일을 보세요.
• API 키가 들어 있지 않고 아무것도 호출하지 않습니다. Skill 혼자서는 내 계정에 접근하거나 돈을 쓸 수 없습니다.
• 무료 오픈 소스입니다. MIT 라이선스이며 npm에 @spicyapi/skill로 공개되어 있고, github.com/spicyapi-ai/spicy-skill에서 개발됩니다.

Skill, MCP, SDK, CLI

SpicyAPI의 공식 도구는 네 가지입니다. 각각 다른 문제를 해결하며, 함께 쓰도록 설계되었습니다.

Skill은 이 중 어느 것도 대신하지 않습니다. 어시스턴트에게 그 도구들을 어떻게 쓰는지 알려 줄 뿐입니다. MCP 도구가 연결되어 있으면 MCP 도구를, 일회성 작업에는 CLI를, 애플리케이션에 들어갈 코드에는 내 언어의 SDK를 쓰게 합니다.

• Skill만 있을 때. 어시스턴트가 프로젝트에 맞는 올바른 연동 코드를 작성하지만, 내 계정에서 무언가를 조회하거나 작업을 대신 실행하지는 못합니다.
• MCP만 있을 때. 어시스턴트가 내 계정에서 움직일 수는 있지만, 올바른 단계 순서를 매번 스스로 알아내야 합니다.
• 둘 다 있을 때. 어시스턴트가 직접 해 볼 수 있고, 동시에 문서에 정해진 방식대로 합니다. 어시스턴트가 실제 작업을 실행하게 하고 싶다면 둘 다 설치하세요. 서로 충돌하지 않습니다.

도움이 되는 일

왼쪽 열은 내가 요청하는 일이고, 오른쪽 열은 그 일을 처리하는 동안 Skill이 어시스턴트에게 지키게 하는 것입니다.

하지 않는 일

• 혼자서 돈을 쓰지 않습니다. Skill은 텍스트라서 아무것도 호출할 수 없습니다. 어시스턴트에게 MCP 서버나 CLI와 API 키가 함께 있다면 유료 작업을 만들 수 있습니다. Skill은 먼저 가격을 보여 주고 명시적인 확인을 받으라고 지시합니다. 단, 내 요청이 바로 그 유료 실행을 이미 분명히 허락했다면 예외입니다. MCP 서버를 쓰면 여기에 더해, 모든 유료 동작이 어시스턴트가 건너뛸 수 없는 확인 단계에서 한 번 더 멈춥니다.
• 기능을 지어내지 않습니다. 작업 취소, 작업 기록 삭제, 웹훅 재전송처럼 공개 API가 제공하지 않는 기능을 호출하는 코드는 작성하지 않습니다.
• 계정 설정을 건드리지 않습니다. 가입, 로그인, 결제, 충전, 팀원 관리, 개인정보 요청, 계정 해지는 SpicyAPI 콘솔에서 합니다. 어시스턴트는 이런 일을 자동화하려 하지 않습니다.
• 테스트를 꾸며 내지 않습니다. 실제 테스트를 요청하면 실제 요청을 보내고(비용이 들 수 있으며, 그럴 때는 내 확인을 받은 뒤에 보냅니다) 실제로 일어난 일을 보고합니다. 모의(mock) 테스트가 통과했다고 "검증됨"으로 보고하는 일은 없습니다.
• 콘텐츠 설정을 추가하지 않습니다. SpicyAPI에는 콘텐츠 모드 플래그도, 요청별 콘텐츠 검토도 없으며, Skill도 그런 것을 지어내지 않습니다. 무엇을 할 수 있는지는 내가 고른 모델이 정합니다.

시작하기 전에

네 가지가 필요합니다. 설치에는 앞의 세 가지만 있으면 됩니다.

1. Agent Skills를 지원하는 AI 코딩 어시스턴트. Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Windsurf를 비롯해 많은 어시스턴트가 지원합니다. Skill은 여러 도구에서 두루 쓰이는 Agent Skills 폴더 형식을 따르므로, 이 형식을 읽는 어시스턴트라면 어디서든 작동합니다. 내 어시스턴트가 지원하는지 모르겠다면 그 어시스턴트의 문서에서 "skills"를 검색해 보세요.

2. Node.js 22 이상. npx 명령이 여기에 들어 있습니다. 다음 명령으로 확인하세요.

   node --version

   skills 설치 프로그램은 현재 Node.js 22.20 이상을, 패키지 자체 설치 프로그램은 22.13 이상을 요구합니다. 명령을 찾을 수 없거나 버전이 더 낮다면 nodejs.org에서 LTS 버전을 설치하고 터미널을 새로 여세요.

3. 터미널. macOS에서는 터미널 앱, Windows에서는 PowerShell입니다. 프로젝트별로 설치하려면 프로젝트 폴더에서 명령을 실행하세요.

4. API 호출을 시작할 때 쓸 SpicyAPI API 키. Skill 설치에는 필요 없습니다. 콘솔에서 키를 만드세요. 키는 sk-spicy-로 시작하며 한 번만 표시됩니다. SPICY_API_KEY라는 환경 변수에 저장하고, 키 자체를 어시스턴트와의 채팅에 절대 붙여 넣지 마세요. 인증을 보세요.

설치

설치 방법은 두 가지이며, 어느 쪽이든 같은 파일이 설치됩니다. 특별한 이유가 없다면 첫 번째 방법을 쓰세요.

npx skills add spicyapi-ai/spicy-skill

# Claude Code, 이 프로젝트에만
npx skills add spicyapi-ai/spicy-skill --agent claude-code

# Codex, 모든 프로젝트
npx skills add spicyapi-ai/spicy-skill --agent codex -g

# Claude Code와 Codex, 모든 프로젝트, 질문 없이
npx skills add spicyapi-ai/spicy-skill --agent claude-code codex -g -y

작동하는지 확인하기

npx skills list      # 현재 프로젝트에 설치된 Skill
npx skills list -g   # 모든 프로젝트용으로 설치된 Skill

요청 예시

아래 예시 중 하나를 어시스턴트에 붙여 넣고 세부 사항을 바꿔 쓰세요. 요청에 SpicyAPI를 넣어야 어시스턴트가 Skill을 적용할 상황이라는 것을 압니다.

쓰고 싶은 모델이 이미 정해져 있다면, 모델 페이지의 API 탭이나 인증된 실시간 카탈로그(GET /api/v1/models)에서 정확한 ID를 복사해 요청에 넣으세요. 예시에서는 그 ID가 들어갈 자리에 MODEL_ID_FROM_CATALOG라고 적었습니다. 이것은 실제 ID가 아니라 자리 표시자입니다. 쓸 ID가 없다면 실시간 카탈로그에서 골라 달라고 어시스턴트에게 부탁하세요. 모델 카탈로그와 스키마를 보세요.

Next.js 앱에 이미지 엔드포인트 추가하기

내 Next.js 앱에 서버 측 API 라우트를 추가해 줘. 텍스트 프롬프트를 받아서 SpicyAPI의 MODEL_ID_FROM_CATALOG 모델로 이미지를 생성하고, 결과를 기다렸다가 이미지 링크를 돌려주면 돼. API 키는 SPICY_API_KEY에서 읽어.

Skill이 어시스턴트에게 챙기게 하는 것:

• 키는 SPICY_API_KEY에 담긴 채 내 서버에만 머뭅니다. 웹 페이지는 내 라우트를 호출할 뿐, 키를 들고 SpicyAPI를 직접 호출하지 않습니다.
• 요청을 만들기 전에 실시간 카탈로그에서 그 모델의 현재 입력 필드를 읽습니다.
• 먼저 정확한 견적을 받아 예상 비용과 최대 청구 금액을 보여 줍니다. 유료 요청에는 확인받은 그 견적이 함께 실립니다.
• 생성 한 건에 멱등 키를 하나 만들고, 요청이 시간 초과되면 그 키를 다시 씁니다.
• 마감 시간을 정해 기다린 다음 작업의 state를 확인합니다. 기다림이 끝났다고 해서 생성이 성공한 것은 아니기 때문입니다.

Express에서 웹훅으로 결과 받기

내 Express 서버에 SpicyAPI 작업 결과를 받는 웹훅 엔드포인트를 추가해 줘. SPICY_WEBHOOK_SECRET으로 서명을 검증하고, 결과 링크를 내 데이터베이스에 저장해.

• 요청을 JSON으로 파싱하기 전에, 받은 그대로의 원본 요청 본문으로 서명을 검증합니다.
• 같은 이벤트가 두 번 이상 도착할 수 있으므로, 전달에 붙은 request_id로 중복을 무시합니다.
• 완전하고 검증된 웹훅에서는 추가 조회 없이 결과를 바로 읽습니다.

완성된 영상을 내 저장소로 복사하기

SpicyAPI 영상 작업이 성공하면 영상을 내려받아 내 S3 버킷에 올리고, SpicyAPI 링크 대신 내 링크를 저장해 줘.

• 결과 링크는 임시이고 생성된 파일은 약 14일 동안만 보관되므로, 내가 관리하는 곳에 오래 남는 사본을 저장합니다.
• 결과 링크에서 내려받을 때는 API 키를 보내지 않습니다.
• 링크가 만료되었다면 SpicyAPI에 같은 작업을 다시 조회해 새 링크를 받습니다. 링크를 얻으려고 새 작업을 만드는 일은 없습니다.

사용자의 사진을 영상으로 바꾸기

내 앱에서 사용자가 사진을 올리면 SpicyAPI로 짧은 영상을 만들어 주게 해 줘.

• 파일을 base64로 요청에 붙여 넣지 않고, 먼저 SpicyAPI에 업로드한 뒤 돌아온 spicy:// 주소를 요청에 넣습니다.
• 업로드 제한을 지킵니다. 이미지는 10 MiB, MP4·WebM 영상과 MP3·WAV 오디오는 90 MiB까지입니다.
• 이미 공개 HTTPS 링크로 올라가 있는 사진은 업로드하지 않고 그대로 넘길 수 있습니다.

재시도와 잔액 부족 처리하기

내 SpicyAPI 연동이 실패 상황을 처리하게 해 줘. 네트워크 시간 초과는 두 번 과금되지 않게 재시도하고, 계정 잔액이 부족하면 알기 쉬운 메시지를 보여 주고, 레이트 제한에 걸리면 속도를 늦춰.

• 시간 초과 뒤에는 같은 멱등 키로 재시도하므로, 재시도가 두 번째 유료 작업을 만들 수 없습니다.
• "잔액 부족"(코드 40201)은 재시도하지 않습니다. 사용자에게는 알기 쉬운 메시지가 보이고, 나는 콘솔에서 충전합니다.
• 다시 시도하기 전에 Retry-After가 알려 준 시간만큼 기다립니다.
• 견적이 만료되었거나 가격이 바뀌었다면(코드 40901) 가격 확인을 건너뛰지 않고, 새 견적을 받아 나에게 다시 묻습니다.
• 실패한 작업을 재시도하면 새 작업이 만들어져 다시 과금될 수 있다는 것을 알기 때문에, 내가 새로 시도하기를 원할 때만 재시도합니다.

여러 건 한꺼번에 생성하기

products.csv에 있는 상품 20개의 제품 사진을 SpicyAPI로 생성해 줘. 한 번에 최대 3개씩 실행하고, 작업 ID를 하나하나 기록해.

• SpicyAPI에는 일괄 처리 엔드포인트가 없으므로, 동시에 실행하는 요청 수를 제한합니다.
• 항목마다 멱등 키와 가격을 따로 둡니다.
• 작업이 접수되는 즉시 작업 ID를 기록합니다.
• 한 항목이 시간 초과되면 그 항목만 복구하고, 배치 전체를 다시 제출하는 일은 없습니다.

구성 파일

설치된 폴더는 다음과 같이 생겼습니다.

spicyapi/
├── SKILL.md
├── references/
│   ├── api-workflows.md
│   └── safety.md
└── agents/
    └── openai.yaml

어시스턴트는 작업에 필요할 때만 두 참고 파일을 열기 때문에, 작업 기억 공간을 내 프로젝트에 넉넉히 쓸 수 있습니다. 설치하기 전에 파일을 읽어 보려면 npx @spicyapi/skill path를 실행하세요. 패키지가 파일을 보관하는 폴더가 출력됩니다.

Skill은 어시스턴트에게 아래 환경 변수로 내 코드와 도구를 설정하라고 지시합니다. Skill 자체는 이 중 어느 것도 읽지 않습니다.

업데이트와 제거

업데이트

Skill은 SpicyAPI가 권장하는 작업 방식이 바뀌면 함께 바뀌지만, 설치된 사본은 저절로 업데이트되지 않습니다. 설치된 폴더에는 버전 번호가 없으므로, 최신 상태인지 확실히 하는 가장 간단한 방법은 다시 설치하는 것입니다.

• npx skills add로 설치했다면: 같은 범위와 같은 어시스턴트로 같은 명령을 다시 실행하세요. 설치된 파일이 그 시점의 저장소 내용으로 교체됩니다. 변경은 공개되는 즉시 반영되므로 기다릴 필요가 없습니다.

• 패키지 설치 프로그램으로 설치했다면: --force와 처음과 같은 --target을 붙여 다시 실행하세요. @latest를 붙이면 npx가 캐시된 패키지를 다시 쓰지 않고 최신 패키지를 받아 옵니다.

  npx @spicyapi/skill@latest install --target ~/.claude/skills/spicyapi --force

제거

Skill을 제거해도 SpicyAPI 계정, API 키, 어시스턴트가 이미 작성한 코드에는 아무 영향이 없습니다.

• npx skills add로 설치했다면: 설치할 때와 같은 프로젝트 폴더에서 아래 명령을 실행하세요. 전역으로 설치했다면 -g를 붙입니다. 그런 다음 spicyapi 폴더가 사라졌는지 확인하세요.

  npx skills remove spicyapi

• 패키지 설치 프로그램으로 설치했다면: spicyapi 폴더를 삭제하세요. Finder나 파일 탐색기에서 지워도 되고, 터미널에서 지워도 됩니다.

  # macOS와 Linux: 실제로 설치한 폴더를 지정하세요
  rm -rf ~/.agents/skills/spicyapi

  # Windows PowerShell
  Remove-Item -Recurse -Force "$HOME\.agents\skills\spicyapi"

  Enter를 누르기 전에 경로를 두 번 확인하세요. 경로는 반드시 spicyapi로 끝나야 합니다.

제거한 뒤에는 새 세션을 시작해야 어시스턴트가 더 이상 Skill을 쓰지 않습니다.

문제 해결

소스

이 패키지는 MIT 라이선스이고 **github.com/spicyapi-ai/spicy-skill**에서 공개적으로 개발됩니다. Skill이 실제로 설치하는 지시문을 읽거나, 문서와 다르게 동작하는 부분을 알리거나, 변경을 제안하는 일 모두 저장소에서 하면 됩니다.

다음 단계