Claude Code Skills: 자신만의 도구 만드는 방법

Claude Code 에이전트는 전체 모노레포를 리팩토링하고 데이터베이스 마이그레이션까지 스스로 작성할 수 있지만, 만약 사용자가 권한 대화 상자에 클릭해야 하는 상황이라면 아무도 보고 있지 않은 터미널 앞에서 침묵하게 됩니다. Claude Code의 Skills는 바로 이러한 종류의 사각지대를 해결해 주며, MIT 라이선스로 공개된 big-arrow-on-the-screen 저장소는 이를 보여주는 실제 사례입니다: macOS의 모든 창 위에 거대한 화살표를 그려서 어떤 버튼을 눌러야 할지 알려줍니다.

흥미로운 점은 이 화살표 자체가 아닙니다. 모델의 코드를 한 줄도 건드리지 않고 에이전트와 연결하는 메커니즘입니다. 본 기사는 이 실제 프로젝트를 사례 연구로 사용하여 skill이 무엇인지, 모델이 어떻게 이를 발견하는지, 그리고 처음부터 자신만의 에이전트 확장을 구축하는 방법을 설명합니다.

요약 (TL;DR)

• YAML을 포함한 SKILL.md 파일 하나만으로 Claude Code가 새로운 skill을 발견하고 활성화할 수 있습니다.
• big-arrow-on-the-screen은 데몬이 없는 Swift 바이너리와 bigarrow install-skill을 통해 설치 가능한 skill을 결합합니다.
• 프론트매터(frontmatter)에 모호한 설명만으로는 아무리 유용하더라도 모델의 선택을 얻을 수 없습니다.
• 셸 스크립트나 모든 실행 가능한 바이너리가 독점 SDK 없이도 skill의 실제 본체가 될 수 있습니다.
• MCP는 에이전트를 상태를 가진 외부 시스템과 연결하며, skill은 서버를 올리지 않고 특정 작업을 해결합니다.

Claude Code Skills란 무엇인가요?

Claude Code의 Skills는 에이전트의 기본 코드를 수정하지 않으면서 에이전트가 할 수 있는 것을 확장하는 일련의 지침, 메타데이터 및 선택적 스크립트 패키지입니다. 각 skill은 SKILL.md 파일과 함께 폴더에 존재합니다. 모델은 먼저 그 설명을 읽고, 요청된 작업에만 해당할 경우 나머지 내용을 로드합니다.

이것을 신입 직원의 책상 위에 놓인 매뉴얼 라이브러리로 생각해 보세요. 아무도 첫날 40개의 매뉴얼을 외우지 않지만, 고객이 특정 질문을 할 때 직원은 올바른 매뉴얼을 찾아 읽고 그제야 행동합니다. Claude Code도 똑같습니다. 짧은 이름과 설명을 목록으로 유지하다가, 사용자의 요청이 해당 설명과 일치할 때만 스킬의 전체 내용을 열어줍니다.

이 메커니즘을 **점진적 공개(progressive disclosure)**라고 부릅니다. 모든 설치된 스킬이 지속적으로 컨텍스트 공간을 소모하는 것을 방지합니다. 100개의 스킬을 설치했을 때 드는 비용은, 실제로는 100줄의 이름과 설명이지, 100개의 전체 문서가 로드되는 것이 아닙니다. 이 폴더는 SKILL.md 외에도 지침이 필요로 하는 모든 스크립트나 파일을 포함할 수 있습니다. 이것이 점진적 공개의 두 번째 계층입니다. 단순히 어떤 스킬을 로드할지 결정하는 것을 넘어, 해당 작업에 필요한 스킬의 어느 부분을 읽을 가치가 있는지를 결정합니다.

왜 중요한가: 화면 위의 큰 화살표(big-arrow-on-the-screen)가 해결하는 문제

실제 컴퓨터에서 작업을 자동화하는 에이전트는 조만간 인간만이 수행하거나 승인해야 하는 단계에 부딪힙니다. 시스템 권한 대화, 2단계 인증, CAPTCHA, 서명 등이 그것입니다. 에이전트는 올바른 버튼을 찾지만, 누를 수도 없고 눌러서는 안 됩니다.

프로젝트의 README에는 이러한 실제 사례들이 나열되어 있습니다: 사용자가 터미널을 보고 있는지 여부를 알지 못한 채 '허용'을 클릭하도록 요청하는 비서; Keynote에서의 3단계 가이드; Chrome에서 열린 14개 탭 중 올바른 탭 선택; 화상 통화로 친척에게 PDF를 저장하도록 도움. 모든 경우에 해결책은 에이전트가 사용자를 대신하여 행동하게 하는 것이 아닙니다. 정확히 어디서 행동해야 하는지 사용자에게 알려주는 것입니다.

설계상 이 **에이전트 확장(extension)**은 클릭하거나 타이핑하거나 화면을 캡처하지 않습니다. 오직 그릴(draw) 뿐입니다. 모든 것에 겹쳐지는 투명한 창이며, 마우스 클릭을 무시하고 키보드 포커스를 온전히 유지합니다. 저장소에 따르면, 이 화살표를 그리는 데 macOS의 특별한 권한이 필요하지 않으며, 전체 바이너리는 백그라운드 데몬이나 메뉴 막대 아이콘, 계정 또는 원격 측정 기능이 없는 단일 Swift 실행 파일입니다.

macOS는 클릭을 무시하는 투명 창을 시스템의 Quartz API를 통해 허용합니다.

Skill 작동 방식 내부: SKILL.md의 해부학적 구조

모든 스킬은 세 개의 대시로 구분된 YAML 블록으로 시작하며, 최소한 name과 description이라는 두 가지 필수 필드를 가집니다. 두 번째 구분자 다음에는 Markdown 형식의 본문이 오며, 이는 모델이 마치 자신의 프롬프트 일부인 것처럼 따르는 자연어 지침입니다. 하지만 이 지침은 해당 스킬을 적용해야 한다고 결정했을 때만 작동합니다.

가장 간단한 스킬은 두 개의 파일을 가집니다. 첫 번째는 SKILL.md입니다:

---
name: hola-mundo
description: "사용자에게 인사하고 시스템 시간을 말한다. 인사를 요청하거나, 시간 또는 스킬이 작동하는지 테스트할 때 사용." 
...

그리고 같은 폴더에 있는 이 파일이 호출하는 스크립트인 saludar.sh입니다:

#!/usr/bin/env bash
echo "Hola desde tu primera skill. Hora del sistema: $(date '+%H:%M:%S')"

Claude Code에게 이 스킬이 설치된 상태에서

결정은 오직 description 필드를 기반으로 합니다. 모델은 사용자 요청을 설치된 각 스킬의 짧은 문구와 비교하고, 그 후에야 하나를 선택하여 전체 SKILL.md 파일과 필요한 스크립트를 열어줍니다.

sequenceDiagram
participant U as Usuario
participant A as Agente
...

실제 예시: big-arrow 단계별 사용법

big-arrow-on-the-screen 설치는 macOS 전용이며, Homebrew를 통해 진행합니다:

brew install franzenzenhofer/tap/bigarrow
bigarrow install-skill

두 번째 명령어는 SKILL.md 파일과 CLI 사용 지침을 Claude Code의 스킬 폴더와 Codex가 설치된 경우에 복사하며, 이는 저장소(repository) 설명에 따릅니다. 이를 통해 에이전트에게 버튼을 가리키라고 요청할 때 더 이상 명령어를 수동으로 작성할 필요가 없습니다. 에이전트가 스킬 지침을 기반으로 스스로 구성합니다.

README에서 가져온 예시는 한 번 구성된 명령어의 모습입니다:

bigarrow point --element "Allow" --app "System Settings" \
--text "Franz, click Allow: Ghostty may control your Mac"

이 명령어는 System Settings 내의

12 54 notas.txt

두 줄, 오십사 단어. 동일한 구조, 이름, 설명 및 명령어 하나로 거의 모든 CLI(Command Line Interface)에 적용할 수 있습니다. 내부 linter, 자체 도구 또는 특정 플래그를 가진 bigarrow 바이너리 등 어떤 것이든 가능합니다.

시작하기: 자신만의 스킬 설치 및 테스트

필요한 유일한 전제 조건은 Claude Code가 로컬 환경에 설치되어 있고 인증된 상태여야 한다는 것입니다. 셸(shell) 기반의 스킬에는 추가적인 SDK나 툴체인(toolchain)이 필요하지 않습니다. macOS와 Linux에서 명령어는 동일합니다:

mkdir -p ~/.claude/skills/hola-mundo
cd ~/.claude/skills/hola-mundo
cat > SKILL.md  saludar.sh  **💡 팁:** 설명을 마치 내부 검색 엔진의 항목처럼 작성하세요. 실제 사용자가 입력할 수 있는 동의어(