CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

DaleStudy 커뮤니티의 Agent Skills 모음집. AI 코딩 어시스턴트(Claude Code, Cursor, GitHub Copilot)용 재사용 가능한 스킬 정의를 제공한다.

이 저장소는 빌드 과정 없는 순수 콘텐츠 저장소다. 각 스킬은 SKILL.md 파일로 정의되며, 배포 시 단순히 ZIP으로 압축되어 dist/ 디렉토리에 .skill 확장자로 저장된다.

Development Commands

스킬 테스트 (로컬)

# 로컬 저장소에서 특정 스킬 설치 테스트
npx skills add . --skill bun --agent claude-code --global --yes

# Bun 사용 시
bunx skills add . --skill bun --agent claude-code --global --yes

설치 후 ~/.agents/skills/{skill-name} 및 ~/.claude/skills/{skill-name} (심볼릭 링크)에서 확인 가능

배포 방식

이 저장소는 GitHub를 통해 직접 배포된다. npx skills add dalestudy/skills는:

1. GitHub 저장소 클론
2. skills/ 디렉토리에서 SKILL.md 파일 읽기
3. 선택한 스킬을 ~/.agents/skills/에 설치

별도 빌드/패키징 과정 없음. skills/{skill-name}/SKILL.md 파일을 수정하면 즉시 배포된다.

CI 테스트

GitHub Actions가 자동으로 실행됨 (스케줄: 매일 11:00, 23:00 UTC):

• 모든 스킬의 설치 가능성 검증
• .github/workflows/ci.yml의 matrix.skill 배열에 명시된 스킬만 테스트 대상

새 스킬 추가 시 CI 업데이트 필수: matrix.skill 배열에 스킬명 추가

Repository Architecture

스킬 구조

각 스킬은 Agent Skills 스펙을 따른다:

skills/{skill-name}/
└── SKILL.md          # YAML frontmatter + Markdown 지시사항 (필수)

핵심 원칙:

• SKILL.md는 실행 가능한 지시사항이자 메타데이터를 포함
• description 필드는 스킬 활성화 조건을 명확히 기술 (파일 패턴, 키워드, 사용 상황)
• allowed-tools는 스킬이 요구하는 도구 권한을 선언 (예: Bash(bun:*))

SKILL.md 작성 규칙

---
name: skill-name
description: "스킬 설명 + 활성화 조건. 다음 상황에서 사용: (1) ..., (2) ..., (3) ..."
license: MIT
compatibility: 필요한 CLI 도구 (예: Requires bun CLI)
metadata:
  author: DaleStudy
  version: "1.0"
allowed-tools: Bash(command:*) Bash(another:*) # 공백으로 구분
---

# 스킬 제목

스킬 지시사항 (Markdown)

중요:

• description은 AI 에이전트가 언제 이 스킬을 사용할지 판단하는 주요 기준
• 구체적인 파일 패턴 (.stories.tsx), 키워드 (bun, CSF), 사용 상황을 명시
• allowed-tools는 권한 프롬프트 최소화를 위해 정확히 기술

배포 구조

스킬은 GitHub 저장소를 통해 직접 배포된다:

npx skills add dalestudy/skills --skill bun

위 명령은:

1. https://github.com/DaleStudy/skills 저장소 클론
2. skills/bun/SKILL.md 파일 복사
3. ~/.agents/skills/bun/에 설치

Adding New Skills

새 스킬 추가 시 반드시 /skill-creator 스킬을 사용하라:

/skill-creator

또는 "새 스킬 만들어줘"라고 요청하면 자동 활성화된다.

/skill-creator는 다음 작업을 수행:

1. SKILL.md frontmatter 형식 검증
2. description 필드의 활성화 조건 명확성 확인
3. .github/workflows/ci.yml의 matrix.skill 배열 업데이트
4. dist/ 디렉토리에 .skill 파일 생성

Current Skills

• bun: Node.js 대신 Bun 런타임 사용
• github-actions: GitHub Actions 워크플로우 작성 및 보안
• skill-creator: 새 스킬 생성 가이드
• storybook: Storybook CSF 3.0 스토리 작성
• testing: React Testing Library 및 Vitest 테스팅 모범 관례
• typescript: TypeScript 타입 정의 및 모범 관례

GitHub App 스킬 통합

자동 스킬 검증

모든 PR에서 .github/workflows/claude-code-review.yml 워크플로우가 자동으로:

1. skill-creator 설치: npx skills add . --skill skill-creator --agent claude-code --global --yes 실행
2. Claude Code 자동 활성화: SKILL.md 변경 시 skill-creator의 description 매칭으로 자동 로드
3. 검증 수행 (SKILL.md 변경 시):
   • ✅ Frontmatter YAML 문법 정확성
   • ✅ name 필드와 디렉토리명 일치
   • ✅ description 필드에 트리거 조건 포함 여부
   • ✅ .github/workflows/ci.yml의 matrix.skill 배열 업데이트 확인
   • ✅ 네이밍 규칙 (소문자, 하이픈, 최대 64자)

테스트 방법

# SKILL.md 변경을 포함한 테스트 PR 생성
mkdir -p skills/test-skill
cat > skills/test-skill/SKILL.md <<EOF
---
name: test-skill
description: "테스트 스킬"
---
# Test Skill
EOF

git add skills/test-skill/
git commit -m "test: add test-skill for validation testing"
git push origin test/skill-validation
gh pr create --title "test: Skill validation workflow" \
  --body "Testing skill-creator integration in GitHub App"

기대 결과: Claude Code가 PR에 description 필드 부족 및 CI matrix 누락을 지적하는 코멘트 생성

Important Notes

• 스킬 추가 후 CI 업데이트 필수: .github/workflows/ci.yml의 matrix.skill 배열에 새 스킬명 추가
• SKILL.md만 수정하면 됨: 빌드 과정 없음, 변경사항은 즉시 반영됨
• description 작성이 핵심: AI 에이전트가 올바른 상황에서 스킬을 활성화하도록 구체적으로 기술
• GitHub App 자동 검증: SKILL.md 변경 시 skill-creator가 자동으로 PR 리뷰에서 검증 수행

---

Referenced Files

The following files are referenced in this skill and included for context.

skills/bun/SKILL.md

---
name: bun
description: "Node.js 대신 Bun 런타임 사용을 위한 스킬. 다음 상황에서 사용: (1) 새 JavaScript/TypeScript 프로젝트 생성 시, (2) package.json 또는 의존성 관련 작업 시, (3) 스크립트 실행 또는 개발 서버 시작 시, (4) Node.js 프로젝트를 Bun으로 전환 시, (5) 'bun', 'bunx', 'bun.lockb' 키워드가 포함된 작업 시"
license: MIT
compatibility: Requires bun CLI
metadata:
  author: DaleStudy
  version: "1.0.0"
allowed-tools: Bash(bun:*) Bash(bunx:*)
---

# Bun

Node.js 대신 Bun을 기본 런타임으로 사용.

## 설치

```bash
curl -fsSL https://bun.sh/install | bash

명령어 매핑

Node.js / npm	Bun
npm install	bun install
npm install <pkg>	bun add <pkg>
npm install -D <pkg>	bun add -d <pkg>
npm uninstall <pkg>	bun remove <pkg>
npm run <script>	bun run <script> 또는 bun <script>
npx <cmd>	bunx <cmd>
node <file>	bun <file>
npm init	bun init
npm create <template>	bun create <template>

프로젝트 초기화

# 새 프로젝트
bun init

# 템플릿 사용
bun create next-app my-app
bun create vite my-app

패키지 관리

# 설치 (bun.lockb 생성)
bun install

# 의존성 추가
bun add express zod
bun add -d typescript @types/node  # devDependencies

# 삭제
bun remove lodash

lockfile: bun.lockb (바이너리). .gitignore에 추가하지 않음.

스크립트 실행

# package.json scripts
bun run dev
bun run build

# 파일 직접 실행 (TypeScript 지원)
bun index.ts
bun src/server.ts

# 단축 (run 생략 가능)
bun dev

GitHub Actions

- uses: oven-sh/setup-bun@v{N} # 최신 버전 확인: gh api repos/oven-sh/setup-bun/releases/latest --jq '.tag_name'
- run: bun install
- run: bun test