Agent skill

understanding-project

프로젝트 구조, 아키텍처, 기술 스택, 패키지 역할 등 전반적인 이해가 필요할 때 사용. 코드가 어디에 있는지, 패키지 간 의존성이 어떤지, 왜 이 구조인지 궁금하면 이 스킬. Triggers: "모노레포 구조가 어떻게 돼", "기술 스택", "export 충돌", "패키지 간 의존성", "프로젝트 구조", "어떤 패키지에 있어", "파일 어디에 있어", "아키텍처", "디렉터리 구조", "코드 위치", "모듈 역할", "어떤 기술 쓰고 있어", "스택", "의존성". Covers the monorepo architecture, package roles, tech stack, and coding conventions.

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/greenheadHQ/awesome-anki/tree/main/.claude/skills/understanding-project

SKILL.md

프로젝트 이해

Anki 카드를 원자적 단위로 분할하는 웹 앱. 정보 밀도 높은 카드를 AI(Gemini/OpenAI)로 학습 효율 좋은 작은 카드로 분리.

모노레포 구조

awesome-anki/
├── packages/
│   ├── core/      # 핵심 로직 — 파서, 분할, 검증, 임베딩, 프롬프트
│   ├── server/    # Hono REST API (localhost:3000)
│   └── web/       # React 19 + Vite 프론트엔드 (localhost:5173)
├── data/          # split-history.db (SQLite, SoT는 MiniPC)
└── output/        # backups/, embeddings/, prompts/

기술 스택

영역 기술
런타임 Bun (npm 아님)
언어 TypeScript
LLM 멀티 프로바이더 (Gemini + OpenAI), factory 패턴
백엔드 Hono (REST API)
프론트엔드 React 19 + Vite
스타일링 Tailwind CSS v4 (@tailwindcss/postcss 플러그인)
상태 관리 TanStack Query
렌더링 markdown-it + KaTeX + highlight.js

패키지별 핵심 모듈 (packages/core/src/)

모듈 역할
anki/ AnkiConnect API 래퍼 + 학습난이도 탐지(difficulty.ts) — working-with-anki 스킬 참조
llm/ 멀티 LLM 추상화 (factory, adapter, pricing)
gemini/ Gemini 전용 API (분할 프롬프트, cloze-enhancer, zod 응답 검증)
parser/ 텍스트 파싱 (container, nid, cloze) — splitting-cards 스킬 참조
splitter/ Split 로직 — splitting-cards 스킬 참조
validator/ 카드 검증 4종 — validating-cards 스킬 참조
embedding/ OpenAI 임베딩 (text-embedding-3-large, 3072차원) — managing-embeddings 스킬 참조
prompt-version/ 프롬프트 버전 관리 — managing-prompts 스킬 참조
utils/ HTML 스타일 보존, diff-viewer, 원자적 파일 쓰기

export 규칙

packages/core/src/index.ts에서 명시적 named export 사용. export *는 이름 충돌 발생 (SplitCard, validateStylePreservation 등).

충돌 방지를 위해 prompt-version 함수는 접두사 사용:

  • listVersions → listPromptVersions
  • getVersion → getPromptVersion

실행 방법

bash
bun run dev          # 서버 + 클라이언트 동시 실행
bun run dev:server   # 서버만 (localhost:3000)
bun run dev:web      # 클라이언트만 (localhost:5173)

자주 발생하는 문제

  • bun install 사용: npm install 금지
  • export 충돌: 새 모듈 추가 시 index.ts에서 개별 항목 나열
  • Tailwind v4: tailwindcss init 대신 @tailwindcss/postcss 플러그인 사용
  • 포트 충돌: lsof -ti:3000 | xargs kill -9로 정리 후 재시작

상세 참조

  • references/architecture.md — 모노레포 상세 구조, 패키지 역할
  • references/tech-stack.md — Bun, Hono, React 19, Tailwind v4 상세
  • references/conventions.md — export 규칙, 실행 방법, 모노레포 설정
  • references/troubleshooting.md — 구조/실행 관련 자주 발생하는 문제 해결

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

greenheadHQ/awesome-anki

validating-cards

USE THIS SKILL for card content validation — fact-checking, freshness, similarity, context consistency, or anything about duplicate detection and card quality. Triggers: "팩트 체크 결과가", "유사한 카드 찾아줘", "문맥 검증", "검증 캐시", "최신성 검사", "중복 카드", "검증 상태 아이콘", "validate/all", "Jaccard", "임베딩 유사도", "중복 판정", "useValidateCard", "useBatchValidate", "검증 4종", "일괄 검증", "context-checker", "fact-checker", "freshness-checker", "similarity-checker", "findSimilarGroups", "analyzeCardGroup", "검증 폴백". Covers the 4 validation types: fact-check, freshness, similarity, context.

0 0
Explore
greenheadHQ/awesome-anki

developing-web-ui

React 프론트엔드의 컴포넌트, 훅, 렌더링, 스타일 관련 작업이면 반드시 이 스킬을 먼저 확인할 것. Triggers: "React 컴포넌트 추가", "ContentRenderer 수정", "TanStack Query", "CSS 충돌", "웹 UI 버그", "페이지 추가", "Tailwind 스타일", "렌더링 문제", "shadcn", "shadcn 컴포넌트", "shadcn 마이그레이션", "variant API", "UI 마이그레이션", "마이그레이션", "toast", "sonner", "Toaster", "DiffViewer", "ContentPreview", "BottomSheet", "CompactSelector", "markdown 렌더링", "모바일 반응형", "useMediaQuery", "useIsMobile", "훅 추가", "query hook", "캐시 무효화", "staleTime", "분할 미리보기 UI", "분할 반려 UI", "카드 브라우저", "어려운 카드". Covers the React frontend, components, hooks, query patterns, rendering pipeline, and UI troubleshooting.

0 0
Explore
greenheadHQ/awesome-anki

managing-embeddings

USE THIS SKILL for anything related to embeddings, vector similarity, or semantic search. Triggers: "임베딩 생성", "코사인 유사도", "캐시 어디에", "임베딩 상태", "의미 유사도", "text-embedding-3-large", "openai embedding", "벡터 차원", "3072", "임베딩 캐시", "embedding 마이그레이션", "레거시 캐시", "embedding fallback", "유사도 검사 임베딩 모드", "임베딩 배치", "rate limit 429". Covers OpenAI embedding API, file-based cache with migration, and text preprocessing.

0 0
Explore
greenheadHQ/awesome-anki

managing-llm

LLM 추상화 계층, 프로바이더 어댑터, 가격표, 예산 가드 등 LLM 관련 작업이면 무조건 이 스킬. 모델 변경, 프로바이더 추가, 비용 계산, 토큰 카운트 등 모든 LLM 인프라를 다룬다. Triggers: "LLM 모델 변경", "프로바이더 추가", "비용 추정", "예산 가드", "pricing table", "모델 비교", "LLM 비용", "토큰 사용량", "모델 추가", "LLM 설정", "Gemini", "OpenAI", "API key", "model pricing", "budget cap", "token count", "adapter", "factory".

0 0
Explore
greenheadHQ/awesome-anki

working-with-anki

AnkiConnect 연결, 카드/덱/모델 조회, 학습 데이터 복제, 백업/롤백, 어려운 카드 탐지, 커스텀 config 액션 등 Anki와의 모든 상호작용을 다룬다. Triggers: "AnkiConnect 연결", "test 프로필", "ease factor 복제", "카드 정보 조회", "학습 데이터", "AnkiConnect API", "Anki 프로필", "카드 모델", "어려운 카드", "난이도 탐지", "difficulty", "백업", "롤백", "분할 적용", "scheduling", "스케줄링", "getConfig", "setConfig", "커스텀 액션". Covers AnkiConnect API wrapper, scheduling clone, backup/rollback, difficulty detection, and custom config actions.

0 0
Explore
greenheadHQ/awesome-anki

splitting-cards

카드 분할 로직, LLM 기반 Split, nid 승계 전략, 텍스트 파서, 비용 추정, 배치 분할 등 카드 분할의 모든 측면을 다룬다. Triggers: "Split 결과가 이상해", "파서 버그", "분할 미리보기", "nid 승계", "Cloze 번호 리셋", "컨테이너 파서", "카드 분할", "atomic card", "분할 비용", "split cost", "배치 분할", "batch split", "분할 적용", "split apply", "분할 검증", "스타일 보존". Covers Split logic, nid inheritance strategy, text parsers, cost estimation, batch split, and split validation.

0 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results