스킬·자료 모음
bergside/typeui.sh가 만드는 typeui.sh CLI가 npx typeui.sh pull <slug> 명령으로 이 레지스트리에서 파일을 가져가 쓴다. 즉 이 저장소는 "자동차(CLI)가 없는 부품 창고"에 가깝다.
bergside/awesome-design-skills · 라이선스 MIT(2026, Bergside) · 스킬 67개(skills/index.json 항목 수와 폴더 수 일치 확인) · 마케팅 미리보기 이미지 77장(유령 이미지 10장 포함, 본문 9번 섹션 참고) · 최근 커밋 f631a09, 2026-06-28 · 정리 기준일 2026-07-29 기준 약 한 달 전 커밋 · 별점 미인용(얕은 클론으로는 확인 불가) · bergside/design-md-chrome이라는 같은 소유자의 다른 저장소와는 무관)
awesome-design-skills는 "디자인 시스템을 코드로 만드는 도구"가 아니라 "AI 에이전트가 읽을 지침서 모음"이다. 저장소를 열어 보면 놀랍도록 단순하다 — README.md, LICENSE, 이미지 폴더 하나, 그리고 skills/ 폴더 안에 67개의 하위 폴더. 각 하위 폴더 안에는 딱 두 개의 마크다운 파일(SKILL.md, DESIGN.md)만 들어 있다. package.json도, 빌드 스크립트도, 테스트 코드도 없다.
67개 폴더는 각각 하나의 "디자인 미학"을 표현한다. 유리질감의 glassmorphism, 거친 콘크리트 느낌의 brutalism, 8비트 게임을 흉내 낸 pacman·tetris, 리서치 저널풍의 claude까지 — 취향의 스펙트럼이 넓다. 각 폴더의 SKILL.md는 "이 미학대로 UI 코드를 짜라"는 지침을 AI 에이전트에게 주는 파일이고, DESIGN.md는 같은 내용을 사람이 읽기 좋게 풀어놓은 짝꿍 파일이다.
이 저장소는 67가지 색상·질감이 인쇄된 견본책과 같다. 어떤 벽을 어떻게 칠할지 자세한 설명(색 번호, 붓질 방법, 주의사항)까지 카드 뒷면에 빼곡히 적혀 있지만, 붓과 페인트 통을 들고 실제로 칠하는 사람(=AI 에이전트)은 이 책 밖에 있다.
그리고 이 견본책을 서점에서 사서 우리 집(=우리 프로젝트) 서랍에 넣어주는 "배달원(=typeui.sh CLI)"도 저장소 밖 별도 회사(별도 저장소)가 운영한다. 견본책 자체는 배달도, 시공도 하지 않는다.
2025년 이후 Claude·Cursor·Codex 같은 AI 코딩 에이전트가 널리 쓰이면서, 에이전트에게 "이렇게 행동하라"고 미리 심어주는 스킬(skill)·규칙(rules) 파일이라는 새로운 파일 장르가 생겼다. awesome-design-skills는 이 트렌드 중에서도 "디자인"이라는 좁고 구체적인 영역에 특화해 자리를 잡았다.
에이전트에게 지침 없이 "UI를 예쁘게 만들어줘"라고만 하면, 대부분 비슷비슷한 무채색 Tailwind 기본값(둥근 카드, 옅은 회색 배경, 파스텔 배지)으로 수렴하는 현상이 흔하다. 색상 토큰·폰트·톤이 미리 정의된 SKILL.md 한 장을 읽히면, 에이전트가 적어도 "이 프로젝트만의 일관된 방향"은 지키게 만들 수 있다.
글래스모피즘부터 브루탈리즘, 레트로 아케이드(pacman·tetris), 브랜드 오마주(claude·codex·shadcn·roku·sega)까지 폭넓게 큐레이션돼 있어, "어떤 스타일부터 시작할지" 고민하는 시간을 npx typeui.sh pull <slug> 한 줄로 줄여준다.
SKILL.md는 에이전트마다 규칙 파일을 두는 위치가 다르다는 현실적 문제(.cursor/skills/, .claude/ 등)를 typeui.sh CLI가 -p cursor,claude 같은 옵션으로 흡수한다. 저장소 자체는 "콘텐츠"만 책임지고, "배포"는 CLI가 맡는 역할 분리가 여러 에디터·에이전트를 오가는 개발자에게 매력적이다.
shadcn/ui나 Tailwind 테마 프리셋은 실행 가능한 코드(컴포넌트·설정 파일)를 준다. 반면 이 저장소의 산출물은 자연어 지침 문서다. "완성된 컴포넌트"가 아니라 "에이전트가 컴포넌트를 만들 때 지킬 규칙"을 판다는 점에서, 코드 배포가 아니라 프롬프트/컨텍스트 배포 시장에 속한다.
README의 표현을 빌리면 이 저장소는 "AI 에이전트가 코드를 생성할 때 참고할 디자인 시스템 지침 파일의 큐레이션 레지스트리"다. 구체적으로 세 가지 반복되는 실무 문제를 겨냥한다.
새 프로젝트를 시작할 때마다 "우리 브랜드 컬러가 뭐였지, 폰트는, 여백 스케일은?"을 다시 정리하는 대신, skills/<slug>/SKILL.md 프런트매터에 이미 colors·typography·rounded·spacing 토큰이 정의돼 있다. 예를 들어 skills/glassmorphism/SKILL.md는 primary=#1856FF, success=#07CA6B, warning=#E89558, danger=#EA2143 같은 값을 이미 갖고 있다.
Cursor는 .cursor/, Claude Code류는 .claude/ 아래에 규칙·스킬 파일을 기대하는 식으로 도구마다 관례가 다르다. 저장소 자체는 이 문제를 직접 풀지 않지만, README의 "Specify providers" 절이 안내하는 npx typeui.sh pull glassmorphism -p cursor,claude 명령이 이 파편화를 CLI 레벨에서 흡수하도록 설계돼 있다 — 저장소는 "재료"만 대고, "여러 곳에 나눠 담는 일"은 짝꿍 CLI의 몫으로 분업한다.
SKILL.md의 Quality Gates 절은 "모호한 형용사에만 의존하는 규칙 금지", "모든 접근성 문장은 구현에서 테스트 가능해야 함" 같은 검증 기준을 명시한다. 또 Component Rule Expectations 절은 default·hover·focus-visible·active·disabled·loading·error 같은 상태값을 빠짐없이 정의하라고 요구한다. 즉 "예쁘게"라는 취향 판단을, 최소한 "이 상태들을 빠뜨리지 않았는가"라는 점검 가능한 목록으로 바꿔주는 것이 실질적 기여다.
SKILL.md 프런트매터가 바로 이 토큰 값들의 모음이다.
저장소 루트는 단출하다. 실행할 것도, 설정할 것도 없다. 무게중심은 오직 skills/ 폴더에 실린 67개 서브폴더다.
이 트리에서 눈여겨볼 점 두 가지. 첫째, 이 저장소에는 실행 진입점이 없다 — package.json도 .github/workflows/도 존재하지 않는다(직접 클론해 확인). 둘째, skills/.DS_Store처럼 macOS Finder가 남긴 시스템 파일이 .gitignore 없이 그대로 커밋돼 있다 — 사소하지만 "저장소 위생"이 완벽하지 않다는 신호다.
index.json에 담아 CLI에게 알려준다.
이 저장소의 진짜 콘텐츠는 skills/index.json + 67벌의 SKILL.md/DESIGN.md 쌍이다. 하나씩 실제 파일 내용을 기준으로 뜯어본다.
skills/index.json — slug 기반 조회 테이블
67개 키를 가진 JSON 객체로, 각 키(slug)마다 slug·name·skillPath·designPath 네 필드를 담는다. 예를 들어 실제 파일의 항목은 이렇다.
"glassmorphism": {
"slug": "glassmorphism",
"name": "Glassmorphism",
"skillPath": "skills/glassmorphism/SKILL.md",
"designPath": "skills/glassmorphism/DESIGN.md"
}
67개 키의 등장 순서는 알파벳순이 아니다("agentic, artistic, bold, brutalism, cafe, claymorphism, clean, colorful, contemporary, corporate, cosmic, creative, dithered, doodle, dramatic, editorial" 다음 갑자기 "square, pulse, stitch"가 끼어드는 식) — 즉 스킬이 추가된 시간 순서를 그대로 반영한 배열로 보인다. CLI는 이 파일 하나만 내려받아 slug로 조회한 뒤 skillPath를 따라가 실제 SKILL.md를 가져가는 구조다.
SKILL.md — AI 에이전트가 읽는 지침 (12개 섹션)
YAML 프런트매터(name·description·license·metadata.author)로 시작해, 본문은 <!-- TYPEUI_SH_MANAGED_START -->와 <!-- TYPEUI_SH_MANAGED_END -->라는 HTML 주석 마커 사이에 담긴다. 이 마커는 "이 구간은 typeui.sh 도구가 관리(재생성)한다"는 신호로 읽힌다 — 즉 사람이 직접 이 구간을 손으로 고쳐도, CLI가 다시 밀어넣을 때 덮어써질 수 있다는 뜻이다. 마커 안쪽 구조는 12개 섹션으로 고정돼 있다.
| 섹션 | 내용 |
|---|---|
| Mission | "당신은 <스킬명>의 전문 디자인 시스템 지침 작성자다"라는 역할 지정 문장 |
| Brand | 이 미학의 정체성을 설명하는 산문 — 스킬마다 길이·깊이 편차가 크다(9번 섹션 참고) |
| Style Foundations | visual style·타이포 스케일·폰트·굵기·색상 토큰·spacing scale을 한 줄씩 |
| Accessibility | 거의 모든 스킬에서 동일: "WCAG 2.2 AA, keyboard-first interactions, visible focus states" |
| Writing Tone | "concise, confident, helpful" 등 짧은 형용사 나열 |
| Rules: Do / Don't | "의미 있는 토큰 우선", "저대비 텍스트 금지" 등 범용 규칙 |
| Expected Behavior · Guideline Authoring Workflow · Required Output Structure · Component Rule Expectations · Quality Gates · Example Constraint Language | 6개 섹션 모두 스킬 간 글자 하나 다르지 않은 공용 템플릿(아래 실측 참고) |
DESIGN.md — 사람용 짝꿍 문서, 그러나 실제로는…
YAML 프런트매터에 colors·typography·rounded·spacing 토큰을 좀 더 구조화된 형태(중첩 객체)로 다시 담고, 본문은 Overview·Style Foundations·Colors 세 섹션뿐이다. 그런데 Colors 섹션을 열어보면 skills/glassmorphism/DESIGN.md와 skills/brutalism/DESIGN.md 모두 색상 설명이 토씨 하나 안 틀리고 이렇다.
- **Primary (#1856FF):** Token from style foundations.
- **Secondary (#3A344E):** Token from style foundations.
- **Success (#07CA6B):** Token from style foundations.README는 DESIGN.md를 "디자인 개요·근거(rationale)·유지보수 노트를 담는 사람용 문서"라고 소개하지만, 실측 결과 색상 하나하나의 "근거"는 전부 "Token from style foundations."(스타일 파운데이션에서 온 토큰)이라는 동일 문장으로 채워져 있다 — 왜 이 색을 골랐는지에 대한 실제 서술은 없다.
index.json과 SKILL.md 프런트매터 어디에도 category나 tag 필드는 없다. 67개는 평평한(flat) 단일 네임스페이스로만 존재하며, 분류는 오직 슬러그 이름이 속하는 "느낌"으로만 짐작할 수 있다. 실제 슬러그를 훑어 정리하면 대략 이런 결이 보인다.
| 느슨한 축 | 대표 슬러그(실제 폴더명) |
|---|---|
| 디자인 사조 오마주 | glassmorphism · brutalism · claymorphism · neumorphism · skeumorphism |
| 브랜드/제품 오마주 | claude · codex · shadcn · roku · sega |
| 게임·장르 패러디 | pacman · tetris · matrix |
| 분위기 형용사 | bold · clean · minimal · vibrant · dramatic · friendly |
| 시대감 | retro · vintage · futuristic · contemporary |
| 업종/장소 | cafe · corporate · enterprise · fiction |
같은 표 안에서도 실제 토큰 값은 확실히 다르다 — pacman은 primary=Press Start 2P 픽셀 폰트를, tetris는 primary=Bangers 만화체 폰트를, matrix는 primary=Space Mono, secondary=#0B0C14(짙은 검정)를 쓴다. 토큰 값의 다양성은 진짜지만, 그 값을 감싸는 12개 섹션 중 6개는 완전히 동일한 틀이라는 점이 이 저장소의 핵심 성격이다.
86줄짜리 glassmorphism/SKILL.md와 brutalism/SKILL.md를 통째로 비교(diff)하면, 다른 줄은 프런트매터의 name·description과 Style Foundations 토큰 값뿐이다. Guideline Authoring Workflow(6단계), Required Output Structure(7항목), Component Rule Expectations, Quality Gates, Example Constraint Language — 이 다섯 섹션은 글자 하나까지 완전히 동일하다.
스택 지도를 그리려면 먼저 밝혀야 할 게 있다. 이 저장소 자체에는 실행되는 코드가 0줄이다. find . -type f로 전수 조사한 결과 파일 확장자는 .md·.json·.png, 그리고 macOS가 흘린 .DS_Store뿐이었다. package.json·CI 워크플로(.github/)·테스트 코드는 전혀 없다.
| 구성 요소 | 정체 |
|---|---|
| 콘텐츠 포맷 | Markdown(YAML 프런트매터 포함) + JSON(index.json) + PNG(미리보기) |
| 자동화 위치 | 이 저장소 밖. README가 안내하는 bergside/typeui.sh 저장소의 npm 패키지(typeui.sh CLI)가 실제 fetch·쓰기 로직을 담당(이번 딥다이브에서 그 저장소 자체는 클론·분석하지 않았음 — README의 소개만 확인) |
| CLI 명령 3종 | pull <slug>(가져와 쓰기) · list(목록 보기) · generate(대화형으로 새 스킬 만들기) |
| 미리보기 사이트 | typeui.sh/design-skills — 별도 웹앱, 이 저장소에는 소스가 없음 |
이 저장소는 식자재 창고고, typeui.sh CLI는 그 창고에서 재료를 꺼내 손님(당신의 프로젝트) 식탁에 차리는 배달·플레이팅 담당이다. 창고 자체에는 조리 도구도 불도 없다 — 냉장고(index.json) 안에 라벨 붙은 반찬통(각 스킬 폴더) 67개가 있을 뿐이다.
SKILL.md 본문의 Guideline Authoring Workflow·Required Output Structure 절이 "긴 지시문 템플릿을 채워 넣는" 형식을 취하고, README의 generate 명령이 "대화형 프롬프트로 커스텀 스킬 생성"을 약속하는 것을 함께 보면 — 이 67개 SKILL.md 자체가 그 generate 파이프라인의 산출물일 가능성이 높다. 5번 섹션에서 확인한 "6개 섹션이 완전히 동일하다"는 사실이 이 추정을 뒷받침한다. 다만 이는 소스 구조로부터의 합리적 추정이며, 생성 스크립트 자체는 이 저장소에 없어 직접 확인하지는 못했다.
---로 감싼 구간에 넣는 YAML 형식의 메타데이터. 제목·설명·색상 값처럼 "기계가 파싱해 쓸 값"을 본문 산문과 분리해 담는 관례다.
이 딥다이브를 위해서는 얕은 클론(git clone --depth 1)으로 소스를 직접 확인했지만, 일반 사용자는 이 저장소를 클론할 필요가 없다. README가 안내하는 실사용 경로는 전부 npx 한 줄이다.
| 항목 | 요구사항 |
|---|---|
| 실행 환경 | Node.js + npx가 되는 환경(버전은 README에 별도 명시 없음) |
| 스킬 하나 받기 | npx typeui.sh pull <slug> — 예: npx typeui.sh pull glassmorphism |
| 여러 프로바이더 지정 | npx typeui.sh pull glassmorphism -p cursor,claude |
| 미리 보기만 | npx typeui.sh pull glassmorphism --dry-run — 실제로 파일을 쓰지 않고 무엇이 쓰일지만 확인 |
| 목록 탐색 | npx typeui.sh list — 미리보기 링크와 함께 대화형으로 훑어보기 |
| 새 스킬 만들기 | npx typeui.sh generate — 대화형 프롬프트로 나만의 스킬 생성 |
| 쓰기 대상 경로 | README 표현으로 ".cursor/skills/, .claude/ 등 설정된 provider 경로" — 실제 경로 목록은 CLI 쪽 문서(별도 저장소)에 있음 |
API 키가 필요한지, 오프라인에서도 되는지, provider 경로 전체 목록이 무엇인지는 bergside/typeui.sh라는 별도 저장소의 코드를 봐야 정확히 알 수 있다. 이번 분석은 담당 레포인 awesome-design-skills만 클론·분석했으므로, 이 표의 CLI 관련 행은 README에 적힌 사용 예시를 그대로 옮긴 것이지 CLI 소스 코드 검증 결과가 아니다.
README의 표(67개 미리보기 이미지 + npx typeui.sh pull <slug> 명령이 나란히 적힌 표)나 typeui.sh/design-skills 미리보기 사이트를 훑어보며 원하는 미학의 슬러그를 정한다. 예: 유리질감이 마음에 들면 glassmorphism, 8비트 게임 느낌이면 pacman.
npx typeui.sh pull glassmorphism을 실행한다. CLI는 awesome-design-skills 저장소의 skills/index.json에서 glassmorphism 항목을 찾아 skillPath(skills/glassmorphism/SKILL.md)를 확인하고, 그 파일을 가져와 내 프로젝트의 provider 경로(예: .claude/)에 써 넣는다. DESIGN.md는 레지스트리(원본 저장소) 쪽에만 남아 사람이 참고하는 문서로 쓰인다.
Claude Code나 Cursor 같은 도구가 세션을 시작할 때 그 provider 경로의 파일들을 훑는다면, 방금 심어둔 SKILL.md의 Mission·Brand·Style Foundations·Rules Do/Don't·Quality Gates가 그 세션의 "디자인 인격"이 된다. 이제 "버튼 하나 만들어줘" 같은 평범한 요청에도, primary=#1856FF 같은 토큰과 "저대비 텍스트 금지" 같은 규칙이 자동으로 적용된다.
DESIGN.md의 색상 설명이 대부분 "Token from style foundations."로 비어 있다는 걸 5번 섹션에서 확인했다. 실전에서는 이 문서를 그대로 믿기보다, 프로젝트 특성에 맞게 사람이 직접 근거·예외 규칙을 채워 넣는 두 번째 손질 단계가 사실상 필요하다.
README는 각 SKILL.md를 "브랜드 철학·타이포 스케일·컴포넌트 규칙·접근성 규칙까지 담은" 문서로 소개한다. 실제로 열어보면 반은 맞고 반은 다르다. skills/claude/SKILL.md의 Brand 절은 "연구 저널풍의 미학이 따뜻한 돌 위에 인쇄된 듯한 인상. Anthropic Sans로 UI 크롬을, Anthropic Serif로 대형 타이포를... 1차 CTA 버튼에만 비대칭적인 위 평평·아래 둥근 모서리를 준다"는 식으로 구체적이고 공들인 서술을 담은 반면, skills/tetris/SKILL.md의 Brand 절은 통째로 "the most iconic game of history(역사상 가장 상징적인 게임)" 한 문장뿐이다. 67개의 완성도는 균일하지 않다 — 일부만 깊게 다듬어졌고, 다수는 자동 생성된 뼈대에 가깝다.
pull 직후 Brand 절과 색상 근거를 한 번 읽어보고, 너무 짧거나 일반적이면(예: 한 줄짜리 Brand, "Token from style foundations." 나열) 프로젝트 맥락에 맞게 직접 보강하는 편이 안전하다. 이 저장소의 가치는 "완성된 디자인 시스템 문서"가 아니라 "토큰이 채워진 빠른 출발점"에 있다.
registry-examples/ 폴더의 PNG는 77장이지만 skills/ 폴더와 index.json의 스킬은 67개뿐이다. 두 목록을 직접 대조해 보면 anime·candy·dark·forest·machine·mars·matcha·minimax·nostalgia·pragmatic 이렇게 10개의 -marketing.png 파일은 대응하는 스킬 폴더가 더 이상 존재하지 않는 "유령 이미지"다. 과거에 있다가 이름이 바뀌었거나 삭제된 스킬의 흔적으로 보이며, 정리(clean-up)가 완벽하지 않다는 증거다.
만약 README나 미리보기 사이트 캐시에서 nostalgia 같은 이름을 봤다면, 지금은 skills/index.json에 없어 npx typeui.sh pull nostalgia가 실패할 가능성이 높다. 반드시 현재 index.json 또는 README 표에 실제로 나열된 슬러그인지 확인하고 당겨야 한다.
git clone 자체는 되지만, 클론한 폴더 안에서 돌릴 스크립트가 없다. package.json도 없고 CI도 없다. 이 저장소는 "읽고 필요한 파일만 복사해 가는" 대상이지, "실행하는" 대상이 아니다. 실습·학습 목적이라면 클론보다 npx typeui.sh list --dry-run류로 CLI를 직접 만져보는 편이 이 프로젝트의 실제 사용 방식에 더 가깝다.
bergside/design-md-chrome과 같은 프로젝트라는 혼동
같은 소유자(Bergside) 계정에는 design-md-chrome이라는 별개 저장소도 있다(추정컨대 DESIGN.md 계열 파일을 브라우저에서 보기 좋게 렌더링하는 크롬 확장 프로그램류로 보인다). 이번 딥다이브의 대상은 오직 awesome-design-skills이며, 두 저장소는 코드·목적이 다른 별개 프로젝트다. 이름이 비슷한 자매 저장소와 혼동하지 않도록 주의한다.
| 대안 | awesome-design-skills와의 차이 |
|---|---|
| shadcn/ui + 테마 프리셋 | 바로 붙여 쓰는 실행 가능한 React 컴포넌트 코드를 준다. 이 저장소는 코드가 아니라 "코드를 짤 때 지킬 규칙"을 주는 한 단계 위(지침) 레이어다. 함께 쓰면 시너지가 있다 — 실제로 shadcn이라는 슬러그도 이 레지스트리 안에 있다. |
| Tailwind Config / 디자인 토큰 npm 패키지 | 토큰을 코드(JS/CSS 변수)로 배포한다. 이 저장소는 토큰을 자연어 지침 문서 속 값으로만 갖고 있어, 에이전트가 "해석"해서 코드로 옮겨야 한다 — 더 유연하지만 일관성은 에이전트의 준수 여부에 달려 있다. |
| 직접 프롬프트로 매번 지시하기 | "우리 색은 이런 톤이고..."를 매번 타이핑하는 대신 파일 하나를 미리 심어두는 것이 이 저장소의 핵심 이득이다. 다만 9번 섹션처럼 스킬별 완성도 편차가 있어, 결국 처음 한 번은 직접 다듬는 수고가 남는다. |
| Claude의 공식 Agent Skills·다른 스킬 마켓 | 범용 스킬 마켓들은 코딩·리서치·문서 작업 등 폭넓은 작업을 다룬다. 이 저장소는 오직 "시각적 디자인 톤"이라는 좁은 한 축에 깊게 집중한 버티컬 레지스트리라는 점이 차별점이다. |
bergside/awesome-design-skills는 67개의 SKILL.md/DESIGN.md 쌍을 담은, 코드가 전혀 없는 콘텐츠 레지스트리다. 실제 배포·설치 로직은 별도 저장소인 bergside/typeui.sh CLI가 담당하고, 이 저장소는 그 CLI가 읽어갈 "재료"만 index.json과 폴더 구조로 정리해둔다. 67개 스킬은 슬러그 이름 자체가 유일한 분류 기준이며, 각 SKILL.md의 12개 섹션 중 6개(Guideline Authoring Workflow·Required Output Structure·Component Rule Expectations·Quality Gates 등)는 완전히 동일한 공용 템플릿이고, 나머지(토큰 값·Brand 문단)만 스킬마다 다르다 — 그리고 그 "다른 부분"조차 스킬별로 공들인 정도가 크게 갈린다.
매번 색상·폰트 팔레트를 처음부터 정의하기 귀찮고, 67가지 취향 중 하나를 골라 "이 방향으로 통일해줘"라고 에이전트에게 맡기고 싶은 상황에 잘 맞는다. 특히 --dry-run으로 먼저 확인하고 받는 습관을 들이면 안전하다.
DESIGN.md의 색상 근거가 대부분 "Token from style foundations."로 채워져 있고, 다수 스킬의 Brand 서술이 짧다는 점(9번 섹션)에서, 이 저장소를 "완성된 디자인 시스템 문서 세트"로 기대하면 실망할 수 있다. 받은 뒤 프로젝트에 맞게 직접 다듬는 걸 전제로 쓰는 게 현실적이다.
.cursor/, .claude/)에 파일을 놓아야 그 도구가 규칙을 읽는데, typeui.sh CLI는 이 프로바이더별 경로 차이를 -p 옵션으로 처리해준다.이미 내려받은 저장소에서 README.md가 보이는 루트를 기준으로 진행한다. 아래 명령은 파일을 읽고 결과를 화면에 출력한다. 목록 검증에는 Python 3을 사용하며, 제시한 Python 코드는 저장소에 포함된 도구가 아니라 학습용 예제다.
목표: 스킬 이름을 찾는 것과 그 스킬의 지침 파일을 찾는 과정이 어떻게 연결되는지 이해한다.
README.md의 저장소 구조 설명을 읽은 뒤, 아래 명령으로 skills/index.json의 glassmorphism 항목을 확인한다.
python3 -B -c '
import json
from pathlib import Path
index = json.loads(Path("skills/index.json").read_text(encoding="utf-8"))
print(json.dumps(index["glassmorphism"], ensure_ascii=False, indent=2))
'skillPath와 designPath에 해당하는 두 파일을 읽는다.
cat skills/glassmorphism/SKILL.md
cat skills/glassmorphism/DESIGN.mdSKILL.md의 행동 규칙과 DESIGN.md의 토큰 설명을 구분하고, 각각 누가 읽는 문서인지 한 문장씩 설명한다.완료 기준: 슬러그·표시 이름·지침 경로·설명 경로를 직접 찾고, 목록 파일만으로 디자인 규칙 전체를 알 수 없는 이유를 설명할 수 있다.
목표: 스타일 이름의 인상과 실제로 지정된 색상·글꼴·여백 값을 구분한다.
diff의 종료 코드 1은 두 파일에 차이가 있다는 뜻이다.
diff -u skills/glassmorphism/DESIGN.md skills/brutalism/DESIGN.mdStyle Foundations 절을 비교한다. 설명 문서의 colors·typography·spacing 값이 지침 본문에 어떻게 표현됐는지 찾는다.
cat skills/brutalism/SKILL.mdColors 절이 색상 선택의 이유까지 설명하는지도 확인한다.완료 기준: 비교표의 각 행에 근거 파일과 필드가 있고, 원문에서 확인한 값과 자신이 예상한 효과를 구분한다. 설명이 부족한 항목은 추측으로 채우지 않고 추가 질문으로 남긴다.
목표: 문서 경로가 끊어진 문제와 목록 밖에 남아 있는 이미지의 차이를 직접 확인한다.
python3 -B -c '
import json
from pathlib import Path
root = Path(".")
index = json.loads((root / "skills/index.json").read_text(encoding="utf-8"))
errors = []
for slug, item in sorted(index.items()):
if item.get("slug") != slug:
errors.append(f"슬러그 불일치: {slug}")
for field in ("skillPath", "designPath"):
value = item.get(field, "")
if not value or not (root / value).is_file():
errors.append(f"문서 누락: {slug} {field}")
known = set(index)
folders = {p.name for p in (root / "skills").iterdir() if p.is_dir()}
previews = {
p.stem[:-len("-marketing")]
for p in (root / "registry-examples").glob("*-marketing.png")
}
print("연결 오류:", errors or "없음")
print("목록에 없는 폴더:", sorted(folders - known))
print("목록에 없는 미리보기:", sorted(previews - known))
print("미리보기 없는 항목:", sorted(known - previews))
'skills/index.json에서 다시 확인한다. 이미지 파일의 존재만으로 사용할 수 있는 스킬이라고 판단하지 않는다.완료 기준: 연결 오류가 없는지 확인하고, 나머지 출력은 별도로 해석한 점검표를 만든다. 항목 수를 외우는 대신 실행 시점의 목록과 실제 파일을 대조한다.
목표: 자연어 지침을 구현자가 확인할 수 있는 규칙과 검사 절차로 바꾼다.
Brand 절을 읽고, 구체적인 시각 규칙과 해석이 더 필요한 표현을 구분한다.
cat skills/tetris/SKILL.md
cat skills/claude/SKILL.mdskills/glassmorphism/SKILL.md의 Component Rule Expectations와 Quality Gates 절을 기준으로 가상의 저장 버튼과 처리 결과 안내를 설계한다.default·hover·focus-visible·active·disabled·loading·error를 검토하고, 버튼 자체의 상태인지 주변 안내에 필요한 상태인지 구분한다. 각 항목에 사용할 토큰·예상 동작·확인 방법을 적는다.다음은 원문의 요구를 구체화한 학습용 검수 항목의 예다.
대상: 저장 버튼
규칙: 키보드로 버튼에 도달하면 포커스를 눈으로 구분할 수 있어야 한다.
확인: Tab으로 이동해 표시를 확인하고 Enter 또는 Space로 실행되는지 점검한다.
금지 예: 마우스를 올렸을 때만 버튼 경계를 표시한다.
근거: skills/glassmorphism/SKILL.md의 Accessibility 절완료 기준: 관련 상태마다 규칙·확인 방법·금지 예·근거가 있는 검수표를 완성한다. 적용하지 않는 상태는 이유를 적고, 실제 화면을 구현하지 않은 항목의 판정은 미검증으로 남긴다.
앞 주의 결과물을 다음 주에 다시 사용한다. 이 저장소에 없는 실행 앱을 찾기보다, 문서의 구조·토큰·규칙·검증을 차례로 익히는 흐름이다.
| 주차 | 배울 개념 | 이 레포에서 읽을 곳 | 결과물 |
|---|---|---|---|
| 1주차 | 콘텐츠 레지스트리, 슬러그, 경로를 통한 문서 조회 | README.md의 저장소 구조·사용법, skills/index.json |
선택한 슬러그에서 두 문서로 이어지는 경로표. 목록이 제공하는 정보와 문서를 열어야 알 수 있는 정보를 구분한다. |
| 2주차 | YAML 프런트매터, 디자인 토큰, 의미에 따른 값의 이름 | skills/glassmorphism/와 skills/brutalism/의 SKILL.md·DESIGN.md |
색상·글꼴·여백 비교표. 각 값의 출처와 화면에 미칠 영향을 연결한다. |
| 3주차 | 에이전트 지침 작성, 구체적인 제약, 금지 예와 예외 처리 | skills/claude/SKILL.md와 skills/tetris/SKILL.md의 Brand·Rules: Do·Rules: Don't·Example Constraint Language |
한 스킬을 골라 만든 규칙 보강안. 원문 요구와 학습자가 추가한 제안을 구분하고, 각 규칙에 금지 예를 붙인다. |
| 4주차 | 컴포넌트 상태, 키보드 조작, 확인 가능한 접근성 요구 | skills/glassmorphism/SKILL.md의 Accessibility·Component Rule Expectations·Quality Gates |
버튼과 결과 안내의 상태별 검수표. 확인 절차와 예상 결과를 적고 실제로 확인하지 않은 판정은 미검증으로 표시한다. |
| 5주차 | 목록 무결성, 미리보기 대응 관계, 문서 유지보수 | skills/index.json·skills/·registry-examples/, 비교한 설명 문서의 Colors 절 |
과제 3의 검사 결과와 사람이 검토할 항목을 함께 담은 점검 보고서. 끊어진 경로, 미등록 자료, 설명이 부족한 근거를 구분한다. |
원문을 요약하는 데서 끝내지 말고, 그 설명을 어디서 확인했고 다음 사람이 어떻게 다시 검사할 수 있는지 적는다. 파일 연결을 검사하는 코드와 디자인 의도를 판단하는 사람의 검토는 각각 무엇을 확인하는지 분명하게 기록한다.
skills/ 아래 각 폴더의 SKILL.md가 에이전트용 지침이고 DESIGN.md가 사람용 짝꿍 문서다.skills/index.json이 스킬별 문서 경로를 알려주며, 실제 파일을 가져오는 CLI는 별도 프로젝트다.glassmorphism처럼 이 레포의 목록 키와 스킬 폴더 이름에 쓰이며, 표시용 이름인 name과 구분해서 읽는다.---로 감싼 메타데이터 구간이다. 이 레포의 SKILL.md에는 이름·설명 같은 정보가, DESIGN.md에는 색상·글꼴·여백 같은 구조화된 값도 들어 있다.DESIGN.md의 프런트매터에서 colors 아래의 primary처럼 상위 묶음과 하위 값을 읽을 때 필요하다.SKILL.md의 Style Foundations와 DESIGN.md의 프런트매터를 비교해 토큰의 실제 값을 확인할 수 있다.success·danger처럼 용도를 드러내는 이름을 사용하라는 요구가 Rules: Do에 나온다.Component Rule Expectations는 기본·포커스·비활성·처리 중·오류 등의 상태를 관련 있는 경우에 정의하도록 요구한다.Accessibility 절은 키보드 우선 조작과 눈에 보이는 포커스 표시를 요구한다.Accessibility 절에 적힌 목표이며, 문서에 이름이 있다는 사실만으로 생성된 화면의 준수 여부가 확인되는 것은 아니다.Quality Gates는 모호한 형용사만으로 규칙을 끝내지 말고 토큰·기준값·예제로 구체화하며, 접근성 요구를 구현에서 검사할 수 있게 하라고 명시한다.SKILL.md에는 TYPEUI_SH_MANAGED_START와 TYPEUI_SH_MANAGED_END가 있으며, 실제 갱신 동작을 확인할 CLI 소스는 이 레포에 없다.README.md는 -p cursor,claude 옵션으로 대상을 지정하는 CLI 사용 예를 안내한다.registry-examples/에 있는 -marketing.png 파일은 미리보기이며, 해당 이름의 스킬이 현재 등록돼 있는지는 skills/index.json으로 따로 확인한다.