Visual — 스킬 그래프 시각화
프로젝트의 모든 스킬을 방향성 그래프로 매핑합니다: 각 스킬이 소비하는 것, 생산하는 것, 그리고 스킬들이 어떻게 워크플로우로 연결되는지 보여줍니다. 두 가지 출력물을 생성합니다 — 문서화용 Mermaid 마크다운 파일과 탐색용 대화형 브라우저 그래프.
시작 시 알림: "스킬 그래프 매핑 중..."
사용 시기
다음과 같은 경우 /visual을 실행하세요:
- 모든 스킬이 어떻게 함께 작동하는지 한눈에 이해하려 할 때
- 스킬 생태계에 기여자를 온보딩할 때
- 스킬을 추가하거나 수정한 후 그래프를 감사할 때
워크플로우
1단계: 모든 스킬 스캔
find skills/ -name "SKILL.md" 2>/dev/null | sort
각 SKILL.md 파일을 전체 내용을 읽습니다.
2단계: 각 스킬에서 메타데이터 추출
각 스킬 파일에서 다음을 추출합니다:
| 필드 | 출처 |
|---|---|
id | 디렉토리 이름 (예: skills/walkthrough/ → walkthrough) |
label | name 프론트매터, 알려진 경우 README의 이모지 접두사 포함 |
description | description 프론트매터 — 첫 문장만 |
triggers | 콘텐츠: 텍스트에서 찾은 /command 패턴 |
inputs | 콘텐츠: 스킬이 읽는 파일/소스 (예: git diff, docs/plans/) |
outputs | 콘텐츠: 스킬이 쓰는 파일 (예: .review/review.md) |
relationships | relationships 프론트매터 배열 — 아래 스키마 참조 |
Relationships 프론트매터 스키마 (명시적, 권장):
relationships:
- target: <skill-id> # 다른 스킬의 디렉토리 이름
type: <relationship-type> # 아래 유형 중 하나
label: <short phrase> # 그래프 엣지에 표시 (5단어 이하)
관계 유형:
| 유형 | 의미 | 화살표 스타일 |
|---|---|---|
leads-to | 이 스킬 이후 권장되는 다음 단계 | 실선 --> |
alternative | 동일한 작업에 대한 다른 접근 방식 | 점선 -.-> |
complements | 다른 목적, 함께 잘 작동 | 실선 --> |
feeds-from | 이 스킬이 대상의 출력을 소비 | 실선 --> |
analyzes | 이 스킬이 대상의 파일을 읽고 처리 | 실선 --> |
3단계: 관계 추론 (폴백 전용)
relationships 프론트매터가 없는 스킬의 경우 콘텐츠에서 추론합니다:
- 명명된 트리거 참조: 콘텐츠가 다른 스킬의
/command또는 디렉토리 이름을 언급 → 참조된 스킬로의leads-to엣지. - 공유 I/O: 두 스킬이 동일한 파일 경로를 읽거나 씀 → 두 스킬 간
complements엣지. - 워크플로우 언어: 콘텐츠에 "X를 실행한 후", "Y를 사용하기 전", "Z와 잘 작동" 등의 표현 포함 → 표현과 일치하는 방향성 엣지 생성.
- 지식 저장소 패턴: 다른 스킬의 출력을 입력으로 받지 않고 지식 저장소에만 쓰는 스킬 → 학습 내용 보존을 언급하는 다른 스킬이
leads-to로 연결.
추론된 모든 엣지는 그래프 모델에서 "inferred": true로 표시합니다. 두 출력물 모두에서 점선으로 렌더링됩니다.
4단계: 내부 그래프 모델 구축
내부적으로 다음 JSON 구조를 생성합니다 (디스크에 쓰지 않음):
{
"skills": [
{
"id": "walkthrough",
"label": "🚶 walkthrough",
"description": "One sentence.",
"triggers": ["/walkthrough"],
"inputs": ["git diff"],
"outputs": []
}
],
"edges": [
{
"source": "walkthrough",
"target": "compound",
"type": "leads-to",
"label": "save session learnings",
"inferred": false
}
]
}
5단계: docs/SKILL_GRAPH.md 작성
docs/ 디렉토리가 없으면 생성합니다. docs/SKILL_GRAPH.md에 네 개의 섹션을 작성합니다:
섹션 1 — 개요 그래프
## Skill Overview
\`\`\`mermaid
flowchart LR
classDef skill fill:#1a1a2e,stroke:#4a90d9,color:#e0e0ff
classDef terminal fill:#0d2618,stroke:#4a9d6f,color:#a0ffa0
skill-a["emoji name\n/trigger"]:::skill
skill-b["emoji name\n/trigger"]:::skill
...
skill-a -->|"label"| skill-b
skill-c -.->|"label"| skill-d
\`\`\`
규칙:
leads-to및complements엣지: 실선-->alternative및 추론된 엣지: 점선-.->- 노드 레이블 형식:
"emoji name\n/trigger"(\n으로 줄바꿈) - 나가는
leads-to엣지가 없는 스킬은:::terminal클래스 - Mermaid 노드 ID는 유효한 식별자여야 함 — 하이픈을 밑줄로 대체, 레이블은 그대로 유지
섹션 2 — 워크플로우 체인
들어오는 leads-to 엣지가 없는 모든 진입점 스킬을 찾습니다. 각각에 대해 전체 leads-to 경로를 추적하고 명명된 워크플로우를 작성합니다:
## Workflows
### Code Review Workflow
\`\`\`mermaid
flowchart LR
walkthrough -->|"save learnings"| compound
\`\`\`
### Implementation Workflow
...
\`\`\`
두 경로가 동일한 터미널 노드를 공유하는 경우 하나의 다이어그램으로 표시할 수 있습니다.
섹션 3 — 데이터 흐름
입력 소스, 스킬, 출력 아티팩트를 표시합니다. 메타데이터에 명시적 입력 또는 출력이 있는 스킬만 포함합니다:
## Data Flow
\`\`\`mermaid
flowchart LR
classDef artifact fill:#1a1a1a,stroke:#888,color:#ccc
classDef ext fill:#2a1a0a,stroke:#d9904a,color:#ffd0a0
git_diff["/"git diff"/"]:::ext
review_md["/"..review/review.md"/"]:::artifact
git_diff --> review_diff
review_diff --> review_md
\`\`\`
섹션 4 — 스킬 인덱스
표: 스킬 | 트리거 | 설명 | 읽기 | 쓰기
6단계: 대화형 HTML 출력 생성
4단계의 그래프 모델을 한 줄로 축소된 JSON 문자열로 직렬화합니다. 아래 두 출력물 모두에 이 JSON 문자열을 사용합니다 (동일한 데이터, 다른 템플릿).
6a — 스킬 대시보드 (기본 출력)
skills/visual/references/dashboard-template.html을 엽니다.
/* GRAPH_DATA_JSON */을 JSON 문자열로 바꿉니다.
.docs/skill-dashboard.html에 씁니다.
대시보드에는 세 개의 탭이 있습니다:
- Skills — 각 스킬의 트리거, 설명, 읽기/쓰기, 나가는 관계를 보여주는 카드 그리드
- Graph — 대화형 Cytoscape 그래프 (첫 번째 탭 열 때 지연 초기화)
- Workflows — 자동 파생 워크플로우 체인, 대안 및 보완 관계
6b — 독립형 그래프 (보조 출력)
skills/visual/references/graph-template.html을 엽니다.
/* GRAPH_DATA_JSON */을 동일한 JSON 문자열로 바꿉니다.
.docs/skill-graph.html에 씁니다.
템플릿 파일이 없으면 해당 출력을 건너뛰고 보고서에 기록합니다.
7단계: 발견 가능성 확인
CLAUDE.md에서 SKILL_GRAPH를 검색합니다. 찾을 수 없으면 다음을 제안합니다:
스킬 그래프(
docs/SKILL_GRAPH.md)가 아직 CLAUDE.md에서 참조되지 않았습니다. 향후 에이전트가 자동으로 발견할 수 있도록 이 블록을 추가하시겠습니까?## Skill Graph 스킬 관계 및 워크플로우: `docs/SKILL_GRAPH.md` 대시보드 (스킬 + 그래프 + 워크플로우): `.docs/skill-dashboard.html` 독립형 그래프: `.docs/skill-graph.html`CLAUDE.md에 추가하시겠습니까? (예/아니오)
자동으로 쓰지 마십시오. CLAUDE.md를 수정하기 전에 승인을 기다리십시오.
8단계: 완료 보고서 출력
★ 스킬 그래프 매핑 완료
스킬: N
관계: M개 명시적, K개 추론됨
→ docs/SKILL_GRAPH.md [Mermaid 개요 + 워크플로우 + 데이터 흐름 + 인덱스]
→ .docs/skill-dashboard.html [대시보드: 스킬 카드 + 그래프 + 워크플로우]
→ .docs/skill-graph.html [독립형 대화형 그래프]
CLAUDE.md: 노출됨 ✓ / 아직 참조되지 않음
주요 제약 조건
- CLAUDE.md에 자동으로 쓰지 마십시오 — 항상 먼저 질문하십시오
- 명시적 우선 —
relationships프론트매터가 항상 우선하며, 추론된 엣지는 두 출력물 모두에서 점선으로 표시됩니다 - 멱등성 —
/visual을 다시 실행하면 두 출력 파일을 완전히 덮어씁니다 - 비파괴적 — SKILL.md 파일을 절대 수정하지 않으며,
docs/및.docs/에만 씁니다 - Mermaid 노드 ID: 구문 분석 오류를 피하기 위해
-를_로 바꿉니다 (예:review_diff이지review-diff가 아님) - 노드 레이블 길이: 가독성을 위해
\n으로 분할된 줄을 각각 20자 이내로 유지