[실습] 나만의 에이전트 스킬 구축하기

앞 장에서 설계도를 봤다면, 이제는 망치를 들어야 할 차례입니다. 스킬은 개념으로 이해할 때보다 직접 하나 만들어 볼 때 훨씬 빨리 감이 옵니다. 특히 Gemini CLI는 스킬을 작업 공간이나 사용자 범위에서 자동으로 발견하고, 요청과 설명이 맞아떨어질 때 필요한 스킬만 불러오는 구조를 갖고 있어서 실습용으로 좋습니다.¹

이 장에서는 두 가지를 만듭니다. 하나는 매일 써먹기 좋은 코드 리뷰·리팩터링 스킬이고, 다른 하나는 외부 API를 호출해 최신 데이터를 가져오는 고급 스킬입니다. 장을 끝낼 때쯤이면 독자는 "스킬이 뭔지는 알겠는데, 그래서 어떻게 만들죠?"가 아니라 "아, 이건 내 프로젝트에도 바로 넣을 수 있겠다"라는 감각을 얻게 될 것입니다.

3.1 개발 환경 설정: Gemini CLI 및 에이전트 도구 연동

실습은 최대한 단순하게 가는 것이 좋습니다. 처음부터 거대한 팀용 레지스트리나 사내 인프라를 붙이면 금방 숨이 찹니다. 먼저 로컬에서 돌아가는 가장 작은 성공 사례를 만든 뒤, 그다음에 확장하면 됩니다.

Gemini CLI를 쓰려면 우선 Node.js 20 이상이 필요합니다. 설치 방법은 npm, Homebrew, 운영체제별 패키지 매니저 등 여러 가지가 있지만, 가장 무난한 시작은 npm 전역 설치입니다.¹²

npm install -g @google/gemini-cli
gemini --version

설치가 끝났다면 인증을 진행합니다. 개인 Google 계정으로 로그인해도 되고, 서버나 자동화 환경이라면 API 키를 쓸 수도 있습니다. 로컬 실습은 대개 로그인 방식이 가장 편합니다.²

이제 실습용 폴더를 하나 만듭니다.

mkdir -p ~/agent-skills-lab
cd ~/agent-skills-lab
mkdir -p .agents/skills

여기서 .agents/skills가 중요합니다. Gemini CLI는 작업 공간의 .gemini/skills/ 또는 .agents/skills/에서 스킬을 찾고, 사용자 전역으로는 ~/.gemini/skills/ 또는 ~/.agents/skills/를 살핍니다. 이름이 같은 스킬이 겹치면 작업 공간 스킬이 사용자 스킬보다 우선합니다. 같은 우선순위 안에서는 .agents/skills/ 별칭이 .gemini/skills/보다 먼저 적용됩니다.¹

이 우선순위는 실무에서 꽤 유용합니다. 예를 들어 평소에는 전역으로 쓰는 code-review 스킬이 있지만, 어떤 저장소에서는 더 엄격한 규칙이 필요할 수 있습니다. 그럴 때 프로젝트 안에 같은 이름의 스킬을 두면 해당 저장소에서만 덮어쓸 수 있습니다. 한마디로, 에이전트에게 "회사 표준은 이거지만, 이 프로젝트에선 예외야"라고 말하는 셈입니다.

Gemini CLI를 실행한 뒤 스킬이 보이는지 확인합니다.

gemini

세션 안에서는 다음 명령이 가장 자주 쓰입니다.¹

/skills list
/skills reload
/skills enable <name>
/skills disable <name>
/skills link <path>

터미널에서 바로 관리하고 싶다면 아래 명령도 쓸 수 있습니다.¹

gemini skills list
gemini skills link /path/to/local/skills-repo
gemini skills install /path/to/local/skill --scope workspace

처음에는 "왜 굳이 workspace와 user를 나누지?" 싶을 수 있습니다. 하지만 금방 이유를 알게 됩니다.

• 작업 공간 스킬은 프로젝트와 함께 버전 관리하기 좋습니다.

• 사용자 스킬은 어떤 저장소에 가도 쓸 수 있는 개인 무기입니다.

• 같은 이름을 덮어쓸 수 있어 팀 규칙과 개인 습관을 분리하기 쉽습니다.

여기에 에이전트 도구를 더 붙이면 활용 범위가 넓어집니다. 스킬은 절차를 가르치고, 도구는 실제 행동을 담당합니다. 예를 들어 MCP 서버를 연결하고 싶다면, Gemini CLI의 settings.json에 mcpServers 항목을 추가해 서버 명령이나 URL을 등록하는 방식이 기본입니다.³

{
  "mcpServers": {
    "debug-server": {
      "command": "npx",
      "args": ["-y", "some-debug-mcp-package"],
      "trust": false
    }
  }
}

아직 MCP가 익숙하지 않더라도 겁먹을 필요는 없습니다. 지금 단계에서는 "스킬이 일하는 방식이라면, MCP는 손과 발 같은 도구" 정도로 이해하면 충분합니다. 이번 장의 핵심은 스킬 자체를 만드는 것이고, 도구 연동은 그 스킬이 더 멀리 움직이게 하는 보조 수단이라고 생각하면 됩니다.

혹시 스킬이 전혀 인식되지 않는다면 두 가지를 먼저 의심하면 됩니다. 하나는 디렉터리 위치가 잘못된 경우이고, 다른 하나는 세션이 오래된 경우입니다. 이럴 때는 경로와 파일 이름을 먼저 확인하고, 그다음 /skills reload를 실행하는 편이 빠릅니다.¹

3.2 기초 스킬 만들기: 반복적인 코드 리뷰 및 리팩터링 자동화

첫 스킬은 어렵지 않아야 합니다. 동시에 자주 써야 합니다. 그래서 코드 리뷰와 리팩터링 점검이 좋습니다. 거의 모든 개발 프로젝트에서 반복되고, 잘 만들어 두면 체감 효과도 큽니다.

실습용 스킬 폴더를 만듭니다.

mkdir -p .agents/skills/code-review-refactor/references

그리고 SKILL.md를 작성합니다.

---
name: code-review-refactor
description: >-
  Review code changes and suggest safe refactoring steps.
  Use this skill when the user asks for code review, refactoring,
  bug-risk analysis, maintainability feedback, or PR comments.
---

# Code Review Refactor

Use this skill to review source changes and recommend small, reversible improvements.

Load the detailed checklist from [review-checklist](./references/review-checklist.md) when needed.

## Workflow

1. Read the relevant files first and summarize the purpose of the change.
2. Review correctness, readability, duplication, error handling, and tests.
3. Prefer small refactoring ideas over large rewrites.
4. If a risk is uncertain, state the uncertainty clearly instead of guessing.
5. When suggesting a patch, explain why the change is safe.

## Output Format

- Overall assessment
- Top risks
- Refactoring opportunities
- Missing tests
- Recommended next step

이제 체크리스트 파일도 만듭니다.

# Review Checklist

## Correctness
- Are there edge cases for null, empty input, or invalid state?
- Could async flow, race conditions, or stale state break behavior?
- Are return values and error paths consistent?

## Readability
- Is naming clear?
- Is a function doing too many things?
- Can duplicated logic be extracted safely?

## Test Coverage
- Are happy path tests present?
- Are failure and boundary cases covered?
- Does the patch need regression tests?

이 스킬이 좋은 이유는 두 가지입니다. 첫째, 절차가 명확합니다. 둘째, 과하게 똑똑한 척하지 않습니다. 처음 만든 스킬은 보통 열정은 넘치지만 방향 감각이 부족한 신입사원과 비슷합니다. 그래서 "무엇을 먼저 읽고, 어떤 관점으로 보고, 어떤 형식으로 답할지"를 또렷하게 적어 주는 편이 낫습니다.

이제 Gemini CLI에서 확인해 봅시다.

/skills list

목록에 code-review-refactor가 보이면 반은 성공입니다. 그다음은 실제 활성화 테스트입니다. 예를 들어 이렇게 물어봅니다.

src/auth/login.ts를 리뷰하고 리팩터링 포인트와 테스트 누락을 찾아줘.

Gemini는 요청 내용과 스킬 설명을 비교해 해당 스킬이 맞다고 판단하면 활성화 승인을 물어봅니다. 승인하면 SKILL.md 본문과 스킬 폴더 자원에 접근할 수 있게 되고, 그 세션 동안 그 절차를 우선적으로 따릅니다.¹

여기서 중요한 포인트는 설명문입니다. description이 흐리면 자동 활성화가 잘 안 됩니다. 예를 들어 "코드 품질을 돕는 스킬" 정도로 적으면 너무 추상적입니다. 반면 "code review, refactoring, PR comments, bug-risk analysis"처럼 실제 요청에 나올 표현을 함께 넣으면 훨씬 잘 잡힙니다. 스킬은 마법 주문이 아니라 검색 가능한 전문성이라는 사실을 기억하면 좋습니다.¹⁵

만약 자동 활성화가 잘 안 되면 억지로 참지 말고 명시적으로 스킬을 활성화하거나, 프로젝트의 상시 문맥 파일과 함께 사용하는 방법도 고려할 수 있습니다. 중요한 것은 "스킬이 언제 켜져야 하는지"를 사람이 먼저 분명하게 설계하는 것입니다.⁵

이쯤에서 한 번 더 정리해 봅시다. 좋은 리뷰 스킬은 보통 다음 세 가지를 반드시 담습니다.

• 언제 사용해야 하는지

• 무엇을 어떤 순서로 점검하는지

• 답변을 어떤 형식으로 내야 하는지

셋 중 하나라도 빠지면 결과가 흔들립니다. 특히 출력 형식이 없으면, 어떤 날은 장문의 설명을 하고 어떤 날은 한 줄 평만 남기는 일이 생깁니다. 사람에게도 체크리스트가 필요하듯, 에이전트에게도 결과물의 모양을 알려 주는 편이 훨씬 안정적입니다.

3.3 고급 스킬 만들기: 외부 API 호출 및 실시간 데이터 처리 스크립트 작성

이제 조금 더 실무다운 것을 만들어 봅시다. 개발 현장에서 AI가 자주 틀리는 것 중 하나가 "최신 버전"입니다. 모델은 그럴듯하게 말하지만, 패키지 버전은 생각보다 자주 낡습니다. 그래서 외부 API를 직접 조회하는 스킬이 꽤 유용합니다. 이 예제에서는 npm 레지스트리의 최신 버전을 실시간으로 조회하는 스킬을 만듭니다. 핵심은 간단합니다. 모델이 추측하지 말고, 실제로 확인하게 만드는 것입니다.⁶

먼저 폴더를 만듭니다.

mkdir -p .agents/skills/latest-package-check/scripts

다음으로 scripts/latest-package.mjs 파일을 만듭니다.

#!/usr/bin/env node

const packages = process.argv.slice(2);

if (packages.length === 0) {
  console.error("Usage: node latest-package.mjs <package> [package...]");
  process.exit(1);
}

const results = [];

for (const pkg of packages) {
  const url = `https://registry.npmjs.org/${encodeURIComponent(pkg)}/latest`;
  const res = await fetch(url, {
    headers: { Accept: "application/json" }
  });

  if (!res.ok) {
    results.push({ name: pkg, error: `HTTP ${res.status}` });
    continue;
  }

  const data = await res.json();
  results.push({
    name: data.name,
    latestVersion: data.version,
    license: data.license ?? null,
    homepage: data.homepage ?? null,
    repository: data.repository?.url ?? null
  });
}

console.log(JSON.stringify(results, null, 2));

Node 20 이상이라면 기본 fetch를 그대로 쓸 수 있어서 준비가 간단합니다. 바로 이럴 때 "도구는 단순할수록 좋다"는 말이 실감 납니다. 거대한 SDK를 붙이지 않아도, 실제 문제를 해결하는 데는 이 정도면 충분합니다.

이제 SKILL.md를 작성합니다.

---
name: latest-package-check
description: >-
  Check the latest npm package versions in real time and compare them with
  project dependencies. Use this skill when the user asks for dependency
  upgrades, package version checks, package.json review, or update planning.
---

# Latest Package Check

Use this skill when the task requires real-time dependency information.
Never guess the latest package version.

## Workflow

1. Read `package.json` to identify current dependency versions.
2. Run `node ./scripts/latest-package.mjs <package names>` for requested packages.
3. Compare the current version and the latest version.
4. Call out major version jumps separately from minor or patch upgrades.
5. If a package is not found in `package.json`, say so clearly.
6. Summarize upgrade risk and suggest the safest order of update.

## Output Format

- Current version
- Latest version
- Upgrade gap
- Risk level
- Suggested next action

이제 이렇게 테스트할 수 있습니다.

우리 프로젝트의 react, vite, zod 최신 버전을 확인하고 업데이트 위험도를 요약해줘.

Gemini가 스킬을 활성화하면, 스크립트를 실행해 실제 레지스트리 값을 받아오고 그 결과를 바탕으로 비교를 진행할 수 있습니다. 이 순간부터 답변의 근거가 "모델 기억"이 아니라 "실시간 조회 결과"로 바뀝니다. 이것이 바로 스킬이 프롬프트보다 실무에 강한 이유입니다. 잘 만든 스킬은 지식만 주입하는 것이 아니라, 필요한 행동 경로를 함께 만듭니다.

여기서 한 단계 더 나아가고 싶다면, 이 스킬에 작은 규칙 파일을 붙일 수 있습니다. 예를 들어 references/upgrade-policy.md를 두고 "메이저 업그레이드는 changelog 확인 전 자동 제안 금지" 같은 팀 정책을 적어 둘 수 있습니다. 그러면 스킬은 최신 버전 조회와 사내 업데이트 원칙을 한 번에 연결하는 작고 똑똑한 작업 단위가 됩니다.

이 패턴은 다른 작업에도 그대로 적용됩니다. npm 대신 GitHub Releases API를 조회해도 되고, 사내 REST API를 읽어도 되고, 로그 분석 스크립트를 붙여도 됩니다. 구조는 같습니다.

• SKILL.md에는 언제 쓰고 어떤 순서로 일할지 적습니다.

• scripts/에는 실제 조회나 변환 로직을 넣습니다.

• references/에는 길지만 자주 바뀌는 규칙을 넣습니다.

이렇게 나누면 스킬은 작고 날렵해집니다. 에이전트는 필요할 때만 필요한 파일을 읽고, 우리는 규칙 변경이 생겨도 해당 부분만 바꾸면 됩니다. 한 번 만들어 보면 "이건 스킬이라기보다 작은 자동화 서비스 같네?"라는 생각이 드는데, 바로 그 감각이 맞습니다.

3.4 디버깅과 최적화: 에이전트의 오작동을 줄이는 지침 정교화

이제 가장 중요한 구간입니다. 스킬은 거의 항상 첫 버전이 어설픕니다. 이것은 실패가 아니라 정상입니다. 오히려 한 번에 완벽하게 동작하면, 아직 문제를 덜 만나 본 것에 가깝습니다.

스킬 디버깅은 일반 코드 디버깅과 닮았습니다. 증상을 보고, 재현하고, 원인을 좁히고, 수정하고, 다시 테스트합니다. 다른 점이 있다면 버그가 코드에만 있는 것이 아니라 설명문, 파일 경로, 활성화 조건, 출력 형식에도 숨어 있다는 점입니다.

실무에서 가장 자주 만나는 문제는 대체로 아래 다섯 가지입니다.

• 스킬이 아예 활성화되지 않는다.

• 활성화는 되는데 엉뚱한 일에까지 끼어든다.

• 절차는 따르지만 결과가 너무 들쭉날쭉하다.

• 스크립트 실행이 실패한다.

• 수정했는데도 이전 버전처럼 행동한다.

첫 번째 문제, 즉 활성화가 안 되는 경우는 보통 가장 단순한 원인에서 나옵니다. name과 디렉터리 이름이 다르거나, 스킬 위치가 잘못되었거나, 비활성화 상태이거나, 설명문이 약한 경우입니다. 이럴 때는 감으로 추측하지 말고 순서대로 확인합니다.

/skills list
/skills reload

필요하면 아래 명령으로 범위를 더 분명하게 볼 수도 있습니다.

gemini skills list

두 번째 문제는 스킬이 너무 넓을 때 생깁니다. 예를 들어 description에 review, fix, refactor, optimize, debug, design, test를 전부 넣어 버리면 거의 모든 개발 요청에 반응하려 듭니다. 이러면 스킬이 유능해지는 것이 아니라 참견이 심해집니다. 스킬 하나에는 책임 하나를 주는 편이 낫습니다. 리뷰 스킬은 리뷰답게, 버전 조회 스킬은 버전 조회답게 좁혀야 합니다.

세 번째 문제는 출력 형식이 느슨할 때 생깁니다. "적절히 설명해라"는 에이전트에게 너무 큰 자유를 줍니다. 반대로 "위험도, 근거, 다음 액션 순서로 답하라"처럼 틀을 주면 결과가 안정됩니다. 스킬은 창의적 글쓰기가 아니라 재현 가능한 업무 단위라는 점을 잊지 말아야 합니다.

네 번째 문제는 스크립트와 런타임입니다. Node 스크립트인데 Node가 없거나, Python 스크립트인데 실행 환경이 없거나, 네트워크 요청이 차단된 경우입니다. 이럴 때는 SKILL.md 본문이나 메타데이터에 필요한 실행 조건을 분명히 적는 편이 좋습니다. 스킬은 설명문이기도 하지만 운영 문서이기도 합니다.

다섯 번째 문제는 세션 캐시입니다. 이미 활성화된 스킬은 그 세션 동안 계속 우선 적용됩니다. 따라서 SKILL.md를 수정한 뒤에는 /skills reload를 하거나, 필요하면 세션을 새로 시작하는 편이 깔끔합니다.¹

스킬 품질을 끌어올리는 가장 실용적인 방법은 다음 루프를 짧게 도는 것입니다.

1. 실패하는 요청을 하나 고릅니다.

2. 스킬이 어떤 지점에서 엇나가는지 확인합니다.

3. 본문을 줄이거나, 설명을 좁히거나, 출력 형식을 더 또렷하게 만듭니다.

4. 다시 reload하고 같은 요청으로 재시험합니다.

5. 잘되면 그 상태를 버전처럼 관리합니다.

그리고 아주 중요한 팁이 하나 있습니다. 오래 씨름해서 겨우 좋은 결과를 만든 세션이 있었다면, 그 세션을 그냥 흘려보내지 말고 스킬로 굳히는 편이 좋습니다. "이번에 힘들게 가르친 방법"을 곧바로 다음 번을 위한 자산으로 바꾸는 것입니다.⁶

실전에서는 이런 문장이 꽤 강력합니다.

방금 우리가 진행한 디버깅 절차를 재사용 가능한 스킬로 정리해줘.

이 한 줄이 주는 의미는 큽니다. 프롬프트는 세션이 끝나면 사라지지만, 스킬은 다음 세션부터 팀 자산이 됩니다.

3.5 스킬은 작게 시작할수록 빨리 강해진다

처음부터 거창한 범용 스킬을 만들 필요는 없습니다. 오히려 작을수록 좋습니다. 코드 리뷰, 최신 버전 확인, 로그 요약, 배포 전 점검처럼 반복되지만 매번 다시 설명하던 일을 하나 골라 스킬로 만들면 됩니다. 그 작은 자동화가 쌓이면, 어느 순간 에이전트는 단순한 채팅 상대가 아니라 일하는 방식이 정리된 협업 파트너가 됩니다.

이 장에서 만든 두 가지 예제는 성격이 다릅니다. code-review-refactor는 절차 중심 스킬이고, latest-package-check는 절차와 실행 스크립트가 결합된 스킬입니다. 이 둘을 모두 손에 넣었다면, 이미 스킬 설계의 핵심을 익힌 셈입니다. 무엇을 언제 쓸지 설명하고, 필요한 파일을 묶고, 출력 형식을 고정하고, 실제 도구나 스크립트로 행동하게 만든다. 스킬은 결국 이 네 가지의 조합입니다.

다음 장에서는 이 개별 스킬들을 더 큰 흐름으로 엮게 됩니다. 하나의 스킬이 유능한 전문가라면, 여러 스킬이 연결된 워크플로우는 작은 팀입니다. 이제 우리는 그 팀을 움직일 준비가 거의 끝났습니다.

참고

¹Agent Skills | Gemini CLI

²Gemini CLI on Linux, macOS, and Windows (Agent Setup)

³MCP servers with the Gemini CLI

⁵agent-skills/docs/gemini-cli-setup.md at main · addyosmani/agent-skills · GitHub

⁶Building Agent Skills with skill-creator