SkillLens: 사용법 및 유지보수
SkillLens는 모든 SKILL.md 파일을 애니메이션 수영레인(swimlane) 플로우차트로 변환합니다. 카드는 단계(step), 마름모는 결정(decision), 실선은 전진, 점선은 루프백, 반짝이는 점은 선을 따라 이동하며 현재 단계는 강조 표시됩니다. UI와 차트 텍스트는 영어(기본)와 중국어로 제공되며, 오른쪽 상단의 '中/EN' 버튼으로 전환할 수 있습니다.
title: SkillLens
subtitle: SKILL.md 입력 · 자동 추출 · 애니메이션 플로우차트 출력
hero: SkillLens | 가져오기 · 추출 · 조정 · 내보내기
trigger start: 기술 워크플로우를 이해하고 싶을 때 [시작] {bell}
워크플로우를 읽습니다
확인하거나 발표합니다
lane L1: 가져오기 [import] (green)
step open: SkillLens 열기 [start.bat] {play}
모든 로컬 스킬을 나열합니다
저장할 때마다 다시 그립니다
step add: 드롭 또는 붙여넣기 [drop] {upload}
폴더, .md 파일
또는 붙여넣은 텍스트
lane L2: 추출 [extract] (blue)
decide has: skillflow 블록이 있나요? [skillflow?]
step auto: 휴리스틱 추출 [auto] {sparkles}
섹션 → 레인
단계 / 결정 / 루프
step check: 소스와 비교 확인 [review] {scan-eye}
카드를 클릭하면 텍스트 표시
연결 관계 확인
step tune: 구조 편집 [edit] {pencil}
다시 그리기 적용
코드 블록으로 복사
lane L3: 출력 [export] (purple)
step draw: 블록에서 그리기 [render] {layers}
레인 · 카드 · 마름모
점들이 선을 따라 흐름
step out: 내보내기 [export] {download} +end
HTML / SVG / PNG
mp4 녹화
flow:
start -> open -> add -> has
has -> auto : 아니오
has -> draw : 예
auto -> check -> tune -> draw -> out
check ~> auto : 소스 텍스트 수정
열기
start.bat더블 클릭: 로컬 서버를 시작하고 브라우저를 엽니다. 목록에는 리포지토리의skills/와examples/, 그리고 로컬 Claude 사용자 및 플러그인 스킬이 포함되며, SKILL.md가 변경된 후 2초 이내에 다시 그려집니다.npm start와 동일합니다.npm run start:project는 리포지토리 자체 스킬만 나열합니다.index.html직접 열기: 서버가 필요 없지만, 목록이data/skills.js에서 오므로 먼저npm run scan을 실행해야 합니다. 비디오 녹화 및 자동 번역은 서버가 필요합니다.- 추가 폴더:
--root Name=<path>또는 리포지토리 루트에skillviz.config.json파일을 생성합니다:{"roots":[{"label":"팀 스킬","dir":"<path>"}]}.
차트가 잘 그려지는 스킬 작성법
추출 규칙은 src/extract.js에 있습니다. 다음과 같이 작성된 SKILL.md는 skillflow 블록 없이도 올바르게 차트가 그려집니다:
- 절차를
## 워크플로우/## 단계/## 과정과 같은 제목 아래에 순서 목록 또는 번호가 매겨진###하위 섹션으로 배치하고, 각 단계는**짧은 제목**: 설명형식으로 작성하세요. - 결정은 "If …" / "Whether …"로 시작하세요.
If X, do Y는 '예' 출구가 있는 마름모가 됩니다. - 라우터는 왼쪽 열에 "상태 / 조건 / If"가 있고 오른쪽 열에 "동작 / 수행 / 라우트"가 있는 두 열 표로 작성하세요. 그러면 첫 번째 일치 결정 체인이 됩니다.
- 루프는 "...할 때까지 N단계로 돌아가기" 형식으로 작성하세요.
- 선택적 단계는 앞에
[필요한 경우]/[선택 사항]을 붙이세요. 카드에 점선 테두리가 생깁니다. ## 규칙/## 참고아래의 규칙은 호박색 노트가 되고,## 참조아래의 자료는 연결되지 않은 참조 레인이 됩니다.
skillflow 블록 (정확한 제어)
SKILL.md에 ```skillflow 블록이 포함되면 SkillLens는 해당 블록만 그립니다. 가장 빠른 작성 방법: 구조 패널에서 자동 추출된 차트를 수정한 후 "코드 블록으로 복사"를 클릭하여 SKILL.md에 붙여넣습니다. 구문:
| 라인 | 의미 |
|---|---|
title: subtitle: `hero: title | subtitle footer: window: cols: 4` |
trigger id: 제목 [태그] {아이콘} | 상단의 트리거 카드; 들여쓰기된 아래 줄은 설명 |
lane id: 제목 [태그] (색상 종류) | 레인; 색상: green / blue / purple / teal / rose / amber / slate; 종류: flow(기본, 연결됨) / ref(참조, 연결 안 됨) / bare(프레임 없음) |
step id: 제목 [태그] {아이콘} +optional +end | 단계 카드; +end는 종료 단계(채워진 아이콘), +optional은 점선 카드 |
decide id: 질문? [부제목] | 결정 마름모 |
note: 텍스트 | 레인 내부의 노트 |
a -> b -> c : 레이블 (flow: 아래) | 전진선; ~>는 점선 루프; a -> "텍스트" : 예는 짧은 텍스트를 가리키는 출구 |
flow:가 없으면 비참조 레인의 카드가 순서대로 연결됩니다. 아이콘은 Lucide 이름이며, src/icons.js에 나열되어 있습니다. 추가하려면 lucide-static에서 SVG 본문을 복사하세요.
SkillLens 변경하기
- 레이어:
markdown.js가 파싱 →extract.js/dsl.js가 구조 생성 →layout.js가 카드 배치 및 라인 경로 설정 →render.js가 SVG를 그리고 애니메이션 재생 →app.js가 UI. 모든 UI 및 차트 문자열은i18n.js에 있으며, 모든 키는en과zh모두에 추가하세요. - 페이지는 더블 클릭으로 열려야 하므로 일반
<script>태그를 사용하며 ES 모듈은 사용하지 않습니다. 각 스크립트는SV.mod.name = function (SV) {…}로 작성되어 독립형 내보내기가toString()으로 코드를 인라인할 수 있습니다. - 모든 프레임은 시간 t의 순수 함수여야 합니다(CSS 애니메이션,
Math.random또는 벽시계 시간 사용 금지). 그렇지 않으면 프레임별 비디오 녹화가 깨집니다. - 테마: Blueprint(기본), Midnight 및 Glass. 차트 색상은
render.js의THEMES에, UI 색상은style.css상단의 CSS 변수에 있습니다. 둘 다 함께 변경하세요. Blueprint 전용 세부 사항(격자, 눈금자, 모서리 눈금, 카드 번호, 호박색 활성 단계)은P.blueprint뒤에 있습니다. - 글꼴: Google Fonts의 Noto Sans SC(중국어), Inter(라틴), JetBrains Mono(태그 및 경로)를 사용하며, 오프라인에서는 시스템 폰트로 대체됩니다. 레이아웃은 캔버스로 텍스트를 측정하므로 글꼴을 기다려야 합니다.
app.js는loadingdone에서 측정 캐시를 지우고 다시 그리며, 레코드 모드와 독립형 내보내기는 먼저 차트 텍스트에 대해document.fonts.load를 호출합니다.index.html의 글꼴 링크,layout.js의FONT/MONO, 독립형 템플릿의 링크를 동기화 상태로 유지하세요. - 자동 번역:
scripts/lib/translate.mjs(서버,/api/translate)와src/app.js의useTranslation(차트에서 어떤 문자열이 번역되는지 결정). 차트 텍스트와 열린 소스 텍스트만 번역됩니다. 태그, 파일 이름, 경로 및 예/아니오는 유지됩니다. 백엔드 우선 순위: API 키가 설정되고@anthropic-ai/sdk가 설치된 경우 Anthropic SDK, 그렇지 않으면 로컬 Claude Code CLI(Windows에서는.cmd따옴표 문제를 피하기 위해node_modules/@anthropic-ai/claude-code/bin/claude.exe를 직접 호출). 캐시 키는 양쪽에서lang + \u0001 + text입니다. - 헤드리스 브라우저에서 변경 사항 확인:
npm run scan후node scripts/record.mjs <skill> --seconds 3를 실행하거나,scripts/lib/cdp.mjs를 통해 스크린샷을 촬영하세요. 회귀 테스트를 위해 모든 스킬을SV.extract→SV.layout→SV.render.toSVG로 실행하고 오류가 발생하지 않으며 텍스트가 카드를 넘치지 않는지 확인하세요. - 녹화에는 로컬 Chrome/Edge와 ffmpeg가 필요합니다.
SV_CHROME/SV_FFMPEG환경 변수를 설정하거나, 찾을 수 없는 경우 경로를 지정하세요. - README 히어로 미디어:
docs/promo.webp(인라인으로 표시되는 애니메이션)는 원시docs/promo.mp4(사운드가 포함된 전체 비디오)로 연결됩니다. GitHub는 리포지토리 MP4를 인라인으로 재생하지 않으므로(README 인라인도, 파일 보기에서도, 크기에 관계없이) 원시 링크는 다운로드됩니다. 인라인 플레이어는 github.com 편집기를 통해 업로드된 비디오(user-attachmentsURL)가 필요합니다. GIF 대신 애니메이션 WebP를 사용하세요: 어두운 Blueprint 그라데이션에서 30초 GIF는 20MB를 초과하지만 WebP는 더 선명한 색상으로 8MB 미만을 유지합니다. 1080p 마스터에서:ffmpeg -i master.mp4 -vf "fps=15,scale=960:-1:flags=lanczos" -c:v libwebp -quality 70 -compression_level 6 -loop 0 -an docs/promo.webp및ffmpeg -i master.mp4 -c:v libx264 -preset slow -crf 23 -pix_fmt yuv420p -c:a aac -b:a 160k -movflags +faststart docs/promo.mp4.