Communitygithub.com

SkillFlowChart — 决策流程图生成器

AI가 SKILL.md에서 의미를 추출하여 구조화된 JSON 데이터를 생성하고, 스크립트가 이를 기반으로 결정론적으로 HTML 순서도를 생성하는 도구입니다.

SkillFlowChart — 决策流程图生成器란 무엇인가요?

SkillFlowChart는 AI 에이전트(Claude Code, Cursor, Codex 등)가 SKILL.md 문서를 읽고, AI가 의미적 판단을 수행하여 구조화된 nodes.json 데이터를 추출한 후, Python 스크립트가 이 데이터를 기반으로 순서도 HTML을 생성하는 효율적인 파이프라인입니다. AI는 순수하게 의미 분석과 노드/엣지 구조화만 담당하며, 좌표 계산이나 SVG 생성은 스크립트가 결정론적으로 처리합니다. 이로 인해 반복 가능하고 정렬된 픽셀 정확도를 보장합니다. 지원하는 플랫폼은 모든 AI 에이전트이며, SKILL.md의 자연어 설명을 기반으로 entry, decision, process, output, terminal 등의 노드 타입과 ai, script, decision, output, terminal 등 다양한 role을 가진 노드를 정의하고, 각 엣지에 side 필드를 명시적으로 지정하여 레이아웃을 제어합니다. 또한 루프(되돌림)와 합류점을 지원하며, 다양한 예제 파일이 제공되어 쉽게 시작할 수 있습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add CoderMoray/SkillFlowChart

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

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

문서

Skill 決策流程圖生成器

SKILL.md 파일을 읽어 구조화된 데이터 nodes.json을 추출하고, 스크립트가 결정론적으로 순서도 HTML을 생성합니다.

분업

단계담당자이유
SKILL.md → nodes.jsonAISKILL.md는 자연어로, 의미가 불안정하므로 AI가 문맥을 이해해야 함
nodes.json → HTML스크립트좌표 계산은 결정론적이고 재현 가능하며 픽셀 정렬이 필요함

AI는 오직 구조화된 데이터만 출력하며, 좌표나 SVG를 절대 생성하지 않습니다. 스크립트는 오직 기하학만 수행하며, 의미를 절대 추측하지 않습니다.

실행 단계

1. SKILL.md 읽기

사용자가 지정한 SKILL.md 파일을 읽습니다. 파일을 찾을 수 없는 경우 사용자에게 경로를 입력하도록 요청합니다.

2. AI가 nodes.json 추출

다음 스키마에 따라 JSON을 출력합니다. 각 출력 엣지에는 반드시 명시적으로 side 필드가 있어야 합니다. 이는 AI의 의미적 판단이며, 스크립트는 추측하지 않습니다.

최상위 구조

{
  "title": "스킬 이름",
  "subtitle": "선택적 설명",
  "nodes": [ ... ],
  "edges": [ ... ],
  "loops": [ ... ],
  "legend": [ ... ]
}
  • nodes: 필수, 노드 배열
  • edges: 필수, 방향성 엣지 배열
  • loops: 선택 사항, 되돌림 점선 (아래 참조)
  • legend: 일반적으로 빈 배열 []로 두고, 기본 범례 사용

노드 type

type의미모양
entry흐름 시작점둥근 사각형
decision결정 지점 (예/아니오, 있음/없음)다이아몬드
process처리 단계둥근 사각형
output보고서/파일 출력둥근 사각형
terminal종료/오류 종료둥근 사각형

노드 role (색상)

role의미fill / stroke
aiAI 추론 / LLM 호출#E6F1FB / #185FA5
output보고서 / 파일 출력#EEEDFE / #534AB7
decision결정 지점#FAEEDA / #854F0B
script스크립트 실행#E1F5EE / #0F6E56
terminal종료 / 오류#FCEBEB / #A32D2D

각 노드는 하나의 role만 가질 수 있습니다. 한 단계가 여러 가지 성격의 작업(다른 role에 해당)을 포함하는 경우, 반드시 여러 개의 노드로 분할해야 합니다. 예를 들어 '스크립트로 기준선 가져오기 + AI 보충 분석'은 role=script와 role=ai 두 개의 노드로 분할되어야 합니다.

엣지 side (중요!)

side의미레이아웃 동작
bottom메인 흐름 아래로target은 from의 다음 레이어, cx는 from 상속
left결정 왼쪽 분기 / 분기 왼쪽결정 → 동일 레이어 수평 연결; 일반 → 다음 레이어 직교 꺾임선
right결정 오른쪽 분기 / 분기 오른쪽위와 동일, 방향만 반대

side의 의미적 판단은 AI가 수행합니다:

  • 결정 다이아몬드(type=decision)의 left/right → 결정과 동일 레이어, 수평 연결선
  • 일반 사각형(type=process/output)의 left/right → 다음 레이어, 직교 꺾임선 (수직→수평→수직, 대각선 없음)

loops (되돌림, 선택 사항, 점선)

흐름에 '이전 단계로 돌아가는' 로직이 있을 때 사용합니다. 예를 들어:

  • 수정 후 재검토 (apply_fix → entry)
  • 재시도 (retry → checkpoint)
  • 조건 충족까지 반복 (recheck → validate)
{ "from": "apply_fix", "to": "entry", "label": "수정 후 재검토", "path": "left_edge" }

필드 설명:

  • from: 되돌림 시작 노드 id (보통 마지막 단계)
  • to: 되돌림 종료 노드 id (보통 흐름 시작점 또는 검사 지점)
  • label: 되돌림 레이블, 점선 옆에 표시
  • path: 고정값 "left_edge" (그래프 왼쪽 가장자리를 따라 경로 지정)

참고:

  • 되돌림 시작점과 종료점 사이에 edges에 중복 엣지를 그리지 마십시오. 그렇지 않으면 중복 렌더링됩니다.
  • loops의 from/to 노드는 depth 계산에 참여하지 않습니다.

legend

일반적으로 빈 배열 []로 두면, 스크립트가 기본 5색 범례를 사용합니다. 필요시 사용자 지정:

[
  { "label": "AI 실행",   "fill": "#E6F1FB", "stroke": "#185FA5" },
  { "label": "출력/보고서", "fill": "#EEEDFE", "stroke": "#534AB7" },
  { "label": "결정 지점",   "fill": "#FAEEDA", "stroke": "#854F0B" },
  { "label": "스크립트",    "fill": "#E1F5EE", "stroke": "#0F6E56" },
  { "label": "종료",       "fill": "#FCEBEB", "stroke": "#A32D2D" }
]

3. 스크립트 호출하여 HTML 생성

python3 <skill_dir>/scripts/flowchart.py <nodes.json> --out docs/decision-flowchart.html

스크립트는 다음을 수행합니다:

  • id 고유성, side/type/role 유효성, from/to 참조 유효성 검증
  • 레이어 자동 계산 (결정 측지는 동일 레이어 / 일반 분기는 하위 레이어 / 합류점 = max(들어오는 엣지)+1)
  • x (side에 따라 결정) 및 y (레이어 + 노드 높이에 따라) 자동 계산
  • 연결선 렌더링 (수평 측지 / 직교 꺾임선 / 수직 메인 흐름 / 합류점 3단 / 되돌림 점선)
  • 자동 viewBox + 하단 범례
  • 자체 포함 HTML 출력

nodes.json 예제

  • docs/halucatch-v2-nodes.json — 전체 예제 (loop 되돌림, 삼항 분기, 합류점 포함)
  • docs/halucatch-nodes.json — 기본 예제
  • docs/security-review-nodes.json — 다중 결정 지점 예제
  • docs/self-nodes.json — 최소 예제 (9개 노드)

자체 점검 목록

  • 진입 노드 type=entry가 최상단에 위치
  • 각 엣지에 side 필드 존재 (bottom/left/right)
  • 결정 다이아몬드의 side=left/right는 측지 (동일 레이어 수평 연결)
  • 일반 사각형의 side=left/right는 분기 (하위 레이어 직교 꺾임선)
  • 하나의 노드에 하나의 role, 혼합 단계는 분할됨
  • 합류점 (여러 들어오는 엣지가 같은 노드로)은 특별 처리 불필요, 스크립트가 자동 인식
  • 되돌림은 loops 필드 사용, edges에 중복 없음
  • 모든 노드 id가 edges의 from/to에서 참조됨 (고립 노드 없음)
  • 범례는 빈 배열 []

자주 묻는 질문

Q: 노드가 겹칩니다. 어떻게 해야 하나요? side 필드가 누락되었는지 확인하십시오. 결정 분기에는 side (left/right/bottom)가 반드시 있어야 합니다. 그렇지 않으면 두 대상 노드가 같은 위치를 상속받게 됩니다.

Q: 되돌림 점선이 그려지지 않습니다. 되돌림은 loops 배열로 선언해야 하며 (edges가 아님), from/to를 edges에 중복해서 넣지 마십시오. path는 고정값 "left_edge"입니다.

Q: 스크립트에서 JSON 형식 오류가 발생합니다. JSON은 주석과 작은따옴표를 지원하지 않습니다. 일반적인 문제: 쉼표 누락, 불필요한 쉼표 (배열 끝), 작은따옴표 사용.

더 많은 질문은 docs/FAQ.md를 참조하십시오.

관련 스킬