SONUB 에이전트 스킬 — 명령 한 줄로 설치

기초 — 스킬이 무엇이고 어떻게 설치하나

이 처음이라면 여기서 시작하세요. 스킬이 무엇이고 어떻게 동작하는지 알아본 뒤, 명령 한 줄로 설치해 써 봅니다. 다 해 봤다면 위의 [중급] 탭에서 나만의 스킬을 만듭니다.

에이전트 스킬 알아보기

은 SKILL.md 파일이 든 폴더로, 에이전트에게 한 종류의 일을 하는 방법을 가르쳐요. 단계, 규칙, 확인 방법이 들어 있고, 원하면 스크립트와 참고 파일도 넣을 수 있어요. Claude Code, Codex 같은 에이전트는 공개된 Agent Skills 형식을 지원해요.

SKILL.md 맨 위에는 이름과 설명이 있어요. 에이전트는 처음에 이것만 읽고, 요청이 설명과 맞을 때 전체 지시를 불러와요. 그래서 스킬이 많아도 대화가 가득 차지 않아요.

쉽게 이해하기

이렇게 생각해 보세요: 스킬은 선반에 꽂힌 업무 설명서 바인더와 같아요. 에이전트는 먼저 모든 바인더의 표지 — 이름과 한 줄 설명 — 만 읽어요. 요청이 표지와 맞으면 그 바인더를 꺼내 안의 단계를 따라요. 그래서 스킬이 많아도 대화가 가득 차지 않아요.
예시: “roll-dice” 스킬: SKILL.md가 든 폴더이고, 표지에는 “사용자가 무작위 숫자를 원하면 주사위를 굴린다”, 안에는 단계와 작은 스크립트가 있어요. “주사위 두 개 굴려 줘”라고 하면 에이전트가 그 바인더를 펼쳐요.
자주 하는 실수: “쓸모 있는 도우미”처럼 막연한 설명. 에이전트는 표지만 보고 고르니, 언제 써야 하는 스킬인지 정확히 적어요.

알록달록한 바인더가 꽂힌 선반. 하나가 펼쳐져 아이콘과 몇 줄이 있는 표지, 점으로 된 단계, 점검표, 끼워 둔 작은 공구 상자가 보인다. 로봇이 표지들을 읽고 말풍선 속 주사위 아이콘과 맞는 바인더를 꺼낸다. — 에이전트는 표지(이름과 설명)만 읽고, 요청과 맞는 바인더 하나만 펼쳐요.

에이전트 스킬이란?

에이전트 스킬(Agent Skills)은 AI 에이전트에게 새 능력과 전문 지식을 더해 주는 가볍고 열린 형식이에요. 스킬 하나는 SKILL.md 파일이 든 폴더 하나예요. SKILL.md 에는 이름(name)과 설명(description), 그리고 한 종류의 일을 어떻게 하는지 알려 주는 지시가 들어 있어요. 폴더에는 스크립트, 참고 문서, 템플릿 같은 파일도 함께 넣을 수 있어요.

에이전트는 점점 똑똑해지지만, 실제 일을 믿고 맡기려면 우리 회사·우리 팀·나만의 일하는 방법을 알아야 해요. 스킬은 그 방법을 폴더 하나에 담아, 에이전트가 필요할 때만 불러 쓰게 해요. 전문 지식은 다시 쓸 수 있는 지시가 되고, 여러 단계의 일은 매번 같은 절차가 돼요.

이 형식은 Anthropic 이 처음 만들어 열린 표준으로 공개했어요. 지금은 누구나 참여해 함께 키워 가요(agentskills.io).

어디에 좋은가 — 절차· 리뷰 기준·문서 양식처럼 팀이 되풀이하는 일에 좋습니다. 사람이 바뀌어도 일하는 방식이 남습니다.

한 번 배우면 여러 AI 도구에서

에이전트 스킬은 한 회사의 기능이 아니라 공개 표준이에요. 그래서 스킬 만드는 법을 한 번 배우면 어디서나 써요. 같은 SKILL.md 폴더가 Claude Code 와 Codex 는 물론, 이 형식을 지원하는 많은 AI 도구에서 그대로 작동해요.

설치도 어디서나 같아요. 도구가 스킬을 찾는 폴더에 스킬 폴더를 넣으면 끝이에요. 도구마다 그 폴더 위치만 조금 달라요(아래 상자).

Claude Code
Claude
ChatGPT & Codex
Gemini CLI
GitHub Copilot
VS Code
Cursor
OpenCode
Goose
Kiro
Junie
Roo Code
Amp
OpenHands
Factory
Laravel Boost

agentskills.io 에 소개된 도구 중 일부예요(2026-10-16 확인). 목록은 계속 늘어나요.

# where each tool looks for skills      all projects        this project
Claude Code                             ~/.claude/skills    .claude/skills
Codex · Gemini CLI · Copilot CLI        ~/.agents/skills    .agents/skills
VS Code (GitHub Copilot)                                    .agents/skills
# put the whole skill folder there:  .agents/skills/roll-dice/SKILL.md

어떻게 동작할까요 — 필요한 만큼만 읽는 세 단계

에이전트는 스킬을 점진적 공개(progressive disclosure) 방식으로 읽어요. 처음에는 조금만, 일이 필요로 할 때 더 읽어요.

찾기(Discovery): 시작할 때 모든 스킬의 이름과 설명만 읽어요. 스킬 하나에 100토큰 정도라 많이 설치해도 가벼워요.
켜기(Activation): 요청이 어떤 스킬의 설명과 맞으면 그 스킬의 SKILL.md 본문 전체를 읽어요. 본문은 5,000토큰, 500줄 아래로 쓰기를 권해요.
실행(Execution): 지시를 따라 일하고, 필요할 때만 scripts/ 의 코드를 실행하거나 references/ 의 문서를 읽어요.

폴더 구조와 SKILL.md 규칙

스킬에 꼭 있어야 하는 파일은 SKILL.md 하나예요. 맨 위에 --- 두 줄 사이의 YAML 머리말이 있고, 그 아래에 Markdown 으로 지시를 써요.

name (필수): 64자 이하, 영어 소문자·숫자·하이픈(-)만 써요. 하이픈으로 시작하거나 끝나면 안 되고 하이픈 두 개를 잇달아 쓸 수 없어요. 폴더 이름과 같아야 해요.
description (필수): 1,024자 이하. 무엇을 하는지와 언제 쓰는지를 사람들이 실제로 하는 말로 써요. 에이전트는 이 글을 보고 스킬을 쓸지 정해요.
license · compatibility · metadata · allowed-tools (선택): 라이선스, 필요한 환경(500자 이하), 작성자·버전 같은 추가 정보, 미리 허락한 도구(실험 기능)예요. 대부분의 스킬에는 필요 없어요.
scripts/ · references/ · assets/ (선택): 실행할 코드, 필요할 때 읽는 문서, 템플릿·이미지·데이터 같은 자료예요. 파일은 스킬 폴더 기준 상대 경로로 가리키고, SKILL.md 에서 한 단계 깊이까지만 연결해요.

my-skill/            # folder name = the skill's name
├── SKILL.md         # required: name + description + instructions
├── scripts/         # optional: code the agent can run
├── references/      # optional: documents read only when needed
└── assets/          # optional: templates, images, data

만들어 보기 — 파일 하나로 5분

가장 간단한 스킬은 SKILL.md 파일 하나예요. agentskills.io 첫걸음(Quickstart)의 주사위 굴리기 스킬을 만들어 봐요.

폴더 만들기: 프로젝트에 .agents/skills/roll-dice/ 폴더를 만들어요(Claude Code 는 .claude/skills/roll-dice/). 폴더 이름이 곧 스킬 이름이에요.
SKILL.md 쓰기: 아래 상자처럼 name 과 description 을 쓰고, 본문에 할 일을 몇 줄로 적어요.
확인하기: 에이전트를 다시 열고 /skills 를 입력해 목록에 roll-dice 가 보이는지 봐요.
시험하기: "d20 굴려 줘"라고 부탁해 스킬이 켜지는지 보고, 관계없는 질문에는 켜지지 않는지도 봐요. 잘 켜지지 않으면 description 을 고쳐요.

---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---

To roll a die, use the following command that generates a random number from 1
to the given number of sides:

```bash
echo $((RANDOM % <sides> + 1))
```

Replace `<sides>` with the number of sides on the die (e.g., 6 for a standard
die, 20 for a d20).

잘 만드는 요령

description 이 가장 중요해요. 무엇을 하는지, 언제 쓰는지, 무엇에는 쓰지 않는지 적어요. "PDF 를 도와줌"처럼 막연하면 거의 쓰이지 않아요.
스킬 하나에는 한 종류의 일만 담아요. 본문은 짧은 단계, 입력과 출력의 예, 흔한 예외로 채워요.
긴 설명은 references/ 로, 반복되는 명령이나 계산은 scripts/ 로 옮겨요. 스크립트는 무엇이 필요한지 밝히고 알아보기 쉬운 오류 메시지를 내게 해요.
skills-ref validate ./my-skill 로 머리말 규칙을 검사하고, git 으로 버전을 관리해 팀과 나눠요.
남이 만든 스킬은 스크립트를 실행할 수 있으니 설치하기 전에 꼭 읽어 보세요.
쓰기 전에 — 남이 만든 스킬은 지시와 스크립트를 먼저 읽고, 되돌릴 수 있는 작은 일로 시험하세요. Agent Skills 사이트는 형식만 정할 뿐, 스킬이 안전한지는 보증하지 않습니다.

조금 더 알아보기

스킬이 언제 쓰일지는 설명이 정하니, 사람들이 실제로 하는 말로 쓰고 무엇에는 쓰지 않는지도 밝히세요. 지시는 짧고 구체적으로 쓰고, 긴 세부 내용은 따로 참고 파일로 옮기고, 써야 하는 요청과 쓰지 말아야 하는 요청으로 스킬을 시험하세요. 스킬은 스크립트를 실행할 수 있으니 믿을 수 있는 곳의 스킬만 설치하고, 먼저 읽어 보세요. SONUB 도 여러 스킬로 만들어졌어요. 그중 하나는 이 사이트에서 보는 용어의 초보자용 팝업을 써요.

명령 한 줄로 설치

프로젝트 폴더의 터미널에서 실행하세요. sonub.com 에서 스킬 목록을 읽고, 어떤 스킬을 어느 에이전트에 넣을지 물은 뒤, 에이전트마다 스킬을 찾는 폴더에 복사합니다.

npx skills add https://sonub.com

Node.js 18 이상이 필요합니다(npx 가 함께 들어 있습니다). 설치한 뒤 에이전트의 새 세션을 시작해야 새 스킬을 읽습니다.

명령을 몰라도 — 인공지능에게 설치해 달라고 말하기

스킬을 설치할 때는 인공지능에게 원하는 스킬을 설치해 달라고 말하면 됩니다. 인공지능이 똑똑해서 “https://sonub.com 에 있는 gp 스킬을 설치해 줘”처럼 어디에 있는 스킬인지 알려 주면 설치를 해 줍니다. 스킬 설치 명령어를 몰라도 인공지능이 설치하고 사용합니다. 아래 문장을 복사해 에이전트에게 보내 보세요.

SONUB 스킬을 설치해 줘: npx skills add https://sonub.com -y 를 실행하고, 어떤 스킬이 설치됐는지와 쓰기 시작하려면 뭐라고 말하면 되는지 알려 줘.

다만, 정말 아무것도 모른 채로 인공지능에게 시키기만 하면 결국은 인공지능이 일을 한 것이지 여러분이 일을 한 것이 아닌 것이 됩니다.

그래서 인공지능에 대해서 먼저 알고 있어야 인공지능에게 더 잘 일을 시킬 수가 있고, 인공지능이 일을 잘못했을 때 무엇이 잘못되었는지 인공지능이 한 작업을 분석해서 다시 요청을 할 수 있는 것입니다.

자주 쓰는 옵션

이 컴퓨터의 모든 프로젝트에(없으면 지금 프로젝트에만): npx skills add https://sonub.com -g
스킬 하나만: npx skills add https://sonub.com -s gp
에이전트 하나에만: npx skills add https://sonub.com -a claude-code
스킬 목록만 보고 설치하지 않기: npx skills add https://sonub.com -l
묻지 않고 — 모든 스킬을 이 컴퓨터에서 찾은 에이전트에: npx skills add https://sonub.com -y

업데이트와 삭제

여기서 설치한 모든 스킬을 최신으로: npx skills update
스킬 지우기: npx skills remove gp

스킬

스킬은 에이전트가 읽는 지침 SKILL.md 와 작은 도구가 든 표준 폴더입니다. 가입할 것이 없고 MIT 라이선스입니다.

gp

나의 모든 일감을 GitHub Project 보드에서

평소 말로 부탁하면 에이전트가 gh CLI 로 GitHub Project 보드를 관리하고, 결과를 다시 읽어 확인합니다.

이렇게 말해 보세요

“내 일 보여 줘”
“12번을 Review 로 옮겨”
“TODO 에 ‘문서 고치기’ 추가해”
“맨 앞에 Urgent 칸 만들어”

따라 해 보기: gp 스킬로 일감 관리하기

gp 는 SONUB 가 만든 로, 나의 모든 일감을 Project 보드에서 관리해요. 이런 일을 평소 말로 부탁하면 가 GitHub (gh)로 처리하고, 결과를 다시 읽어 확인해요.

이슈 만들기·고치기·닫기, 이미지 첨부
TODO 체크리스트
칸반 칸 만들기·이름 바꾸기
담당자 지정

스킬 폴더에는 위에서 본 부분이 그대로 들어 있어요. SKILL.md, 실제 일을 하는 스크립트(scripts/gp.py), 필요할 때만 읽는 참고 파일이에요.

준비: github.com/signup 에서 무료 GitHub 계정을 만들고 gh 를 설치하세요. 로그인은 에이전트가 gh auth login 으로 도와줘요.
설치: 아래 한 줄을 터미널에 입력하세요(Node.js 가 필요해요). 내 컴퓨터의 에이전트 — Claude Code·Codex·Gemini CLI 등 — 에 gp 가 설치돼요.
처음 한 번: "gp 설정해 줘"라고 말하세요. 에이전트가 gp 의 doctor 명령으로 점검하고, 내 보드 하나를 고르거나 새로 만들어요.
평소 말로 부탁하세요: "이슈 만들어: 로그인 버튼이 안 눌려, 이 스크린샷 첨부해", "Done 으로 옮겨", "Review 칸 만들어", "내 일 보여 줘".

# 1) install the gp skill — Claude Code, Codex, Gemini CLI, Copilot CLI ...
npx skills add https://sonub.com -s gp -g
#   -g: for every project (leave it out for this project only)

# 2) once: log in to GitHub with the board permissions
gh auth login
gh auth refresh -s project,repo

# 3) then just ask the agent:
# "Set up gp and show my GitHub projects."
# "Make an issue: the login button does nothing. Attach shot.png. TODO: reproduce, fix, test."
# "Move it to In Progress."   "Add a Review column."   "Done!"   "What's on my plate?"

무료 GitHub 계정, gh CLI, Python 3.8 이상이 필요합니다.

이 스킬만 설치

npx skills add https://sonub.com -s gp

SKILL.md 읽기

claude-skill

Claude Code 를 배우고 더 잘 쓰기

Claude Code 는 거의 날마다 새 버전이 나옵니다. 이 스킬은 순서대로 가르치고, 지금의 공식 문서로 답하고, 내 설정을 점검하고, 새 기능을 모두 요약합니다.

내 프로젝트에서 하는 실습과 확인 질문이 있는 14개 레슨
퀴즈와 저장되는 진도
공식 문서로 확인한 답과 그 링크
CHANGELOG 의 모든 새 기능을 주제별로 요약
설정·CLAUDE.md·스킬·플러그인·MCP 를 보는 설정 점검(doctor)
/claude-skill update 가 새로 나온 기능을 스킬에 더합니다

이렇게 말해 보세요

“다음 레슨”
“파일을 고칠 때마다 prettier 를 돌리는 훅은 어떻게 만들어?”
“내 설정 점검해 줘”
“퀴즈 내 줘”

Python 3.8 이상과 인터넷 연결이 필요합니다(공식 문서를 읽습니다).

이 스킬만 설치

npx skills add https://sonub.com -s claude-skill

SKILL.md 읽기

자주 묻는 질문

에이전트 스킬이 뭔가요?

AI 에이전트에게 어떤 일을 언제·어떻게 할지 알려 주는 SKILL.md 파일과, 그 일에 필요한 스크립트·메모가 든 폴더입니다. 열린 표준(agentskills.io)이라 같은 폴더를 여러 에이전트에서 씁니다.

모든 프로젝트에, 아니면 이 프로젝트에만?

-g 가 없으면 지금 있는 프로젝트 안(예: .claude/skills/·.agents/skills/)에 설치되고, 커밋하면 팀도 같이 씁니다. -g 를 붙이면 홈 폴더에 한 번 설치해 모든 프로젝트에서 씁니다.

어떤 에이전트에서 되나요?

Claude Code·Codex·Gemini CLI·GitHub Copilot CLI·Cursor 와 skills 도구가 아는 다른 에이전트에서 됩니다. 어느 에이전트에 넣을지 묻고, -a 로 하나를 지정할 수도 있습니다.

무료인가요? 내 데이터는 어디로 가나요?

무료이고 MIT 라이선스입니다. 스킬은 내 컴퓨터에서 내 도구로 돌아갑니다 — gp 는 내 gh 로그인으로 GitHub 와만 이야기하고, claude-skill 은 공개된 Claude Code 문서를 읽고, popup 은 내 파일에서 일합니다. sonub.com 은 스킬 파일을 내줄 뿐입니다.

설치했는데 보이지 않아요.

에이전트의 새 세션을 시작하세요 — 시작할 때 스킬 폴더를 읽습니다. Claude Code 에서는 /gp 처럼 빗금과 스킬 이름을 입력해도 됩니다.

수업으로 배우기 — AI 과정 Agent Skills 챕터

중급 — 나만의 스킬 만들기

자꾸 되풀이하는 부탁을 로 만듭니다. 폴더를 만들고, 가 찾을 수 있는 설명을 쓰고, 짧은 단계별 지시를 쓴 뒤, 불러서 확인하고, 나만 쓸지 팀이 함께 쓸지 둘 곳을 정합니다.

첫 스킬 — 되풀이하는 부탁을 스킬로

첫 스킬로 좋은 것은 에게 벌써 세 번 넘게 설명한 일입니다. 메시지 쓰는 법, 우리 팀의 테스트 순서, 보고서 모양 같은 것입니다. 그 설명을 SKILL.md 에 한 번 적어 두면 에이전트가 매번 찾아서 따릅니다.

자꾸 설명하는 일 하나를 골라 소문자·숫자·하이픈으로 짧은 이름을 짓습니다(commit-message).
에이전트의 스킬 폴더에 그 이름으로 폴더를 만듭니다. npx skills init <name> 이 폴더와 SKILL.md 틀을 만들어 줍니다.
맨 위에 name(폴더 이름과 같게)과 description 을 채우고, 그 아래에 단계를 씁니다.
새 세션을 열고 그 일을 평소 말로 부탁합니다. 에이전트가 스킬을 쓰면 성공입니다.

Terminal

# in your project folder
mkdir -p .agents/skills && cd .agents/skills
npx skills init commit-message      # makes commit-message/SKILL.md

# Codex · Gemini CLI · Copilot CLI read   .agents/skills/commit-message/SKILL.md
# Claude Code reads                       .claude/skills/commit-message/SKILL.md

에이전트에게 "방금 한 일을 스킬로 만들어 줘"라고 부탁해도 됩니다. Claude Code 와 Codex 는 형식을 알고 있습니다(Codex 에는 $skill-creator 가 들어 있습니다).

description — 에이전트가 가진 단 하나의 단서

처음에 에이전트는 모든 스킬의 이름과 설명(description)만 읽습니다. 그 몇 줄로 지금 부탁에 맞는 스킬을 고릅니다. 설명이 흐릿하면 스킬이 아예 쓰이지 않거나 엉뚱한 때 쓰입니다.

무엇을 하는지와 언제 쓰는지를 둘 다, 한두 문장으로 씁니다.
"I can help you …"가 아니라 3인칭("Writes commit messages …")으로 씁니다.
사람들이 실제로 치는 낱말을 넣습니다: "commit message", "commit this", "staged changes".
규칙: description 은 1,024자 이하, name 은 소문자·숫자·하이픈 64자 이하이고 폴더 이름과 같습니다.

SKILL.md

# ✗ too vague — the agent cannot tell when to use it
description: Helps with commits.

# ✓ what it does + when to use it + the words people really say
description: Writes a git commit message from the staged changes in the Conventional Commits style. Use when the user asks for a commit message, says "commit this", or wants to describe staged changes.

Claude Code 는 스킬 목록에서 설명을 1,536자까지만 보여 주므로 가장 중요한 쓰임을 맨 앞에 둡니다.

본문 지시 — 짧게, 차례대로, 예시와 함께

frontmatter 아래가 에이전트가 스킬을 쓸 때 읽는 지시입니다. 에이전트는 이미 똑똑하므로 모르는 것만 씁니다: 우리 규칙, 우리 순서, 우리 모양.

에이전트가 이미 아는 것(git 이 무엇인지, Markdown 쓰는 법)은 빼세요.
순서가 중요하면 번호를 붙이고, 일이 틀어졌을 때 할 일도 적습니다("스테이징된 것이 없으면 그렇다고 말하고 멈춘다").
바라는 결과를 예시 한두 개로 보여 줍니다 — 예시가 설명보다 더 잘 전해집니다.
선택지를 늘어놓지 말고 기본값 하나를 줍니다("pdfplumber 를 쓴다. 스캔한 PDF 만 OCR").
SKILL.md 는 500줄 아래로 둡니다. 길어지면 파일로 나눕니다([고급] 탭).

.agents/skills/commit-message/SKILL.md

---
name: commit-message
description: Writes a git commit message from the staged changes in the Conventional Commits style. Use when the user asks for a commit message or says "commit this".
---

1. Run `git diff --staged`. If nothing is staged, say so and stop.
2. Pick one type: feat, fix, docs, refactor, test or chore.
3. Write a subject of 50 characters or less, then a blank line,
   then why the change was made in one or two short lines.

Example:
fix(cart): keep the coupon after a page reload

The coupon code was stored only in memory.

스킬 부르기와 확인

스킬은 두 가지로 쓰입니다. 부탁이 설명과 맞으면 에이전트가 스스로 고르거나, 내가 이름으로 부릅니다.

자동: 평소 말로 부탁합니다("커밋 메시지 써 줘"). 에이전트가 설명을 읽고 스킬을 불러옵니다.
Claude Code: /skills 로 목록을 보고 /<skill-name> 으로 부릅니다. 이름 뒤의 말은 $ARGUMENTS 에 들어갑니다.
Codex: /skills 로 목록을 보고, 메시지에 $<skill-name> 을 쓰면 부릅니다.
Claude Code 는 SKILL.md 를 고치면 바로 반영합니다. 스킬 폴더를 새로 만들었다면 /reload-skills 를, 다른 도구에서는 새 세션을 엽니다.

Claude Code · Codex

# Claude Code
/skills                 # list the skills it found
/commit-message         # call one yourself
/fix-issue 123          # "123" goes into $ARGUMENTS in SKILL.md

# Codex
/skills                 # list and pick
$commit-message         # mention one in your message

써야 할 때 스킬이 쓰이지 않으면 description 부터 고치세요 — 대부분 그것이 원인입니다.

같은 스킬을 홈 폴더(내 모든 프로젝트)에 둘 수도, 프로젝트(그 프로젝트에서 일하는 모두)에 둘 수도 있습니다.

개인 스킬: Claude Code 는 ~/.claude/skills/, Codex·Gemini CLI·Copilot CLI 는 ~/.agents/skills/.
프로젝트 스킬: 프로젝트의 .claude/skills/ 나 .agents/skills/. 커밋하면 팀 모두가 같은 스킬을 씁니다.
이름이 같은 스킬이 둘이면 Claude Code 는 개인 스킬을 프로젝트 스킬보다 앞에 씁니다.
스킬에 비밀번호나 API 키를 넣지 마세요 — 스킬 파일은 읽히고 자주 공유됩니다.

Where

# only me, every project
~/.claude/skills/commit-message/      # Claude Code
~/.agents/skills/commit-message/      # Codex · Gemini CLI · Copilot CLI

# this project — commit it and the whole team gets it
.claude/skills/commit-message/
.agents/skills/commit-message/

git add .agents/skills/commit-message
git commit -m "Add the commit-message skill"

중급 연습 — 내 프로젝트에서 하나 만들기

AI 에게 세 번 넘게 한 부탁 하나를 적습니다.
npx skills init 으로 그 스킬 폴더를 만들고 name 과 description 을 씁니다.
단계를 다섯 줄 이하로 쓰고 결과 예시를 하나 넣습니다.
새 세션에서 평소 말로 부탁해 스킬이 쓰이는지 보고, 이름으로도 불러 봅니다.
상관없는 일을 부탁해 스킬이 쓰이지 않는지도 확인합니다.

다섯 가지가 모두 되면 [고급] 탭으로 넘어가세요.

공식 문서

2026-10-18 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.

고급 — 큰 스킬: 파일 나누기·스크립트·옵션·시험·안전

SKILL.md 하나로 모자랄 때: 필요할 때만 읽는 파일로 나누고, 정해진 일은 스크립트에 맡기고, frontmatter 옵션을 쓰고, 믿기 전에 시험하고, 남이 만든 은 설치 전에 살펴봅니다.

파일로 나누기 — 필요한 것만 읽게

는 스킬을 세 단계로 읽습니다. 처음에는 이름과 설명, 스킬을 쓸 때 SKILL.md, 다른 파일은 필요할 때만. 그래서 큰 자료는 따로 파일로 두고, SKILL.md 는 어떤 질문에 어느 파일을 읽을지 알려 주는 지도가 됩니다.

SKILL.md 에는 전체 모습과 "이럴 때는 저 파일을 읽어라"를 둡니다.
파일 링크는 SKILL.md 에서 한 단계만 겁니다. 파일 → 파일 → 파일로 이어지면 일부만 읽히기 쉽습니다.
100줄이 넘는 참고 파일은 맨 위에 목차를 둡니다.
파일 이름은 내용이 보이게(doc2.md 말고 finance.md), 경로는 언제나 / 로 씁니다.

sql-report/

sql-report/
├── SKILL.md              ← the map: what to read for which question
├── references/
│   ├── finance.md        ← read only for revenue questions
│   └── sales.md          ← read only for sales questions
└── scripts/
    └── check_query.py    ← run it, do not read it

SKILL.md

## Which file to read
- Revenue, billing → read [references/finance.md](references/finance.md)
- Deals, pipeline → read [references/sales.md](references/sales.md)

스크립트 — 매번 똑같아야 하는 일은 코드로

미리 만든 스크립트는 에이전트가 그때그때 쓰는 보다 믿을 만하고, 실행하면 코드가 아니라 출력만 컨텍스트에 들어갑니다. 검사·변환처럼 정확해야 하는 일은 scripts/ 에 둡니다.

실행하라는 것인지("Run scripts/check_query.py") 읽으라는 것인지("규칙은 scripts/check_query.py 를 보라") 분명히 씁니다.
오류는 스크립트 안에서 처리하고, 무엇이 잘못됐고 어떻게 하면 되는지 알려 주는 메시지를 냅니다.
필요한 패키지와 버전을 적고, 꼭 필요한 것은 compatibility 에도 적습니다.
검사 → 고치기 → 다시 검사의 고리를 만들고, 검사를 통과한 뒤에만 다음으로 갑니다.
정해 둔 값에는 이유를 주석으로 답니다(타임아웃이 왜 30초인가?).

SKILL.md

## Check the query before you run it

Run:
    python3 scripts/check_query.py query.sql

It prints OK, or one problem per line.
If it is not OK, fix the query and run the check again.
Run the query only after you see OK.

어떤 언어를 실행할 수 있는지는 에이전트마다 다릅니다. 흔히 Python·Bash·JavaScript 를 씁니다.

frontmatter 옵션 — 표준과 도구마다의 덤

name·description 말고도 표준에는 몇 가지 선택 필드가 있고, 도구마다 자기 필드를 더합니다. 도구는 모르는 필드를 무시하므로 먼저 표준 필드만으로 동작하게 만드세요.

표준: license, compatibility(필요한 프로그램·네트워크, 500자 이하), metadata(만든 사람 등), allowed-tools(미리 허락한 도구 — 실험 단계).
Claude Code disable-model-invocation: true — 나만 부를 수 있습니다. 배포·메시지 보내기처럼 뒤탈이 있는 일에 씁니다.
Claude Code user-invocable: false — AI 만 쓰고 / 메뉴에는 숨깁니다. context: fork 는 스킬을 서브 에이전트에서 따로 실행합니다.
Claude Code !`command` — 스킬을 읽기 전에 명령을 실행해 그 출력으로 바꿔 넣습니다(예: !`git diff HEAD`).
Codex: agents/openai.yaml 의 policy → allow_implicit_invocation: false — $<skill-name> 으로 부를 때만 쓰입니다.

.claude/skills/deploy/SKILL.md

---
name: deploy
description: Deploys the app to staging or production. Use when the user says deploy, release or ship.
license: MIT
compatibility: Requires git, docker and network access
metadata:
  author: my-team
allowed-tools: Bash(git status) Bash(./scripts/deploy.sh *)
# Claude Code only — other tools ignore these
disable-model-invocation: true
argument-hint: "[staging|production]"
---

Current branch: !`git branch --show-current`

Deploy to $ARGUMENTS with `./scripts/deploy.sh $ARGUMENTS`.

allowed-tools 에는 스킬에 꼭 필요한 명령만 넣으세요. 권한이 넓을수록 실수의 대가가 커집니다.

시험 — 많이 쓰기 전에 시험부터

스킬이 잘 되는지는 해 봐야 압니다. 먼저 스킬 없이 에이전트가 무엇을 틀리는지 보고, 그것을 고칠 만큼만 씁니다.

스킬 없이 그 일을 시켜 보고 틀리거나 빠뜨린 것을 적습니다.
그 빈틈을 보는 시험 부탁을 셋 이상 만듭니다 — 스킬이 쓰이면 안 되는 부탁도 하나 넣습니다.
빈틈을 메울 만큼만 지시를 씁니다.
새 세션에서 같은 부탁을 스킬이 있을 때와 없을 때 해 보고 비교합니다.
쓸 모델 모두로 시험합니다 — 작은 모델에는 설명이 더 필요할 수 있습니다.

Terminal

# checks the frontmatter and the naming rules
skills-ref validate ./commit-message

evals.json (your own format)

[
  {"query": "write a commit message for what I staged", "use_skill": true},
  {"query": "commit this, it fixes the login bug",      "use_skill": true},
  {"query": "explain what git rebase does",             "use_skill": false}
]

skills-ref 는 agentskills 저장소의 참고 도구(시연용)입니다 — 내려받아 pip install -e . 로 설치합니다. Claude Code 에서는 /skill-doctor 가 스킬마다 컨텍스트 비용과 사용 횟수를 보여 줍니다.

안전 — 남의 스킬은 코드처럼 읽기

스킬은 에이전트가 따르는 지시이고, 그 스크립트는 내 컴퓨터에서 실행됩니다. 나쁜 스킬은 에이전트가 나쁜 지시를 따르게 만들므로 설치 전에 확인합니다.

믿을 수 있는 곳에서만 설치합니다. -l 을 주면 설치하지 않고 목록만 봅니다.
설치 전에 SKILL.md 와 scripts/ 의 모든 파일을 읽습니다.
파일이나 키를 다른 곳으로 보내거나 무언가를 지우는 명령이 있는지 봅니다.
스킬에 비밀번호나 키를 넣지 말고 환경 변수에서 읽게 합니다.
Claude Code: Skill(deploy *) 같은 권한 규칙으로 스킬을 막고, disableSkillShellExecution 설정으로 !`command` 를 끕니다.

Terminal

# see what is inside before you install
npx skills add my-name/my-skills -l

# read the instructions and every script
cat .agents/skills/<name>/SKILL.md
ls .agents/skills/<name>/scripts/

내 스킬도 마찬가지입니다. 커밋하거나 나누기 전에 바뀐 곳을 한 번 더 읽으세요.

고급 연습 — 내 스킬 키우기

중급에서 만든 스킬의 긴 부분을 references/ 로 옮기고 SKILL.md 에서 링크합니다.
scripts/ 에 검사 하나를 쓰고 SKILL.md 에 "검사 → 고치기 → 다시 검사" 단계를 더합니다.
스킬 폴더에 skills-ref validate 를 돌리고 알려 준 것을 고칩니다.
시험 부탁 셋(스킬이 쓰이면 안 되는 것 하나 포함)을 만들어 스킬이 있을 때와 없을 때를 비교합니다.
남이 만든 스킬 하나를 설치하기 전에 처음부터 끝까지 읽어 봅니다.

다섯 가지를 모두 해 봤다면 [마스터] 탭으로 넘어가세요.

공식 문서

2026-10-18 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.

마스터 — 내놓기·여러 도구·설계·돌보기

누구나 명령 한 줄로 설치하도록 내 을 내놓고, 한 스킬이 모든 에서 돌게 하고, 언제 스킬이 맞는 도구인지 정하고, 쓰면서 스킬을 좋게 유지합니다.

내 스킬 내놓기 — GitHub 저장소 하나로

공개 에 스킬을 올리면 누구나 npx skills add <owner>/<repo> 로 설치합니다. 저장소 하나에 스킬을 여러 개 둘 수 있습니다.

스킬마다 skills/ 아래 자기 폴더에 둡니다. 설치 도구가 찾아냅니다.
LICENSE 와, 스킬마다 무엇을 하는지와 설치 명령을 적은 README 를 둡니다.
쓰는 사람은 -s 로 스킬 하나만, -g 로 모든 프로젝트에 설치할 수 있습니다.
스킬을 고쳐 push 하면 쓰는 사람은 npx skills update 로 받습니다.

my-skills/

my-skills/                     # a public GitHub repository
├── README.md                  ← what each skill does + the install command
├── LICENSE
└── skills/
    ├── commit-message/SKILL.md
    └── sql-report/SKILL.md

# anyone can install it
npx skills add my-name/my-skills
npx skills add my-name/my-skills -s commit-message -g
npx skills update              # gets your new commits

내 웹사이트에서 내놓기 — SONUB 처럼

내 웹사이트에서도 스킬을 내놓을 수 있습니다. SONUB 가 그렇게 합니다: npx skills add ://sonub.com 은 /.well-known/agent-skills/index.json 의 목록을 읽고 스킬마다 압축 파일을 내려받습니다.

목록에는 스킬마다 이름·설명·압축 파일 주소와 그 압축 파일의 sha256 digest 가 있습니다.
digest 가 바뀌면 npx skills update 가 그 스킬을 다시 받습니다 — 바뀐 스킬만 업데이트됩니다.
name·description 이 규칙(폴더 이름과 같은 소문자 이름, 1,024자 이하 설명)을 어기면 설치 도구가 그 스킬을 말없이 건너뜁니다.
SONUB 는 요청 때마다 스킬 폴더에서 목록과 압축 파일을 만들므로, 고친 스킬을 배포하면 그대로 새 버전입니다.

sonub.com

# the list the installer reads
https://sonub.com/.well-known/agent-skills/index.json

# one archive per skill, with the sha256 digest of its bytes in the list
https://sonub.com/.well-known/agent-skills/gp.tar.gz

npx skills add https://sonub.com

SONUB 스킬과 설치 명령

한 스킬을 모든 도구에서

Agent Skills 는 열린 표준이라 폴더 하나가 Claude Code·Codex·Gemini CLI·GitHub Copilot 등에서 그대로 돌아갑니다. 도구마다 읽는 폴더만 다릅니다.

표준 필드(name·description)와 평범한 지시만으로 동작하게 만듭니다. 도구 전용 옵션은 덤입니다.
한 도구에 묶인 말("Bash 도구")은 피하고 "터미널에서 실행한다"처럼 씁니다.
진짜 폴더는 .agents/skills/ 에 하나 두고 .claude/skills/ 에는 링크를 겁니다. npx skills add 가 이렇게 해 줄 수 있고(권장), --copy 를 주면 복사합니다.
Claude Code 에서는 스킬을 서브 에이전트·훅·MCP 와 함께 플러그인으로 묶어 마켓플레이스로 나눌 수도 있습니다.

Terminal

# one real folder for every tool
.agents/skills/commit-message/

# a link so Claude Code finds the same folder
mkdir -p .claude/skills
ln -s ../../.agents/skills/commit-message .claude/skills/commit-message

스킬에서 MCP 도구를 쓰면 서버 이름까지 붙인 전체 이름(ServerName:tool_name)으로 씁니다. 없으면 에이전트가 도구를 못 찾을 수 있습니다.

Claude Code 마스터 — 플러그인

설계 — 언제 스킬로, 언제 다른 것으로

에이전트에게 가르치는 방법은 여럿입니다. 스킬이 맞는 자리에 스킬을 쓰면 일이 단순해집니다.

모든 대화에서 지킬 규칙 → AGENTS.md(또는 CLAUDE.md).
가끔 필요한 절차나 지식 → 스킬.
큰 일을 맡기고 결과만 받기 → 서브 에이전트.
바깥 서비스·데이터와 연결 → MCP. 그 도구를 어떻게 쓸지는 스킬이 가르칠 수 있습니다.
매번 반드시 일어나야 하는 일(고칠 때마다 포맷) → 훅.

스킬 하나에 일 하나. 스킬이 너무 많은 일을 하면 나눕니다.

스킬 돌보기 — 쓰면서 좋게

스킬은 짐작이 아니라 일하는 모습을 보며 좋아집니다. 실제 일에 쓰고, 에이전트가 헤매는 곳을 고칩니다.

에이전트가 어떻게 쓰는지 봅니다: 한 번도 안 읽는 파일, 자꾸 다시 읽는 파일, 놓치는 규칙.
한 AI 세션에서 스킬을 고치고 새 세션에서 시험합니다 — 새 세션이 빠진 것을 보여 줍니다.
날짜("8월 전에는 …") 대신 지금 방법을 쓰고, 옛 방법은 "옛 방법" 단락에 접어 둡니다.
아무도 안 쓰는 스킬은 지웁니다 — 설명 하나하나가 모든 세션의 컨텍스트를 차지합니다.
팀에게 묻습니다: 바랄 때 시작했나? 지시가 분명했나? 무엇이 빠졌나?

마스터 체크리스트

description 에 무엇을 하는지·언제 쓰는지·사람들이 실제로 쓰는 낱말이 있다
SKILL.md 는 500줄 아래이고, 다른 파일은 한 단계로 링크한다
스크립트는 오류를 스스로 처리하고, 실행할지 읽을지 분명하다
시험이 셋 이상이고, 스킬이 쓰이면 안 되는 경우도 있다
비밀 값이 없고, 남의 스킬은 읽어 본 뒤 설치한다
쓸 에이전트와 모델에서 확인했고, 설치 명령과 함께 내놓았다

모두 체크했다면 내 스킬 하나를 GitHub 에 올려 npx skills add 로 나눠 보세요.

공식 문서

2026-10-18 에 공식 문서로 확인했어요. 도구가 자주 바뀌니 명령이 안 되면 공식 문서를 보세요.

기초 — 스킬이 무엇이고 어떻게 설치하나

에이전트 스킬 알아보기

쉽게 이해하기

에이전트 스킬이란?

한 번 배우면 여러 AI 도구에서

어떻게 동작할까요 — 필요한 만큼만 읽는 세 단계

폴더 구조와 SKILL.md 규칙

만들어 보기 — 파일 하나로 5분

잘 만드는 요령

명령 한 줄로 설치

명령을 몰라도 — 인공지능에게 설치해 달라고 말하기

자주 쓰는 옵션

업데이트와 삭제

스킬

이렇게 말해 보세요

따라 해 보기: gp 스킬로 일감 관리하기

이 스킬만 설치

이렇게 말해 보세요

이 스킬만 설치

이렇게 말해 보세요

이 스킬만 설치

자주 묻는 질문

중급 — 나만의 스킬 만들기

첫 스킬 — 되풀이하는 부탁을 스킬로

description — 에이전트가 가진 단 하나의 단서

본문 지시 — 짧게, 차례대로, 예시와 함께

스킬 부르기와 확인

어디에 둘까 — 나만, 아니면 팀이 함께

중급 연습 — 내 프로젝트에서 하나 만들기

공식 문서

고급 — 큰 스킬: 파일 나누기·스크립트·옵션·시험·안전

파일로 나누기 — 필요한 것만 읽게

스크립트 — 매번 똑같아야 하는 일은 코드로

frontmatter 옵션 — 표준과 도구마다의 덤

시험 — 많이 쓰기 전에 시험부터

안전 — 남의 스킬은 코드처럼 읽기

고급 연습 — 내 스킬 키우기

공식 문서

마스터 — 내놓기·여러 도구·설계·돌보기

내 스킬 내놓기 — GitHub 저장소 하나로

내 웹사이트에서 내놓기 — SONUB 처럼

한 스킬을 모든 도구에서

설계 — 언제 스킬로, 언제 다른 것으로

스킬 돌보기 — 쓰면서 좋게

마스터 체크리스트

공식 문서

만들기

소통

더보기