안녕하세요! SYDE 에디터 사이드입니다 👋

터미널 환경에서 코딩을 도와주는 클로드 코드(Claude Code)가 대세로 떠오르면서, 내 프로젝트의 맥락을 AI에게 주입하기 위해 '스킬(Skills)' 기능을 써보신 분들이 많을 겁니다.

대부분 .claude/skills 폴더에 SKILL.md 마크다운 파일 하나를 덜렁 만들어두고, "Next.js 컴포넌트는 이렇게 짜줘", "플러터(Flutter) 상태 관리는 이런 패턴을 써줘"라고 몇 줄 적어두는 데 그치곤 하죠.

하지만 앤스로픽(Anthropic) 내부에서 수백 개의 스킬을 직접 굴리고 있는 엔지니어 타리크 쉬히파르(Thariq Shihipar)는 우리의 이런 얄팍한 사용법에 묵직한 팩트폭력을 날립니다.

스킬을 단순히 '텍스트 지시문'으로만 쓴다면, 당신은 이 기능의 10%도 쓰지 못하고 있는 겁니다.

스킬은 텍스트 쪼가리가 아니라, 마크다운, 스크립트, 데이터베이스까지 모두 품을 수 있는 '폴더(Folder)'이자 프로그래밍 가능한 컨텍스트입니다. 이 폴더를 어떻게 구조화해야 하는지, 앤스로픽 엔지니어가 직접 밝힌 '클로드 스킬 7대 설계 원칙'을 낱낱이 파헤쳐보겠습니다.

1) 당연한 뻔한 소리는 지워라 (기본값 부수기)

• 클로드는 이미 코딩을 아주 잘합니다. "클린 코드로 짜줘" 같은 말은 토큰 낭비입니다.

• 스킬에는 클로드가 기본적으로 하는 행동 중 '내가 억지로 바꾸고 싶은 습관'만 적어야 합니다.

• 예: "제발 뻔한 보라색 그라디언트나 전형적인 AI 디자인 패턴 좀 그만 써라."

2) 'Gotchas(흔한 삽질 노트)'가 전부다

• 타리크가 7가지 중 가장 가치가 높다고 단언한 섹션입니다.

• 클로드가 내 플러터 앱에서 상태 관리를 짤 때마다 반복해서 내는 에러가 있다면, 그 실패 사례와 해결책을 기록해 두는 겁니다.

• 실패 사례가 스킬에 쌓일수록, AI는 당신의 프로젝트에서 같은 실수를 두 번 다시 반복하지 않습니다.

3) 마크다운이 아니라 '파일 시스템'을 써라

• 모든 정보를 SKILL.md 파일 하나에 우겨넣지 마세요. 스킬은 폴더입니다.

• 메인 파일에는 전체 구조와 각 파일의 역할만 적고, 세부 API 스펙이나 디자인 가이드는 하위 파일로 쪼개세요.

• 예: "Next.js 라우팅 에러가 나면 errors/routing.md 파일을 읽어봐"라고 지시하면, 클로드가 필요할 때만 문서를 열어보며 컨텍스트 과부하를 막아냅니다.

4) 너무 촘촘한 통제(Over-constraint)는 독이다

• 스킬은 결국 재사용을 위한 도구입니다. 예외 없이 빡빡하게 규칙을 얽어매면 AI의 유연한 문제 해결 능력이 죽어버립니다.

• 명확한 가드라인은 주되, 클로드가 상황에 맞게 코드를 응용할 수 있는 숨통은 트여주어야 훨씬 똑똑한 결과물이 나옵니다.

5) 변수를 하드코딩하지 말고 '비워두어라'

• 모든 값을 스킬 안에 고정해 두지 마세요. 실행할 때 유저(메이커)에게 물어보도록 변수 처리를 해두는 것이 좋습니다.

• 이렇게 하면 스킬 파일을 매번 뜯어고칠 필요 없이, "어떤 컴포넌트를 테스트할까요?"라는 클로드의 질문에 답하는 것만으로 상황에 맞게 스킬을 재활용할 수 있습니다.

6) Description은 설명서가 아니라 '트리거(호출 버튼)'다

• 세션이 시작되면 클로드는 각 스킬의 description을 읽고 언제 이 스킬을 쓸지 판단합니다.

• 따라서 이곳에 스킬의 장황한 설명을 적는 것은 무의미합니다.

• 대신 "코드 리뷰해 줘", "플러터 버그 찾아줘", "배포 점검해 줘"처럼 클로드가 이 스킬을 꺼내 들어야 하는 명확한 상황(트리거)을 적어두세요.

7) 매번 백지에서 시작하지 마라 (메모리 축적)

• 스킬의 실행 결과를 텍스트, JSON, SQLite 등의 형태로 파일에 계속 쌓아두게 만드세요.

• "이전 실행 로그를 확인해"라는 룰을 추가하면, 클로드는 매번 백지에서 시작하는 게 아니라 이전의 성공과 실패 히스토리를 누적하며 진짜 '내 프로젝트의 팀원'처럼 진화합니다.

🎙️ 에디터의 한 마디

💡 "클로드가 내 맘대로 코드를 안 짠다면, 그건 내 프로젝트의 룰을 제대로 폴더화해서 쥐여주지 않았기 때문입니다."

기획부터 개발까지 홀로 아우르는 1인 메이커일수록 내 머릿속에만 존재하는 앱의 아키텍처와 비즈니스 로직이 방대할 수밖에 없습니다.

매번 프롬프트 창에 똑같은 지시를 복사해 붙여넣는 수동 노동은 이제 멈춰야 합니다.

"AI가 자꾸 멍청한 코드만 짠다"고 불평하기 전에, 오늘 당장 프로젝트 최상단에 스킬 폴더를 파고 내가 가장 지긋지긋해하는 에러들을 Gotchas 노트에 정리해 보세요.

스킬을 다루는 디테일이 곧 내 디지털 팀원의 연봉(생산성)을 결정짓습니다.

🔗 원본 글 링크: https://x.com/trq212/status/2033949937936085378