Claude Skill - AI 에이전트에 Skill 추가하기

Claude Code나 Cursor 같은 AI 코딩 에이전트를 쓰다 보면 반복적으로 같은 설명을 해야 할 때가 있다. "이 프로젝트는 FSD 아키텍처를 따르니까...", "React Server Component 쓸 때는..." 같은 것들. 매번 프롬프트로 설명하기 귀찮아서 찾아보니 Skills라는 게 있더라.

 

Claude Skill이 뭔가

Skills는 AI 에이전트에게 재사용 가능한 능력을 추가하는 방법이다. 쉽게 말해 특정 작업이나 지식을 패키징해서 에이전트가 필요할 때 참조할 수 있게 만든다.

 

작동 방식

시스템 프롬프트에는 스킬 목록만 간단히 들어간다:

You have these skills available:

- docx: Create and edit Word documents
- frontend-design: Build production-grade UI components
- vercel-react-best-practices: Follow Next.js and React best practices

실제 스킬 내용(SKILL.md)은 에이전트가 필요하다고 판단했을 때만 컨텍스트에 로드된다. 이렇게 하면 토큰 소비를 최소화하면서도 필요한 지식을 제공할 수 있다.

 

스킬에 들어가는 것들

• 프롬프트: 에이전트에게 어떻게 행동할지 가이드
• 스크립트: 함께 실행할 쉘 스크립트나 도구
• 문서: 참고할 추가 자료

예를 들어 "PR 생성" 스킬이라면:

# pr-create/SKILL.md
---
name: Create Pull Request
description: Create a formatted PR using gh CLI
---

## Instructions

Use the `gh` CLI to create pull requests with this format:

**Title format:** [TYPE] Brief description
- TYPE: feat, fix, docs, refactor, etc.

**Body must include:**
- Related issue number
- Summary of changes
- Testing notes

## Example
```bash
gh pr create \
  --title "[feat] Add user authentication" \
  --body "Closes #123

Added JWT-based authentication...

Tested with..."
```
```

### 일반 프롬프트와의 차이

**일반 프롬프트:**
```
"이 코드 리뷰해줘. FSD 아키텍처 따르는지 확인하고,
TypeScript strict 모드 지키는지 체크하고,
any 타입 쓴 곳 있으면 지적해줘"

매번 입력해야 하고, 팀원마다 다르게 설명할 수 있다.

 

Skill:

npx skills add our-team/code-review

한 번 설치하면 팀 전체가 같은 기준으로 코드 리뷰를 받는다.

 

 

토큰 효율성

스킬은 필요할 때만 로드되기 때문에 토큰을 아낀다. 12개 스킬이 설치되어 있어도 실제로 사용하는 건 1~2개뿐이고, 나머지는 컨텍스트를 차지하지 않는다.

MCP 서버를 항상 로드하면 8K+ 토큰이 날아가는데, 스킬은 메타데이터만 200~300 토큰 정도 쓴다.

 

skills.sh - Skills 생태계

skills.sh는 AI 에이전트용 스킬을 모아둔 디렉토리다. npm처럼 패키지를 검색하고 설치할 수 있는 중앙 저장소라고 보면 된다.

 

 

지원하는 에이전트

현재 16개 에이전트를 지원한다:

• Claude Code: Anthropic의 CLI 코딩 에이전트
• Cursor: AI 통합 IDE
• Windsurf: Codeium의 에이전트
• Roo Code: 터미널 기반 에이전트
• GitHub Copilot: GitHub의 AI 어시스턴트
• 기타 AMP, Goose, Droid 등

대부분의 주요 코딩 에이전트가 동일한 스킬 포맷을 지원한다는 게 핵심이다. 한 번 만들면 여러 에이전트에서 쓸 수 있다.

 

 

설치 방법

# 기본 설치
npx skills add <owner/repo>

# 예시
npx skills add vercel-labs/agent-skills/vercel-react-best-practices

한 줄이면 끝이다. 복잡한 설정 없이 바로 사용할 수 있다.

 

 

통계 시스템

skills.sh는 설치 횟수를 추적한다. 어떤 스킬이 실제로 유용한지 한눈에 볼 수 있다.

• All Time: 전체 설치 수
• Trending (24h): 최근 24시간 인기 순위

현재 200개 이상의 스킬이 등록되어 있고, 상위권은 수만 건의 설치를 기록하고 있다.

 

 

누가 만드나

• Vercel: React, Next.js 베스트 프랙티스
• Anthropic: 공식 문서 작성, 디자인 스킬
• Expo: React Native 개발 스킬
• 개인 개발자들: 특정 워크플로우, 프레임워크 스킬

오픈소스 생태계처럼 누구나 기여할 수 있다.

 

 

Top 5 Skills 상세

실제로 가장 많이 사용되는 스킬 5개를 보면 개발자들이 어떤 부분에서 에이전트의 도움이 필요한지 보인다.

 

1. vercel-react-best-practices (32.3K installs)

npx skills add vercel-labs/agent-skills/vercel-react-best-practices

 

뭘 하는 스킬인가

Vercel이 공식적으로 관리하는 React 및 Next.js Best Practices다. Next.js 13+ App Router, Server Components, Streaming 같은 최신 패턴을 에이전트가 정확히 이해하도록 만든다.

 

왜 이렇게 인기인가

React 생태계가 빠르게 변하고 있다. 특히 Next.js 13에서 App Router가 도입되면서 Server/Client Component 구분이 필수가 됐다. 에이전트가 이걸 제대로 이해하지 못하면

// ❌ 에이전트가 자주 하는 실수
'use client'

export default function Page() {
  // Server Component에서 써야 할 기능을 Client에서 씀
  const data = await fetch('/api/data')
}

 

이 스킬을 설치하면:

// ✅ 올바른 패턴
export default async function Page() {
  // Server Component에서 데이터 fetch
  const data = await fetch('/api/data')
  
  return <ClientComponent data={data} />
}

// app/components/ClientComponent.tsx
'use client'

export function ClientComponent({ data }) {
  // 클라이언트 전용 로직
}

 

 

 

2. web-design-guidelines (24.5K installs)

npx skills add vercel-labs/agent-skills/web-design-guidelines

 

뭘 하는 스킬인가

웹 디자인 가이드라인을 정의한다. 색상 팔레트, 타이포그래피, 간격, 레이아웃 패턴 같은 디자인 시스템의 기본을 에이전트에게 가르친다.

 

왜 필요한가

에이전트가 생성하는 UI는 기능적으로는 작동하지만 디자인이 일관성 없고 어색한 경우가 많다.

// ❌ 에이전트가 자주 만드는 디자인
<div className="p-4 m-2 bg-blue-500">
  <h1 className="text-xl font-bold">Title</h1>
  <button className="bg-green-400 p-2 rounded">Click</button>
</div>

 

일관된 가이드라인이 없으면

• 색상이 제멋대로 (blue-500, green-400?)
• 간격이 불규칙 (p-4, m-2, p-2?)
• 타이포그래피 계층이 없음

이 스킬을 적용하면

// ✅ 일관된 디자인 시스템
<div className="p-6 space-y-4">
  <h1 className="text-3xl font-bold text-gray-900">Title</h1>
  <button className="px-4 py-2 bg-primary-600 hover:bg-primary-700 
                     text-white rounded-lg transition-colors">
    Click
  </button>
</div>

 

적용 결과

로봇 관제 대시보드 UI를 만들 때 이 스킬을 써봤는데, 버튼 스타일, 카드 레이아웃, 색상 사용이 훨씬 일관성 있게 나왔다. "좀 더 모던하게", "프로페셔널하게" 같은 애매한 피드백을 줄 필요가 없어졌다.

 

 

3. remotion-best-practices (12.4K installs)

npx skills add remotion-dev/skills/remotion-best-practices

 

뭘 하는 스킬인가

Remotion으로 프로그래매틱 비디오를 만들 때 Best Practices를 가이드한다. Remotion은 React 컴포넌트로 비디오를 작성하는 라이브러리다.

 

왜 특별한가

Remotion은 독특한 개념을 가지고 있다:

• useCurrentFrame(): 현재 프레임 번호
• interpolate(): 값을 애니메이션
• Sequence: 타임라인 관리

일반 React와 다른 부분이 많아서 에이전트가 헷갈리기 쉽다.

// ❌ 일반 React처럼 작성하면 안 됨
function Video() {
  const [opacity, setOpacity] = useState(0);
  
  useEffect(() => {
    // 프레임 기반이 아닌 시간 기반 - 작동 안 함
    setTimeout(() => setOpacity(1), 1000);
  }, []);
}

 

올바른 Remotion 패턴

// ✅ 프레임 기반 애니메이션
function Video() {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();
  
  const opacity = interpolate(
    frame,
    [0, fps], // 0~1초
    [0, 1]    // 투명 → 불투명
  );
  
  return <div style={{ opacity }}>Content</div>;
}

 

실제 활용도

설치 수가 12.4K인 걸 보면 생각보다 많은 사람들이 Remotion을 쓴다. 마케팅 비디오, 제품 데모, 소셜 미디어 콘텐츠 자동 생성에 활용하는 것 같다.

 

 

4. frontend-design (3.9K installs)

npx skills add anthropics/skills/frontend-design

 

뭘 하는 스킬인가

Anthropic이 공식적으로 제공하는 프론트엔드 디자인 스킬이다. Claude가 웹 컴포넌트, 페이지, 아티팩트를 만들 때 프로덕션 수준의 디자인을 생성하도록 가이드한다.

 

web-design-guidelines와 뭐가 다른가

web-design-guidelines는 디자인 시스템(색상, 간격, 타이포그래피)에 집중한다. frontend-design은 실제 구현 패턴(컴포넌트 구조, 인터랙션, 레이아웃)에 집중한다.

// web-design-guidelines가 가르치는 것
<button className="px-4 py-2 bg-primary-600">Button</button>

// frontend-design이 가르치는 것
function Button({ variant, size, loading, children }) {
  return (
    <button
      className={cn(
        "relative transition-all",
        variants[variant],
        sizes[size],
        loading && "cursor-not-allowed opacity-50"
      )}
      disabled={loading}
    >
      {loading && <Spinner />}
      {children}
    </button>
  );
}

 

왜 중요한가

에이전트가 만드는 UI는 종종 "AI가 만든 티"가 난다.

• 과도한 그라디언트
• 불필요한 애니메이션
• 일관성 없는 패딩
• 접근성 무시

이 스킬은 이런 AI 특유의 디자인 패턴을 피하고, 실제 프로덕션에서 쓸 수 있는 수준의 코드를 생성하도록 만든다.

 

실제 효과

Anthropic이 만든 스킬이라 Claude Code와 궁합이 좋다. 특히 Tailwind CSS를 쓸 때 클래스 조합이 훨씬 세련되게 나온다.

 

5. skill-creator (2.5K installs)

npx skills add anthropics/skills/skill-creator

 

뭘 하는 스킬인가

새로운 스킬을 만들 때 가이드해주는 메타 스킬이다. 스킬의 구조, 문서화 방법, 베스트 프랙티스를 알려준다.

 

왜 필요한가

처음 스킬을 만들려고 하면 막막하다:

• 어떤 구조로 만들어야 하나?
• 프롬프트를 어떻게 작성해야 효과적인가?
• 추가 파일은 어떻게 관리하나?

이 스킬이 가르치는 것들

# 스킬 구조
my-skill/
├── SKILL.md          # 메인 프롬프트
├── examples/         # 예시 코드
├── scripts/          # 헬퍼 스크립트
└── docs/            # 추가 문서

# SKILL.md 템플릿
---
name: My Skill
description: What this skill does
---

## When to use

[명확한 사용 시점]

## Instructions

[구체적인 지침]

## Examples

[실제 사용 예시]

 

 

정리

Claude Skill은 AI 에이전트에게 재사용 가능한 능력을 추가하는 방법이다. skills.sh를 통해 검색하고 설치할 수 있으며, 현재 Top 5는:

1. vercel-react-best-practices - React/Next.js 최신 패턴
2. web-design-guidelines - 일관된 디자인 시스템
3. remotion-best-practices - 프로그래매틱 비디오 제작
4. frontend-design - 프로덕션 수준 UI 구현
5. skill-creator - 커스텀 스킬 제작 가이드

설치는 npx skills add <owner/repo> 한 줄이면 끝이다. 팀 컨벤션이나 반복 작업을 스킬로 만들어두면 개발 속도가 확실히 빨라진다.

직접 써보고 어떤 스킬이 자신의 워크플로우에 맞는지 찾아보길 추천한다.