Claude Code 와 Skills — 재사용 가능한 명령 묶음

Claude Code 는 Anthropic 이 2025 년 2 월에 공개한 터미널 기반 코딩 보조 CLI 입니다 (연구 프리뷰 시점). 이후 일반 가용성으로 옮겨가며 IDE 통합 · GitHub Actions · Skills 같은 기능이 추가됐습니다.

1. Claude Code 에 대한 이야기

Anthropic 의 공식 코딩 보조 CLI. 기본 모양은 터미널에서 claude 를 실행해 대화·작업을 진행하는 흐름입니다. 같은 모델 (Claude) 위에서 동작하지만 ChatGPT 같은 챗봇과는 자리가 다릅니다 — 파일 편집·테스트 실행·git 명령 같은 도구를 사용자 권한으로 직접 사용.

특징적인 자리:

• 터미널 우선의 인터페이스 (이후 IDE 확장 · GitHub Actions 결합 추가).
• 사용자 승인 게이트 (권한 모델).
• MCP 클라이언트로 동작 — 외부 도구를 등록 가능.
• 프로젝트 단위 CLAUDE.md 컨벤션.

2. Skills 에 대한 이야기

Anthropic 이 2025 년 10 월 16 일 일반 가용성으로 공개한 기능. 모델·도구·스크립트·프롬프트를 묶어 한 단위 (Skill) 로 만들고 필요할 때 모델이 골라 쓰게 만드는 구조.

자리잡는 흐름:

• 명령 (슬래시 명령) 으로 호출 가능.
• frontmatter 메타데이터로 이름·설명·필요 도구 선언.
• 스킬 디렉터리 안에 보조 스크립트·자료 함께.

3. 디렉터리 구조

위치	의미
~/.claude/skills/<name>/SKILL.md	사용자 전역 스킬.
<project>/.claude/skills/<name>/SKILL.md	프로젝트 스킬 (커밋 가능).

SKILL.md 의 시작에 frontmatter:

---
name: review-pr
description: 현재 PR 의 변경을 리뷰하고 핵심 위험을 정리한다.
---

# Review PR

## 단계
1. 변경 파일 목록 확보
2. ...

스킬 내부에 추가 파일 (보조 스크립트 · 템플릿) 을 둘 수 있고, 모델이 스킬 본문에서 그 파일을 참조합니다.

4. 호출 방식 · 메타데이터

호출 방식:

• Claude Code 안에서 /skill-name 같은 명령으로 호출.
• 모델이 사용자 의도를 보고 등록된 스킬 중 적절한 것을 자동 선택.

frontmatter 의 description 은 모델에게 스킬을 언제 써야 하는지 알려주는 핵심. 너무 짧거나 모호하면 모델이 스킬을 못 고릅니다. 예시·트리거 조건을 명확히 적는 모양이 권장.

스킬 안의 도구 호출은 Claude Code 의 권한 모델을 따릅니다. 자동 허용·승인 필요·차단을 settings 로 분리.

5. 비슷한 개념

Cursor Rules — .cursor/rules/ 디렉터리 또는 .cursorrules 파일에 자연어 규칙. Claude Code 의 CLAUDE.md 와 같은 자리.

Cursor "Custom Modes" (0.46~) — 시스템 프롬프트 · 허용 도구 · 기본 모델을 묶어 한 단위.

Aider Conventions — CONVENTIONS.md 를 명시적으로 컨텍스트에 포함. 코드 스타일·아키텍처 결정을 길게 적어두는 자리.

Continue Custom Commands — 자주 쓰는 작업 (/test · /review) 을 명령으로 등록.

GitHub Copilot Custom Instructions — .github/copilot-instructions.md 또는 사용자 설정의 custom instructions. 공통 안내문을 모델에 항상 포함.

MCP Prompts — MCP 의 세 primitive 중 하나. 클라이언트 중립적 표준이라는 차이.

6. 잘 쓰이는 스킬 후보

• PR 리뷰 절차 (변경 요약 · 테스트 점검 · 보안 점검).
• 마이그레이션 절차 (라이브러리 · API 버전 업).
• 문서 생성 템플릿 (릴리스 노트 · 아키텍처 다이어그램 텍스트).
• 디버그 절차 (로그 수집 · 재현 · 요약).
• 테스트 작성 보조 (자기 프로젝트 테스트 스타일).

7. 짧고 명확한 스킬

스킬이 길어질수록 모델이 일부를 무시하는 경향이 있습니다. 핵심 단계를 짧게 유지하고 보조 자료를 별도 파일로 둔 뒤 본문에서 참조하는 모양이 안정적.

권한 최소화 — 스킬 안에서 시스템 명령·파일 쓰기·외부 호출을 다루면 권한 모델 설정과 함께 설계. 자동 실행 항목과 사용자 승인 항목 분리.

팀 공유 — 프로젝트 디렉터리 .claude/skills/ 에 두면 git 으로 팀 공유가 가능. 사용자 개인의 ~/.claude/skills/ 와 분리.

8. 자주 걸리는 자리

이름 충돌 — 사용자 전역 스킬과 프로젝트 스킬 이름이 같으면 어느 쪽이 우선인지 헷갈림.

frontmatter 누락 — name · description 이 없으면 모델이 못 고름.

스킬 안의 외부 호출 — 스킬이 외부 API · 비밀을 사용하면 자격증명 관리·로그 노출 주의.

너무 많은 스킬 — 모델 컨텍스트가 무거워집니다. 작업 도메인별로 정리.

버전 호환 — Claude Code 가 빠르게 변합니다. 옛 형식의 스킬이 동작하지 않을 수 있음.

CLAUDE.md 와 스킬의 중복 — 같은 규칙을 양쪽에 두면 표류 위험. 한 자리에 두고 다른 쪽은 짧게 참조.

자동 호출의 의도와 어긋남 — 모델이 의도와 다른 스킬을 자동 호출. description 명확화 또는 명시적 호출.

하고픈 말

Skills 는 재사용 가능한 작업 묶음의 표준화 시도입니다. CLAUDE.md (전역 규칙) + Skills (작업 단위 절차) + Subagents (역할별 페르소나) 의 세 자리를 분리해 두면 운영이 깔끔해집니다. 짧고 명확한 description + 작업 도메인별 정리 + 권한 최소화가 안정적인 운영의 출발점.

Next

• subagents
• hooks-settings

Claude Code 문서 · Agent Skills 발표 (2025-10) · Settings · Hooks · Cursor Rules · Copilot Custom Instructions · Aider CONVENTIONS · MCP Prompts 를 참고합니다.