https://x.com/lucas_flatwhite/status/203

@lucas_flatwhite (lucas) "Claude Code Skills 완전 정복"

Anthropic 내부에서 수백 개의 Skills를 쓰며 터득한 진짜 노하우

Claude Code 팀이 직접 쓴 아티클이예요.. 너무 좋네요ㅠ

"Skills가 마크다운 파일 아닌가?"라고 생각하셨다면, 이 글이 그 인식을 완전히 바꿔줄 거예요.

Anthropic 내부에서 수백 개의 Skills를 실제로 운영하며 발견한 유형 분류, 작성 팁, 배포 전략까지.. 지금까지 나온 Skills 관련 글 중 가장 실용적인 내용을 담고 있어요.

↓

What are Skills?

Skills가 "그냥 마크다운 파일"이라는 건 흔한 오해예요.

핵심은 Skills가 폴더라는 점이에요. 마크다운 파일 하나가 아니라, 스크립트, 에셋, 데이터, 설정 파일까지 포함하는 구조예요. Claude는 이 폴더를 탐색하고, 필요한 파일을 발견하고, 직접 조작할 수 있어요.

Claude Code에서는 여기에 더해 동적 hooks을 등록하는 등 다양한 설정 옵션을 쓸 수 있고요. 가장 흥미로운 Skills들은 바로 이 구조와 설정을 창의적으로 활용한 것들이에요.

↓

Types of Skills

수백 개의 Skills를 분류해 보니, 반복되는 유형이 9가지로 모였어요. 좋은 Skills는 하나의 유형에 딱 맞아떨어지고, 헷갈리는 Skills는 여러 유형에 걸쳐 있는 경우가 많았어요.

우리 팀에 어떤 유형이 빠져 있는지 점검하는 체크리스트로 쓰기 좋아요.

Library & API Reference

내부 라이브러리나 Claude가 자주 틀리는 외부 SDK 사용법을 정리해요. 레퍼런스 코드 스니펫과 주의해야 할 함정(gotchas) 목록이 핵심이에요.

(billing-lib, internal-platform-cli, frontend-design)

Product Verification

코드가 실제로 잘 동작하는지 검증하는 Skills예요. Playwright, tmux 같은 외부 도구와 짝을 이루는 경우가 많아요.

출력 결과를 영상으로 녹화하거나, 각 단계마다 상태를 단언하는 스크립트를 포함하면 강력해져요.

(signup-flow-driver, checkout-verifier, tmux-cli-driver)

Data Fetching & Analysis

데이터 스택과 모니터링 툴에 연결하는 Skills예요. 자격증명이 포함된 쿼리 라이브러리, 대시보드 ID, 일반적인 데이터 조회 패턴을 담아요.

(funnel-query, cohort-compare, grafana)

Business Process & Team Automation

반복 작업을 커맨드 하나로 자동화하는 Skills예요. 다른 Skills나 MCP와 조합할수록 강력해지고요.

이전 실행 결과를 로그 파일에 남겨두면 다음 실행 때 일관성을 유지하기 좋아요.

(standup-post, create-ticket, weekly-recap)

Code Scaffolding & Templates

코드베이스 내 특정 기능의 보일러플레이트를 생성해요. 코드만으로는 다 표현 못하는 자연어 요구사항이 있을 때 특히 유용해요.

(new-workflow, new-migration, create-app)

Code Quality & Review

조직 내 코드 품질을 강제하고 리뷰를 도와요. 결정론적 스크립트를 포함하면 더 강해지고, 훅이나 GitHub Action으로 자동화할 수도 있어요.

(adversarial-review, code-style, testing-practices)

CI/CD & Deployment

코드 빌드, 배포, 롤백을 다루는 Skills예요. 데이터를 수집하는 다른 Skills와 연계해서 써요.

(babysit-pr, deploy-service, cherry-pick-prod)

Runbooks

증상(Slack 메시지, 알림, 에러 시그니처)을 받아 다중 도구 조사를 수행하고 구조화된 보고서를 만들어요.

(service-debugging, oncall-runner, log-correlator)

Infrastructure Operations

정기 유지보수와 운영 절차를 자동화해요. 파괴적인 작업에 가드레일을 붙일 수 있어서 베스트 프랙티스를 따르기가 훨씬 쉬워져요.

(resource-orphans, dependency-management, cost-investigation)

↓

Don't State the Obvious

Claude Code는 이미 코드베이스에 대해 많이 알고 있고, Claude 자체도 코딩에 대한 기본 의견이 있어요.

지식 중심의 Skills를 만들 때는 Claude의 일반적인 사고방식에서 벗어나게 만드는 정보에 집중하세요.

프론트엔드 디자인 Skills가 좋은 예예요. Inter 폰트와 보라색 그라디언트처럼 Claude가 기본으로 내놓는 패턴을 피하는 법을 Anthropic 엔지니어가 고객들과 반복해서 만들어 낸 결과물이거든요.

↓

Build a Gotchas Section

Skills에서 가장 신호 밀도가 높은 내용은 Gotchas 섹션이에요.

Claude가 실제로 실수했던 지점들을 누적해서 쌓아두는 공간이에요.

Skills를 처음 만들 때부터 넣기보다, Claude가 새로운 엣지 케이스를 만날 때마다 업데이트해 나가는 게 이 섹션을 풍성하게 만드는 방법이에요.

↓

Use the File System & Progressive Disclosure

Skills는 폴더! 파일 시스템 전체를 컨텍스트 엔지니어링과 점진적 공개의 수단으로 생각하면 좋아요.

Claude에게 어떤 파일들이 있는지 알려주면, 필요한 순간에 알아서 읽어요.

자세한 함수 시그니처는 references/api.md로 분리
최종 결과물 템플릿은 assets/에 포함
레퍼런스, 스크립트, 예시를 각각 폴더로 구분

이 구조 덕분에 Claude는 처음부터 모든 걸 읽지 않고, 필요한 정보를 필요한 시점에 꺼내볼 수 있어요.

↓

Avoid Railroading Claude

Claude는 기본적으로 지침을 따르려고 해요. 그래서 Skills가 너무 재사용될 만큼 구체적이면 오히려 문제가 생길 수 있어요.

필요한 정보는 충분히 주되, 상황에 맞게 적응할 여지를 남겨두세요. 정답을 알려주기보다 판단 기준을 주는 방식이 더 효과적이에요.

↓

Think through the Setup

어떤 Skills는 사용자로부터 초기 정보가 필요해요. 예를 들어 스탠드업을 Slack에 올리는 Skills라면, 어느 채널에 올릴지 물어봐야 하죠.

좋은 패턴은 config.json 파일에 설정 정보를 저장하는 거예요.

설정이 아직 없다면 Claude가 사용자에게 물어보도록 만들고, 구조화된 질문이 필요하다면 AskUserQuestion 도구를 쓰게 하면 좋아요.

↓

The Description Field Is For the Model

Claude Code가 세션을 시작하면, 사용 가능한 모든 Skills를 description과 함께 목록으로 만들어요.

이 목록을 보고 "이 요청에 맞는 Skills가 있나?"를 판단해요.

description은 요약이 아니라 트리거 조건이에요. "언제 이 Skills를 써야 하는지"를 명확히 적어야, Claude가 적시에 꺼내 쓸 수 있어요.

↓

Memory & Storing Data

Skills 안에 데이터를 저장해서 일종의 메모리를 만들 수 있어요. 텍스트 로그 파일, JSON, 심지어 SQLite까지 다양하게 활용돼요.

예를 들어 standup-post Skills가 standups.log를 계속 쌓아두면, 다음 실행 때 어제와 달라진 점을 파악할 수 있어요.

Skills 디렉토리 안에 저장된 데이터는 업그레이드 시 삭제될 수 있어요. 안정적으로 보존하려면 ${CLAUDE_PLUGIN_DATA} 폴더를 쓰는 게 좋아요.

↓

Store Scripts & Generate Code

Claude에게 줄 수 있는 가장 강력한 도구 중 하나는 코드 자체예요.

스크립트와 헬퍼 라이브러리를 Skills에 포함해두면, Claude는 보일러플레이트를 매번 새로 만드는 대신 "다음엔 뭘 할까"를 고민하는 데 컨텍스트를 집중할 수 있어요.

데이터 분석 Skills라면, 이벤트 소스에서 데이터를 가져오는 헬퍼 함수 모음을 Skills 폴더에 넣어두는 식으로요.

↓

On Demand Hooks

Skills에는 해당 Skills가 호출될 때만 활성화되고, 세션이 끝나면 사라지는 훅을 포함할 수 있어요.

항상 켜두기는 부담스럽지만, 특정 상황에선 꼭 필요한 훅에 딱 맞아요.

/careful — rm -rf, DROP TABLE, force-push를 차단. 프로덕션 작업할 때만 켜는 용도
/freeze — 지정한 디렉토리 밖의 Edit/Write를 막아요. "로그만 추가하고 싶은데 다른 걸 자꾸 고치네"라는 상황에서 유용해요

↓

Distributing Skills

Skills를 팀과 나누는 방법은 두 가지예요.

레포에 직접 포함: ./.claude/skills 아래에 체크인하는 방식. 소규모 팀, 소수의 레포에서 잘 동작해요.
플러그인 마켓플레이스: 내부 마켓플레이스를 만들어 팀원이 필요한 것만 골라 설치하는 방식.

레포에 체크인된 Skills는 모두 모델 컨텍스트를 조금씩 소모하기 때문에, 팀과 레포가 많아질수록 마켓플레이스가 더 효율적이에요.

↓

Managing a Marketplace

중앙에서 무엇을 올릴지 결정하지 않아요. 대신 자연스럽게 인기 있는 Skills를 찾아가는 방식이에요.

써보고 싶은 Skills가 있다면, GitHub의 sandbox 폴더에 올리고 Slack으로 공유해요. 충분히 검증됐다고 판단되면 마켓플레이스로 PR을 올리는 식이에요.

나쁜 Skills나 중복 Skills는 생각보다 쉽게 생겨요. 마켓플레이스에 올리기 전에 큐레이션 과정을 두는 게 중요해요.

↓

Composing Skills

Skills끼리 의존 관계를 만들 수 있어요.

예를 들어 파일 업로드 Skills와 CSV 생성 Skills가 있다면, CSV 생성 Skills가 업로드 Skills를 이름으로 참조하면 되고, 설치만 돼 있으면 Claude가 알아서 연계해서 써요.

의존성 관리가 아직 네이티브하게 지원되진 않지만, 이름 참조 방식으로 충분히 구성할 수 있어요.

↓

Measuring Skills

PreToolUse 훅을 이용해 Skills 사용 로그를 쌓을 수 있어요.

이걸 활용하면 어떤 Skills가 인기 있는지, 어떤 Skills가 예상보다 덜 불리는지 파악할 수 있어요.

Skills의 description을 개선할 때 데이터 기반으로 판단할 수 있게 되죠.

↓

결국 모든 Skills는 "몇 줄짜리 지침 + 함정 하나"로 시작했어요.

Claude가 새로운 엣지 케이스를 만날 때마다 조금씩 더해진 것들이 쌓여서, 지금의 수백 개가 됐고요.

정답을 찾아서 만들기보다, 지금 막히는 지점 하나를 Skills로 만들어 시작하는 게 가장 빠른 방법! ![[tweet_2034051480785932580_0.jpg]] ![[tweet_2034051480785932580_1.jpg]] ![[tweet_2034051480785932580_2.jpg]] ![[tweet_2034051480785932580_3.jpg]]

출처: https://x.com/lucas_flatwhite/status/2034051480785932580?s=52&t=isYWfF2KYWH97rviyUmcRQ

https://x.com/lucas_flatwhite/status/203

관련 노트