Sume Format 레시피용 SKILL.md 파일 작성법

Sume Format용 SKILL.md 파일을 쓰려면, 레시피에서 오래 유지되는 '어떻게'(하우스 스타일, 분기 규칙, 품질 기준)를 패키지 루트의 짧은 SKILL.md에 담고, 세부 내용은 references/ 아래 파일로 옮기고, frontmatter의 name을 Format의 slug로 설정하세요. 그러면 각 API 호출은 '무엇을', 즉 instruction과 input만 전달합니다.

아래의 패키지 규칙과 조합 순서는 2026-09-26에 확인한 Sume 문서 Format API (영문)와 Format 패키지 편집하기 페이지에서 가져왔습니다. Format이 무엇인지부터 알고 싶다면 Sume Format이란?을 참고하세요.

SKILL.md에는 무엇을 넣고, API 호출에는 무엇을 넣나요?

문서는 Format 실행을 레시피와 호출로 나눕니다. SKILL.md 본문과 참고 파일로 된 레시피는 '어떻게'입니다. 하우스 스타일, 분기 규칙, 품질 기준이 여기에 해당합니다. instruction과 input으로 된 호출은 '무엇을'입니다. 제품 URL, 브리프, 대본, 가격이 여기에 해당합니다. 레시피가 지시문보다 먼저 자리 잡으므로, 호출할 때마다 시스템 프롬프트를 다시 보내고 그것이 지켜지기를 바라는 방식이 아닙니다.

호출 쪽의 두 가지 사실도 같은 방향을 가리킵니다. instruction은 8000자까지 받지만 프롬프트 텍스트로 전달되는 것은 앞 ~4000자뿐이고, 패키지는 통째로 첨부됩니다. 또 호출자는 instruction을 생략할 수 있으며, 그러면 Format 자체의 기본 지시문이 실행됩니다. 고객 데이터는 AI 에이전트 API에 데이터 넘기기에서 다룬 대로 input에 넣으세요.

에이전트는 레시피를 어떻게 받나요?

모든 실행은 에이전트가 받는 내용을 아래 순서로 조합합니다. 본문은 절대 인라인되지 않습니다. 에이전트는 포인터를 받고, 패키지 전체는 실행 워크스페이스의 디스크에 놓입니다.

Format은 '어떻게'이므로 먼저 옵니다. 실행 지시문은 그 뒤에 오므로, 둘이 어긋나면 모델은 지시문을 따릅니다. 호출자가 실행 한 번에 한해 SKILL.md를 덮어쓸 수 있다는 점을 알고 작성하세요. 실행이 무엇을 받았는지 확인하려면 에이전트 탭에서 그 실행의 thread_id를 여세요. 첫 메시지가 바로 이 텍스트입니다.

[Format: product-promo v12]         <- a pointer at the recipe; the body is never inlined
[Format attached: … SKILL.md]       <- the whole package, on disk in the run's workspace
[Format run instruction]            <- your `instruction`, or the Format's default
[Sume unattended run]               <- API and scheduled runs only
[Sume action input]                 <- a pointer at your `input`, written whole to a file
[Attached files]                    <- your `attachments`, when present

SKILL.md는 얼마나 길어야 하나요?

모든 패키지 파일이 공유하는 파일당, 패키지당 100 MiB 외에는 본문 크기 제한이 없습니다. 크기가 바꾸는 것은 레시피가 실행되는지가 아니라 얼마나 충실히 지켜지는지입니다. 그래서 문서는 SKILL.md를 에이전트가 한 번에 붙잡을 수 있는 짧은 색인으로 두고, 세부 내용은 references/*로 밀어내라고 조언합니다. 그 파일들은 SKILL.md 옆에 놓이며, 열리기 전까지는 비용이 들지 않습니다.

Format 패키지에는 무엇을 담을 수 있나요?

Contents API는 대시보드 편집기와 같은 규칙을 강제합니다. 규칙을 하나라도 어긴 패키지는 아무것도 커밋되기 전에 거부됩니다. 잘못된 경로에는 skill_path_invalid가 허용 목록 전체를 함께 돌려주고, 그 밖의 위반으로는 skill_frontmatter_invalid와 skill_limit_exceeded가 있습니다. Format의 description도 SKILL.md frontmatter에 있습니다. API 레퍼런스에 따르면 POST /v1/formats가 설명을 그곳에 쓰고, 이 파일이 단일 진실 공급원으로 남으며, 카탈로그는 이 파일에서 설명을 다시 읽어 옵니다.

API에서 레시피는 승인 게이트를 어떻게 다뤄야 하나요?

채팅에서 쓴 레시피는 “approve these stills before I make the video”(영상을 만들기 전에 이 스틸을 승인해 주세요)처럼 사람을 기다리며 멈출 수 있습니다. API에는 그 자리에 아무도 없으므로, 실행은 그런 승인이 이미 부여됐다는 안내를 받고 지출 상한 안에서 유료 단계까지 계속 진행합니다. 그래서 SKILL.md에 있는 승인 게이트는 API 실행을 멈추지 않습니다.

정말로 끝낼 수 없는 실행은 반쯤 끝난 completed가 아니라 failed로 돌아옵니다. 문서의 예는 브리프에 맞는 아바타가 없을 때의 unattended_blocked입니다.

패키지는 어떻게 만들고 편집하나요?

채팅에서 에이전트에게 스레드의 레시피를 저장해 달라고 요청하거나(“이걸 product-promo라는 Format으로 저장해 줘”), 라이브러리에서 Format을 편집하거나, Contents API를 쓰세요. 본문은 호출자가 아니라 에이전트에게 전달됩니다. GET /v1/formats/…가 돌려주는 Format 레코드에는 본문이 빠져 있고, docs.sume.com의 Format 콜 시트도 본문을 절대 보여 주지 않습니다. 자기 패키지는 Contents API로 읽습니다.

• POST /v1/formats는 키의 워크스페이스에 Format을 만듭니다. auto_init(기본값 true)은 유효한 최소 SKILL.md를 커밋하며, 그 파일을 교체하는 것이 의도된 다음 호출입니다. API로 Sume Format 만들기를 참고하세요.
• PUT /v1/formats/{handle}/{slug}/contents/{path}는 base64로 인코딩한 파일 하나 전체를 커밋 하나로 씁니다. 경로가 이미 있으면 그 파일의 sha를 보내세요.
• 편집은 진행 중인 실행에 절대 영향을 주지 않습니다. 각 실행은 시작할 때의 패키지를 읽습니다. version은 편집할 때마다 올라가고, 영수증의 format.version이 어느 버전이 실행됐는지 알려 줍니다.