AI 에이전트에게 새 기술을 가르치세요 — 1분이면 됩니다

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

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

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

# 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자 이하이고 폴더 이름과 같습니다.

# ✗ 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줄 아래로 둡니다. 길어지면 파일로 나눕니다([고급] 탭).

---
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
/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 키를 넣지 마세요 — 스킬 파일은 읽히고 자주 공유됩니다.

# 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"

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

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

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

공식 문서

• Agent Skills — Quickstart
• Agent Skills — Specification
• Claude Code — Skills
• Codex — Skills

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

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

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

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

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

## 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초인가?).

## 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> 으로 부를 때만 쓰입니다.

---
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 에는 스킬에 꼭 필요한 명령만 넣으세요. 권한이 넓을수록 실수의 대가가 커집니다.

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

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

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

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

[
  {"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` 를 끕니다.

# 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/

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

고급 연습 — 내 스킬 키우기

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

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

공식 문서

• Skill authoring best practices
• Agent Skills — Specification
• skills-ref — GitHub
• Claude Code — Skills

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

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

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

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

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 https://sonub.com 은 /.well-known/agent-skills/index.json 의 목록을 읽고 스킬마다 압축 파일을 내려받습니다.

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

# 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 와 함께 플러그인으로 묶어 마켓플레이스로 나눌 수도 있습니다.

# 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. 그 도구를 어떻게 쓸지는 스킬이 가르칠 수 있습니다.
• 매번 반드시 일어나야 하는 일(고칠 때마다 포맷) → 훅.

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

• Claude Code 고급 — 스킬·서브 에이전트·훅·MCP
• Codex 고급 — 설정·MCP·스킬·훅

스킬 돌보기 — 쓰면서 좋게

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

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

마스터 체크리스트

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

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

공식 문서

• skills CLI (npx skills) — GitHub
• Agent Skills
• Claude Code — Plugins
• Skill authoring best practices

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