Supabase Agent Skills 사용하기

Agent Skills는 Claude Code, Cursor, GitHub Copilot 등 AI 코딩 에이전트가 특정 작업을 더 정확하게 수행하도록 돕는 지침·스크립트·리소스 묶음입니다. Supabase는 supabase/agent-skills 저장소를 통해 Supabase 관련 작업에 특화된 공식 Skill을 제공합니다.

공식 문서: supabase.com/docs/guides/getting-started/ai-skills

Agent Skill이란?

Skill은 단순한 프롬프트 조각이 아니라, 에이전트가 필요한 순간에 동적으로 로드하는 폴더 단위의 지식 팩입니다. 예를 들어 "Supabase에 테이블 만들어줘" 같은 요청이 들어왔을 때, 에이전트는 Supabase Skill에 포함된 마이그레이션 작성 규칙·RLS 설정 패턴·Edge Function 배포 절차 등을 참조해 더 일관된 결과를 냅니다.

Skill	용도
`supabase`	Supabase 전반(인증, DB, Storage, Edge Functions, Realtime, MCP 연동 등) 종합 Skill
`supabase-postgres-best-practices`	Postgres 성능 최적화 가이드(인덱스, 쿼리 튜닝, RLS 성능 등)

정보

Skill은 Claude Code, Cursor, Cline, GitHub Copilot 등 18종 이상의 에이전트에서 호환됩니다. 한 번 설치하면 여러 툴에서 재사용할 수 있습니다.

사전 준비

Node.js >= 20.0 (npx 사용을 위해 필요)
Claude Code 또는 Cursor 등 Skill 호환 에이전트
Supabase 프로젝트 (Supabase 소개 참고)

설치 방법

방법 A: Skills CLI로 설치 (권장)

Skills CLI는 에이전트별 표준 위치(~/.claude/skills/, .cursor/skills/ 등)에 Skill을 복사해주는 범용 도구입니다.

전체 Supabase Skill 묶음 설치:

npx skills add supabase/agent-skills

특정 Skill만 설치:

# Supabase 종합 Skill
npx skills add supabase/agent-skills --skill supabase

# Postgres 성능 튜닝 Skill
npx skills add supabase/agent-skills --skill supabase-postgres-best-practices

설치 시 대상 에이전트(Claude Code / Cursor / Cline 등)를 선택하는 프롬프트가 뜹니다.

방법 B: Claude Code 플러그인으로 설치

Claude Code를 주로 쓴다면 내장 플러그인 마켓플레이스를 통해 설치하는 것이 더 매끄럽습니다.

Claude Code 세션에서 마켓플레이스 등록
```
/plugin marketplace add supabase/agent-skills
```

플러그인 설치

/plugin install supabase@supabase-agent-skills

설치 완료 후 세션을 재시작하면 Skill이 자동으로 활성화됩니다.

사용 방법

Skill은 자동 로드 방식이라 특별히 호출할 필요가 없습니다. 에이전트가 작업 내용을 분석해 관련 Skill을 스스로 선택합니다.

예시 프롬프트:

posts 테이블을 만들고, 작성자만 자기 글을 수정할 수 있도록 RLS 정책을 설정해줘

Claude Code는 이 요청을 받으면:

supabase Skill의 테이블 생성 + RLS 지침을 참조
supabase-postgres-best-practices Skill의 RLS 성능 팁(인덱스, (select auth.uid()) 패턴 등) 적용
마이그레이션 파일 생성 → MCP로 적용까지 한 번에 처리

수동으로 Skill 호출

Claude Code에서 명시적으로 Skill을 쓰고 싶다면 슬래시 커맨드로 호출할 수 있습니다.

/skill supabase

다른 Skill 탐색하기

npx skills find supabase
npx skills find postgres

또는 브라우저에서 skills.sh 디렉토리를 둘러볼 수 있습니다.

MCP와의 차이

Supabase는 이미 Claude Code에서 Supabase MCP 연동 가이드에서 다룬 MCP 서버를 제공합니다. 둘의 역할은 다음과 같이 나뉩니다.

구분	MCP 서버	Agent Skill
역할	실제 Supabase API/DB에 행동(execute) 을 수행	작업 수행에 필요한 지식/절차 제공
예시	"SQL 실행", "마이그레이션 적용", "타입 생성"	"RLS 설계 원칙", "인덱스 전략", "Edge Function 구조"
런타임	서버 프로세스로 상주, 툴 콜로 호출	파일 묶음, 필요 시 컨텍스트에 로드

둘을 함께 쓰면 가장 강력합니다. Skill이 "어떻게 설계할지"를 알려주고, MCP가 그 설계를 "실제 적용"하는 구조입니다.

팁

Skill은 업데이트가 잦으므로 주기적으로 npx skills add supabase/agent-skills 를 재실행해 최신 버전으로 동기화하세요.
팀에서 공용으로 쓰려면 레포지토리 루트의 .claude/skills/ 경로에 체크인하면 모든 팀원이 동일한 Skill을 공유할 수 있습니다.
Skill 사용 여부는 에이전트가 자율적으로 결정하므로, 특정 Skill의 규칙을 꼭 따르게 하려면 프롬프트에 "supabase skill을 참고해서" 같이 명시해주면 안정적입니다.

Agent Skill이란?​

사전 준비​

설치 방법​

방법 A: Skills CLI로 설치 (권장)​

방법 B: Claude Code 플러그인으로 설치​

사용 방법​

수동으로 Skill 호출​

다른 Skill 탐색하기​

MCP와의 차이​

팁​