반복 작업을 AI 코딩 에이전트를 위한 재사용 가능한 스킬로 바꾸는 방법

AI 코딩 에이전트에 같은 체크리스트를 계속 붙여넣고 있다면 — "컨벤셔널 커밋을 작성하고, 테스트를 실행한 다음, 체인지로그를 업데이트해" — 에이전트가 대신 기억해 줄 수 있는 일을 직접 하고 있는 셈이다. 대부분의 현대적 에이전트는 반복되는 절차를 작고 재사용 가능한 파일 하나로 묶을 수 있게 해준다. Claude Code에서는 이것을 스킬이라고 부르며, 같은 파일이 /deploy 같은 슬래시 명령어의 동력이 되기도 한다. 이 가이드는 스킬을 처음부터 만드는 과정을 짚어본 다음, 다른 도구에도 적용되는 원칙들을 설명한다.

스킬이란 무엇인가

스킬은 안에 SKILL.md 파일 하나가 들어 있는 폴더다. 그 파일은 두 부분으로 구성된다. 에이전트에게 스킬을 언제 사용할지 알려주는 YAML 프론트매터와, 스킬이 실행될 때 따를 지시가 담긴 마크다운 본문이다. 모든 것을 CLAUDE.md(또는 AGENTS.md) 파일에 욱여넣는 것에 비해 가지는 핵심 장점은 **점진적 공개(progressive disclosure)**다. 본문은 스킬이 실제로 호출될 때만 로드되므로, 긴 참조 자료를 두더라도 필요해지기 전까지는 비용이 거의 들지 않는다.

스킬을 호출하는 방법은 두 가지다. /skill-name을 입력해 직접 호출하거나, 자동으로 호출하는 방식이다 — 에이전트가 사용자의 요청을 읽고 그것을 스킬의 description과 대조한 뒤, 관련이 있으면 로드한다.

스킬은 어디에 두는가

폴더를 어디에 두느냐가 누가 그것을 사용할 수 있는지를 결정한다. Claude Code에서는 공식 문서에 따르면:

• ~/.claude/skills/<name>/SKILL.md — 개인용, 모든 프로젝트에서 사용 가능.
• .claude/skills/<name>/SKILL.md — 프로젝트용, 리포지토리에 커밋되어 팀 전원이 동일한 명령어를 사용.

폴더 이름이 곧 명령어가 된다. summarize-changes라는 폴더는 /summarize-changes를 제공한다.

구체적인 예시

커밋하기 전에 커밋되지 않은 변경 사항을 요약하고 위험한 부분을 표시해 주는 스킬을 만들어 보자. 디렉터리를 생성한다:

mkdir -p ~/.claude/skills/summarize-changes

그런 다음 이것을 ~/.claude/skills/summarize-changes/SKILL.md로 저장한다:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any
risks you notice such as missing error handling, hardcoded values, or tests
that need updating. If the diff is empty, say there are no uncommitted changes.

이것이 작동하게 만드는 요소는 두 가지다. 첫째, description은 여러분이 아니라 에이전트를 위해 작성되었다 — 트리거("무엇이 바뀌었는지", "커밋 메시지를 원함", "diff를 리뷰")를 명시함으로써 에이전트가 언제 이 스킬을 꺼내 들지 알게 한다. 둘째, !`git diff HEAD` 줄은 **동적 컨텍스트 주입(dynamic context injection)**이다. Claude Code가 그 명령어를 실행하고 출력 결과를 에이전트가 스킬을 읽기 전에 프롬프트에 붙여넣는다. 지시가 실제 diff가 이미 인라인된 상태로 도착하므로, 답변은 추측이 아니라 여러분의 실제 작업 트리에 근거하게 된다.

아무 파일이나 약간 수정한 다음 에이전트를 실행하고 두 가지 방식 모두 시도해 보라 — "내가 뭘 바꿨지?"라고 물어 자동으로 트리거하거나, /summarize-changes를 입력해 직접 실행해 보라.

인자 전달하기

스킬은 입력을 받을 수 있다. 본문의 $ARGUMENTS 자리표시자는 명령어 뒤에 입력하는 내용으로 치환되며, 인덱스 변형($0, $1)은 특정 단어를 가져온다. /fix-issue 4821로 호출된 스킬은 이슈 번호를 직접 참조할 수 있으므로, 티켓마다 파일을 하나씩 두는 대신 파일 하나가 모든 이슈를 처리한다.

오래 버티는 스킬을 위한 다섯 가지 원칙

이 원칙들은 Claude Code 스킬을 작성하든, Cursor 명령어를 작성하든, 또는 — OpenAI의 2026년 6월 Record & Replay 기능 기준 — 에이전트가 녹화해 준 자동화를 편집하든 모두 적용된다:

1. description은 모델을 위해 작성하라. 구체적인 트리거 문구를 앞쪽에 배치하라. 모호한 description은 에이전트가 스킬을 자동으로 로드하지 않는다는 뜻이고, 그러면 다시 /를 입력하고 이름을 기억해야 하는 처지로 돌아간다.
2. 각 스킬은 한 가지 일만 하게 하라. 배포도 하고 마이그레이션도 실행하고 Slack에도 게시하는 스킬은 신뢰하기 어렵고 디버깅하기는 더 어렵다. 작고 단일 목적의 스킬이 더 잘 조합된다.
3. 상태를 설명하는 대신 실시간 컨텍스트를 주입하라. 실제 diff, 테스트 결과, 파일 목록을 끌어오는 것이 에이전트에게 "현재 상태를 확인해"라고 말하는 것보다 낫다 — 에이전트가 잘못 추측할 수 있는 단계를 하나 없애주기 때문이다.
4. 부작용이 있는 것은 모두 통제하라. 배포하거나, 마이그레이션하거나, 삭제하는 스킬은 에이전트가 자동으로 발동하게 두지 말고 명시적인 호출을 요구하라. 되돌릴 수 없는 동작 전에는 사람이 개입하도록 하는 편이 좋다.
5. 팀 스킬은 리포지토리에 커밋하라. 프로젝트 스킬을 .claude/skills/에 두고 체크인하면 모든 개발자가 — 그리고 CI에서 실행되는 모든 에이전트가 — 동일한 절차를 따른다. 여러분의 관행이 한 사람의 머릿속에만 존재하기를 멈춘다.

언제 스킬을 꺼내 들어야 하는가

경험칙: 같은 여러 단계짜리 지시를 세 번째로 붙여넣는 순간, 또는 CLAUDE.md의 한 섹션이 *사실(fact)*에서 *절차(procedure)*로 바뀌는 순간, 그것을 스킬로 옮겨라. 재사용 가능한 명령어를 얻게 되고, 컨텍스트 파일은 군더더기 없이 유지되며, 지시는 실제로 필요할 때만 로드된다 — 그 덕분에 여러분과 에이전트 모두 눈앞의 작업에 집중하게 된다.