Communitygithub.com

Lev-it/lev-skills

JSON 사양을 인터랙티브 터미널 UI로 변환하는 Ink 터미널 렌더러입니다. @json-render/ink, 터미널 UI 구축, AI 생성 사양 렌더링에 사용하세요.

lev-skills란 무엇인가요?

이 스킬은 @json-render/ink 라이브러리를 사용하여 JSON 사양을 인터랙티브 터미널 컴포넌트 트리로 변환하는 기술입니다. 개발자는 50개 이상의 표준 컴포넌트(Box, Text, Table, Select, Spinner 등)를 활용해 복잡한 터미널 UI를 JSON 형식으로 선언적으로 정의할 수 있습니다. Ink 렌더러는 데이터 바인딩, 가시성 조건, 동적 속성, 액션 시스템을 지원하여 AI 에이전트가 생성한 사양을 그대로 터미널에서 렌더링할 수 있습니다. Cursor, Claude Code, Codex 등 다양한 AI 코딩 에이전트와 호환되며, 실시간 스트리밍, 폼 입력, 목록 반복 등 고급 기능도 제공합니다. 이 스킬을 사용하면 AI 에이전트가 복잡한 터미널 앱을 JSON 사양만으로 구축할 수 있어, React/Ink 코드를 직접 작성할 필요가 없어집니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Lev-it/lev-skills/tree/HEAD/.claude/skills/ink

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

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

문서

@json-render/ink

JSON 사양을 표준 컴포넌트, 데이터 바인딩, 가시성, 액션, 동적 속성을 갖춘 인터랙티브 터미널 컴포넌트 트리로 변환하는 Ink 터미널 렌더러입니다.

빠른 시작

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/ink/schema";
import {
  standardComponentDefinitions,
  standardActionDefinitions,
} from "@json-render/ink/catalog";
import { defineRegistry, Renderer, type Components } from "@json-render/ink";
import { z } from "zod";

// 표준 + 커스텀 컴포넌트로 카탈로그 생성
const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    CustomWidget: {
      props: z.object({ title: z.string() }),
      slots: [],
      description: "커스텀 위젯",
    },
  },
  actions: standardActionDefinitions,
});

// 커스텀 컴포넌트만 등록 (표준 컴포넌트는 내장)
const { registry } = defineRegistry(catalog, {
  components: {
    CustomWidget: ({ props }) => <Text>{props.title}</Text>,
  } as Components<typeof catalog>,
});

// 렌더링
function App({ spec }) {
  return (
    <JSONUIProvider initialState={{}}>
      <Renderer spec={spec} registry={registry} />
    </JSONUIProvider>
  );
}

사양 구조 (플랫 요소 맵)

Ink 스키마는 루트 키가 있는 플랫 요소 맵을 사용합니다:

{
  "root": "main",
  "elements": {
    "main": {
      "type": "Box",
      "props": { "flexDirection": "column", "padding": 1 },
      "children": ["heading", "content"]
    },
    "heading": {
      "type": "Heading",
      "props": { "text": "Dashboard", "level": "h1" },
      "children": []
    },
    "content": {
      "type": "Text",
      "props": { "text": "Hello from the terminal!" },
      "children": []
    }
  }
}

표준 컴포넌트

레이아웃

  • Box - Flexbox 레이아웃 컨테이너 (터미널 <div>와 유사). 그룹화, 간격, 테두리, 정렬에 사용합니다. 기본 flexDirection은 row입니다.
  • Text - 선택적 스타일(색상, 굵게, 기울임 등)이 있는 텍스트 출력
  • Newline - 빈 줄을 삽입합니다. 반드시 flexDirection이 column인 Box 안에 있어야 합니다.
  • Spacer - 주축을 따라 확장되는 유연한 빈 공간

콘텐츠

  • Heading - 섹션 제목 (h1: 굵게+밑줄, h2: 굵게, h3: 굵게+흐리게, h4: 흐리게)
  • Divider - 선택적 중앙 제목이 있는 수평 구분선
  • Badge - 색상이 있는 인라인 레이블 (변형: 기본, 정보, 성공, 경고, 오류)
  • Spinner - 선택적 레이블이 있는 애니메이션 로딩 스피너
  • ProgressBar - 수평 진행률 표시줄 (0-1)
  • Sparkline - 유니코드 블록 문자를 사용한 인라인 차트
  • BarChart - 레이블과 값이 있는 수평 막대 차트
  • Table - 헤더와 행이 있는 표 형식 데이터
  • List - 글머리 기호 또는 번호가 매겨진 목록
  • ListItem - 제목, 부제목, 앞/뒤 텍스트가 있는 구조화된 목록 행
  • Card - 선택적 제목이 있는 테두리 컨테이너
  • KeyValue - 키-값 쌍 표시
  • Link - 선택적 레이블이 있는 클릭 가능한 URL
  • StatusLine - 색상 아이콘이 있는 상태 메시지 (정보, 성공, 경고, 오류)
  • Markdown - 터미널 스타일로 마크다운 텍스트 렌더링

인터랙티브

  • TextInput - 텍스트 입력 필드 (이벤트: submit, change)
  • Select - 화살표 키 탐색이 있는 선택 메뉴 (이벤트: change)
  • MultiSelect - 스페이스바로 전환하는 다중 선택 (이벤트: change, submit)
  • ConfirmInput - 예/아니오 확인 프롬프트 (이벤트: confirm, deny)
  • Tabs - 왼쪽/오른쪽 화살표 키가 있는 탭 표시줄 탐색 (이벤트: change)

가시성 조건

요소에 visible을 사용하여 상태에 따라 표시/숨기기를 제어합니다. 문법: { "$state": "/path" }, { "$state": "/path", "eq": value }, { "$state": "/path", "not": true }, AND의 경우 { "$and": [cond1, cond2] }, OR의 경우 { "$or": [cond1, cond2] }.

동적 속성 표현식

모든 속성 값은 렌더링 시 해결되는 데이터 기반 표현식이 될 수 있습니다:

  • { "$state": "/state/key" } - 상태 모델에서 읽습니다 (단방향 읽기)
  • { "$bindState": "/path" } - 양방향 바인딩: 폼 컴포넌트의 자연스러운 값 속성에 사용합니다
  • { "$bindItem": "field" } - 반복 항목 필드에 대한 양방향 바인딩
  • { "$cond": <조건>, "$then": <값>, "$else": <값> } - 조건부 값
  • { "$template": "안녕하세요, ${/name}!" } - 문자열에 상태 값 보간

컴포넌트는 양방향 바인딩에 statePath 속성을 사용하지 않습니다. 대신 자연스러운 값 속성에 { "$bindState": "/path" }를 사용하세요.

이벤트 시스템

컴포넌트는 emit을 사용하여 명명된 이벤트를 발생시킵니다. 요소의 on 필드는 이벤트를 액션 바인딩에 매핑합니다:

CustomButton: ({ props, emit }) => (
  <Box>
    <Text>{props.label}</Text>
    {/* emit("press")는 사양의 on.press에 바인딩된 액션을 트리거합니다 */}
  </Box>
),
{
  "type": "CustomButton",
  "props": { "label": "제출" },
  "on": { "press": { "action": "submit" } },
  "children": []
}

내장 액션

setState, pushState, removeState는 내장되어 있으며 자동으로 처리됩니다:

{ "action": "setState", "params": { "statePath": "/activeTab", "value": "home" } }
{ "action": "pushState", "params": { "statePath": "/items", "value": { "text": "새 항목" } } }
{ "action": "removeState", "params": { "statePath": "/items", "index": 0 } }

반복 (동적 목록)

컨테이너 요소에 repeat 필드를 사용하여 상태 배열의 항목을 렌더링합니다:

{
  "type": "Box",
  "props": { "flexDirection": "column" },
  "repeat": { "statePath": "/items", "key": "id" },
  "children": ["item-row"]
}

반복되는 자식 내부에서는 { "$item": "field" }를 사용하여 현재 항목을 읽고 { "$index": true }를 사용하여 현재 인덱스를 읽습니다.

스트리밍

useUIStream을 사용하여 JSONL 패치 스트림에서 점진적으로 사양을 렌더링합니다:

import { useUIStream } from "@json-render/ink";

const { spec, send, isStreaming } = useUIStream({ api: "/api/generate" });

서버 측 프롬프트 생성

./server 내보내기를 사용하여 카탈로그에서 AI 시스템 프롬프트를 생성합니다:

import { catalog } from "./catalog";

const systemPrompt = catalog.prompt({ system: "당신은 터미널 어시스턴트입니다." });

제공자

제공자목적
StateProvider컴포넌트 간 상태 공유 (JSON Pointer 경로). 제어 모드를 위한 선택적 store 속성을 허용합니다.
ActionProvider이벤트 시스템을 통해 전달된 액션 처리
VisibilityProvider상태 기반 조건부 렌더링 활성화
ValidationProvider폼 필드 유효성 검사
FocusProvider인터랙티브 컴포넌트 간 포커스 관리
JSONUIProvider모든 컨텍스트를 위한 결합 제공자

외부 저장소 (제어 모드)

외부 상태 관리를 사용하려면 StateProvider (또는 JSONUIProvider)에 StateStore를 전달합니다:

import { createStateStore, type StateStore } from "@json-render/ink";

const store = createStateStore({ count: 0 });

<StateProvider store={store}>{children}</StateProvider>

store.set("/count", 1); // React가 자동으로 다시 렌더링합니다

store가 제공되면 initialState와 onStateChange는 무시됩니다.

createRenderer (상위 수준 API)

import { createRenderer } from "@json-render/ink";
import { standardComponents } from "@json-render/ink";
import { catalog } from "./catalog";

const InkRenderer = createRenderer(catalog, {
  ...standardComponents,
  // 여기에 커스텀 컴포넌트 재정의
});

// InkRenderer는 모든 제공자(상태, 가시성, 액션, 포커스)를 포함합니다
render(
  <InkRenderer spec={spec} state={{ activeTab: "overview" }} />
);

주요 내보내기

내보내기목적
defineRegistry카탈로그에서 타입 안전 컴포넌트 레지스트리 생성
Renderer레지스트리를 사용하여 사양 렌더링
createRenderer상위 수준: 내장 제공자가 있는 컴포넌트 생성
JSONUIProvider모든 컨텍스트를 위한 결합 제공자
schemaInk 플랫 요소 맵 스키마 (내장 상태 액션 포함)
standardComponentDefinitions모든 표준 컴포넌트에 대한 카탈로그 정의
standardActionDefinitions표준 액션에 대한 카탈로그 정의
standardComponents사전 구축된 컴포넌트 구현
useStateStore상태 컨텍스트에 접근
useStateValue상태에서 단일 값 가져오기
useBoundProp$bindState/$bindItem 표현식을 위한 양방향 바인딩
useActions액션 컨텍스트에 접근
useAction단일 액션 디스패치 함수 가져오기
useOptionalValidationuseValidation의 비-예외 변형
useUIStreamAPI 엔드포인트에서 사양 스트리밍
createStateStore프레임워크에 독립적인 인메모리 StateStore 생성
StateStore외부 상태 관리를 연결하기 위한 인터페이스
Components타입이 있는 컴포넌트 맵 (카탈로그 인식)
Actions타입이 있는 액션 맵 (카탈로그 인식)
ComponentContext타입이 있는 컴포넌트 컨텍스트 (카탈로그 인식)
flatToTree플랫 요소 맵을 트리 구조로 변환

터미널 UI 디자인 가이드라인

  • 레이아웃에는 Box를 사용하세요 (flexDirection, padding, gap). 기본 flexDirection은 row입니다.
  • 터미널 너비는 약 80-120열입니다. 주요 구조에는 수직 레이아웃(flexDirection: column)을 선호하세요.
  • 시각적 그룹화를 위해 Box에서 borderStyle을 사용하세요 (single, double, round, bold).
  • 명명된 터미널 색상을 사용하세요: red, green, yellow, blue, magenta, cyan, white, gray.
  • 섹션 제목에는 Heading, 섹션 구분에는 Divider, 상태에는 Badge, 레이블이 있는 데이터에는 KeyValue, 테두리 그룹에는 Card를 사용하세요.
  • 다중 뷰 UI에는 Tabs를 사용하고 자식 콘텐츠에는 가시성 조건을 적용하세요.
  • 인라인 트렌드에는 Sparkline, 값 비교에는 BarChart를 사용하세요.

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

Lev-it/lev-skills

Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo.

Lev-it/lev-skills

Premium brand-kit image generation skill for creating high-end brand-guidelines boards, logo systems, identity decks, and visual-world presentations. Trained for minimalist, cinematic, editorial, dark-tech, luxury, cultural, security, gaming, developer-tool, and consumer-app brand systems. Optimized for intentional logo concepting, refined composition, sparse typography, strong symbolic meaning, premium mockups, art-directed imagery, and flexible grid layouts.

Lev-it/lev-skills

Compact the current conversation into a handoff document for another agent to pick up.

Lev-it/lev-skills

Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, file issues conversationally, or mentions "QA session".

Lev-it/lev-skills

Facilitate a structured sprint retrospective — what went well, what didn't, and prioritized action items with owners and deadlines. Use when running a retrospective, reflecting on a sprint, creating action items from team feedback, or learning how to run effective retros.

Lev-it/lev-skills

Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".

Lev-it/lev-skills

Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.

Lev-it/lev-skills

Teach the user a new skill or concept, within this workspace.

Lev-it/lev-skills

Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.

Lev-it/lev-skills

Move issues through a state machine of triage roles — categorise, reproduce, grill if needed, and write agent-ready briefs.

Lev-it/lev-skills

Create product backlog items in Why-What-Acceptance format — independent, valuable, testable items with strategic context. Use when writing structured backlog items, breaking features into work items, or using the WWA format.

관련 스킬