AGENTS.md · diff

git:20261013.31c7767 to git:20261018.81d1207

4 added, 10 removed. Audit A to A.

# 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

### 스킬 테스트 (로컬)

```bash

# 로컬 저장소에서 특정 스킬 설치 테스트

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` 배열에 스킬명 추가

+ - `skills/` 아래 모든 스킬의 설치 가능성 검증 (스킬을 추가해도 CI를 고칠 필요 없음)

## Repository Architecture

### 스킬 구조

각 스킬은 [Agent Skills 스펙](https://agentskills.io/specification)을 따른다:

```

skills/{skill-name}/

└── SKILL.md # YAML frontmatter + Markdown 지시사항 (필수)

```

**핵심 원칙:**

- SKILL.md는 **실행 가능한 지시사항이자 메타데이터**를 포함

- `description` 필드는 **스킬 활성화 조건**을 명확히 기술 (파일 패턴, 키워드, 사용 상황)

- `allowed-tools`는 스킬이 요구하는 도구 권한을 선언 (예: `Bash(bun:*)`)

### SKILL.md 작성 규칙

```yaml

---

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 저장소를 통해 직접 배포된다:

```bash

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` 스킬을 사용**하라:

```bash

/skill-creator

```

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

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

1. SKILL.md frontmatter 형식 검증

2. `description` 필드의 활성화 조건 명확성 확인

- 3. `.github/workflows/ci.yml`의 `matrix.skill` 배열 업데이트

- 4. `dist/` 디렉토리에 `.skill` 파일 생성

+ 3. `dist/` 디렉토리에 `.skill` 파일 생성

## Current Skills

- **bun**: Node.js 대신 Bun 런타임 사용

- **cloudflare**: Cloudflare 사용 규칙 (Workers 배포, 시크릿 관리)

- **git**: Git 버전 관리 모범 관례 및 워크플로우

- **github-actions**: GitHub Actions 워크플로우 작성 및 보안

- **mcp**: MCP(Model Context Protocol) 서버 생성·구현

- **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` 실행

+ 1. **skill-creator 설치**: `npx skills add dalestudy/skills@skill-creator --agent claude-code --yes` 실행 (PR이 아니라 `main`의 skill-creator로 검증)

2. **Claude Code 자동 활성화**: SKILL.md 변경 시 skill-creator의 `description` 매칭으로 자동 로드

3. **검증 수행** (SKILL.md 변경 시):

- ✅ Frontmatter YAML 문법 정확성

- ✅ `name` 필드와 디렉토리명 일치

- ✅ `description` 필드에 트리거 조건 포함 여부

- - ✅ `.github/workflows/ci.yml`의 `matrix.skill` 배열 업데이트 확인

- ✅ 네이밍 규칙 (소문자, 하이픈, 최대 64자)

### 테스트 방법

```bash

# 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 누락을 지적하는 코멘트 생성

+ **기대 결과:** Claude Code가 PR에 `description` 필드의 트리거 조건 누락을 지적하는 코멘트 생성

## Important Notes

- - **스킬 추가 후 CI 업데이트 필수**: `.github/workflows/ci.yml`의 `matrix.skill` 배열에 새 스킬명 추가

- **SKILL.md만 수정하면 됨**: 빌드 과정 없음, 변경사항은 즉시 반영됨

- **`description` 작성이 핵심**: AI 에이전트가 올바른 상황에서 스킬을 활성화하도록 구체적으로 기술

- **GitHub App 자동 검증**: SKILL.md 변경 시 skill-creator가 자동으로 PR 리뷰에서 검증 수행