Communitygithub.com

wwwyo/syokan

syokan — LLM이 풍부한 UI를 소환합니다. JSON 주문을 외치면 살아있는 인터페이스가 나타납니다. 본질적으로 임시적입니다.

syokan란 무엇인가요?

이 스킬은 syokan(召喚, '소환')이라는 스키마 기반 뷰 레이어를 통해 LLM이 JSON 인캔테이션(incantation)만으로 동적인 UI를 생성하고 표시할 수 있게 해줍니다. 사용자가 "syokan X" 혹은 "X를 syokan"이라고 말하면, 해당 데이터를 뷰로 소환하는 요청으로 해석됩니다. syokan은 미리 정의된 컴포넌트 카탈로그를 기반으로 하며, JSX 대신 JSON 트리를 조립해 POST하면 즉시 렌더링됩니다. 주로 Claude Code, Cursor, Codex 등 LLM 기반 도구에서 사용되며, CLI 명령어(`syokan catalog`, `syokan snapshot.json` 등)를 통해 컴포넌트 조회, 스냅샷 전송, 템플릿 관리 등을 수행합니다. 핵심 특징은 스냅샷이 영구 저장되지 않는 일시적(ephemeral) 설계로, 재구성 가능한 임시 데이터(오늘의 RSS, 진행 중인 리뷰 등)에 적합하며, 재사용이 필요한 레이아웃은 템플릿으로 저장해 반복 재현할 수 있습니다. 또한 로컬 파일을 직접 전달하면 실시간 편집 추적 기능도 제공합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add wwwyo/syokan

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

syokan은(는) 무엇을 하나요?

syokan(召喚, "소환")은 동사입니다 — LLM이 풍부한 UI를 소환합니다. 사용자가 "syokan X"(일본어: 「X를 syokan」)라고 말하면, 해당 데이터를 뷰로 소환하라는 요청입니다. 내부적으로는 스키마 기반 뷰 레이어로, JSX를 작성하는 대신 JSON 주문(카탈로그 컴포넌트의 트리)을 말하면 syokan이 미리 정의된 컴포넌트로 렌더링합니다. 당신의 작업은 데이터를 엔벨로프로 조립하여 syokan에 POST하는 것입니다. 산문에서 syokan은 타동사로 사용하십시오("do syokan" / 「syokan する」는 절대 사용하지 않음 — syokan은 그 자체로 동사입니다).

syokan이 아직 설치되지 않았거나(syokan --help 실패), 사용자가 "onboarding", "set it up", "처음 사용"이라고 말하면 references/onboarding.md를 따라 첫 번째 스냅샷까지 안내하십시오. 환경을 변경하는 작업(예: 설치)은 자동으로 실행하지 말고, 설치되지 않았다고 보고한 후 사용자의 승인을 받은 후에만 실행하십시오(절대 자체적으로 설치하지 마십시오).

필수 사항

  • 스냅샷은 일시적(ephemeral)입니다: 게시된 스냅샷은 지속성이 보장되지 않습니다. 재구성 가능하고 일시적인 데이터(오늘의 RSS, 진행 중인 리뷰 등)만 넣으십시오. 재사용하는 레이아웃의 경우 템플릿을 저장하여 재현하십시오(템플릿은 지속됩니다 — 아래 "재현성을 위한 템플릿" 참조).
  • JSON만 허용: 서버는 JSON 엔벨로프만 수락합니다. 원시 마크다운이나 일반 텍스트는 거부됩니다. 산문을 표시하려면 MarkdownDoc 또는 PlainText 노드로 감싸십시오.
  • 엄격한 스키마: props는 엄격하게 검증됩니다. 스키마에 없는 키는 거부됩니다 — 추가 키를 임의로 생성하지 마십시오.
  • 리프(leaf) 노드는 자식을 가질 수 없음: Stack과 Card만 자식을 허용합니다. 리프 노드에 자식을 첨부하면 수집 시 거부됩니다.

구성부터 보기까지

  1. syokan catalog로 사용 가능한 타입과 props를 확인하십시오(아래 "카탈로그" 참조).
  2. 표시하려는 데이터를 해당 컴포넌트에 매핑하십시오. 최상위 레벨은 일반적으로 컨테이너(Stack 등)로, 항목을 세로로 쌓습니다.
  3. 엔벨로프 JSON으로 변환하십시오(아래 "엔벨로프 형태" 참조). root만 필수입니다.
  4. CLI로 게시하십시오(아래 "게시" 참조). 성공하면 뷰 URL이 출력됩니다.

이전에 유사한 뷰를 구축한 적이 있다면 처음부터 시작하지 말고 저장된 템플릿을 기반으로 하십시오(아래 "재현성을 위한 템플릿" 참조).

엔벨로프 형태

POST 본문에는 다음만 포함될 수 있습니다. id, createdAt, url은 절대 포함하지 마십시오 — 서버가 할당합니다.

{
  "root": { "type": "Stack", "props": {}, "children": [ /* 카탈로그 노드; 전체 예제는 references/examples.md 참조 */ ] }, // 필수. 뷰 트리
  "title": "오늘의 RSS",                                // 선택 사항. 목록과 뷰 헤더에 표시
  "metadata": { "source": { "label": "daily-rss" } },   // 선택 사항. 출처 레이블
  "schemaVersion": 1,                                    // 선택 사항. 서버가 채움
  "idempotencyKey": "rss-2026-06-28"                     // 선택 사항. 이 뷰에 이름을 부여하여 나중에 중복 없이 새로고침 가능
}

metadata.source는 label 외에 추가 키를 유지할 수 있습니다. url 또는 fetchedAt을 추가할 수 있습니다(예: { "label": "gh-review", "url": "https://example.com/..." }).

일일 또는 반복 뷰의 경우 idempotencyKey에 날짜 등을 포함하십시오. syokan CLI가 나머지를 처리합니다: 먼저 해당 키를 대상으로 하고, 기존 뷰가 없을 때만 새 뷰를 생성합니다. 따라서 첫 번째 게시는 뷰를 생성하고, 동일한 키로 이후 게시할 때마다 중복 없이 동일한 뷰를 제자리에서 새로고침합니다. 첫 번째 게시인지 직접 추적할 필요가 없습니다. (CLI 대신 HTTP API를 직접 호출하는 경우: POST /api/snapshots는 항상 생성하고 키를 태깅합니다. PUT /api/snapshots는 기존 키를 대상으로 하며, 키가 없으면 404를 반환합니다 — 존재하지 않으면 생성하는 엔드포인트는 없으므로, CLI는 먼저 PUT을 시도하고 404에서 POST로 폴백합니다.)

카탈로그

사용 가능한 type과 해당 props 정의는 syokan catalog에서 가져오십시오 (md로 옮겨 적지 말고 — 매번 여기서 가져오십시오).

출력은 { "items": [{ "type", "props", "childrenTypes" }] }입니다.

  • props: JSON 스키마로 된 타입의 props입니다. required / enum / format (httpUrl은 uri, Time.datetime은 date-time) / additionalProperties:false (알 수 없는 키는 거부)를 정확히 충족하십시오.
  • childrenTypes: null은 자식을 허용하는 컨테이너, []는 자식을 허용하지 않는 리프, [..]는 나열된 타입만 자식이 될 수 있음을 의미합니다.

컴포넌트를 결합한 완전한 예제는 references/examples.md를 참조하십시오.

게시

조립된 엔벨로프를 파일 또는 stdin으로 전달하십시오. 성공하면 뷰 URL이 stdout에 출력됩니다(syokan snapshot.json / cat snapshot.json | syokan / claude -p '…JSON…' | syokan).

그 외 모든 것 — 명령어, 하위 명령어, 환경 변수, 종료 코드 — 은 syokan --help --json을 참조하십시오. 타입과 props는 syokan catalog를 참조하십시오.

로컬 파일 미리보기

로컬 파일의 경우 syokan <path>가 가장 짧은 경로입니다 — 파일 자체를 syokan합니다. 엔벨로프 JSON은 그대로 게시되며, 그 외(마크다운 / 로그 / txt / json 등)는 라이브 FileDoc에 자동으로 래핑됩니다. CLI는 이를 절대 경로로 변환하여 서버에 전달하며, 서버는 내용을 읽고 확장자에서 형식을 추론합니다(.md/.markdown → 마크다운, .json → 코드, 나머지 → 텍스트). 뷰가 열려 있는 동안 파일 수정을 추적합니다 (재게시 불필요).

syokan notes.md   # 마크다운 렌더링; 저장할 때마다 뷰 새로고침
syokan app.log    # 모노스페이스로 증가하는 로그 표시

여러 파일을 하나의 뷰로 결합하거나 Heading 및 다른 노드와 혼합하려면 직접 FileDoc 노드를 배치하십시오(props: path, 절대 경로만; FileDoc이 읽기 및 변경 추적을 처리합니다).

반대로, 파일 내용을 정적으로 고정(추적 불필요하거나 내용을 변환하는 경우)하여 표시하려면 본문을 MarkdownDoc / PlainText / Code 노드에 넣으십시오. jq --rawfile을 사용하면 JSON 이스케이프에 신경 쓰지 않고 스트리밍할 수 있습니다.

jq -n --rawfile body README.md \
  '{title:"README.md", root:{type:"Stack",props:{},children:[{type:"MarkdownDoc",props:{body:$body}}]}}' \
  | syokan

재현성을 위한 템플릿

즐겨 사용하는 뷰를 매번 처음부터 다시 만들지 말고 — syokan에 템플릿으로 저장하여 재사용하십시오. 템플릿은 "저장된 엔벨로프 자체"입니다. 스켈레톤에 {{...}}와 같은 마커를 넣고 직접 채울 수 있습니다.

일치하는 템플릿이 있으면 처음부터 만들지 마십시오: 목록에서 id를 찾아 → 가져온 다음 → 데이터를 교체하고 → 게시하십시오. 보관할 가치가 있는 새 뷰를 만들면 저장하고 다음에 재현하십시오. 하위 명령어 구문(templates list|add|get|rm)은 syokan --help --json을 참조하십시오.

관련 스킬