에이전트 스킬을 처음부터 구축하기

발행: 2일 전 (2025년 12월 26일 오후 05:20 GMT+9)

15 min read

원문: Dev.to

Source: Dev.to

(번역할 텍스트를 제공해 주시면 한국어로 번역해 드리겠습니다.)

에이전트 스킬 – 작동 방식 및 통합 방법

View the complete implementation on GitHub

에이전트 스킬이란?

에이전트 스킬은 간단한 문제를 해결합니다: 에이전트를 모든 분야에 능숙하게 만들려고 하면 시스템 프롬프트가 비대해진다.

모든 내용을 하나의 거대한 프롬프트에 넣는 대신:

You're an expert at code review, git, file organization, API testing...
[2000 lines of instructions]

다음과 같이 구분되고 재사용 가능한 스킬을 정의합니다:

You have access to these skills:
- code-review: Reviews code for bugs and security
- git-helper: Git workflows and troubleshooting
- file-organizer: Organizes files intelligently
- api-tester: Tests REST APIs

Load them when needed.

각 스킬은 에이전트가 필요할 때 로드할 수 있는 자체 포함된 마크다운 파일입니다.

핵심 아이디어

스킬은 디렉터리에 저장된 마크다운 파일입니다. 구성은 다음과 같습니다:

YAML 프론트‑머터 – name, description 및 선택적 메타데이터를 포함합니다.
(프론트‑머터가 처음이라면 이 가이드를 참고하세요.)
마크다운 본문 – 임시 시스템 프롬프트 역할을 하는 상세 지시사항.

에이전트가 전문 지식이 필요할 때 해당 스킬을 로드합니다:

User: "Review this code for SQL injection"
   ↓
Agent: "I need the code‑review skill"
   ↓
System: [Loads SKILL.md with security guidelines]
   ↓
Agent: [Follows those guidelines]

따라서 스킬은 구조화된, 모듈형 프롬프트이며, 필요할 때만 발견되고 로드됩니다.

실제 작동 방식

1️⃣ 탐색

디렉터리에서 SKILL.md 파일을 스캔하고 앞부분 메타데이터만 파싱합니다.
이를 통해 전체 내용을 로드하지 않고도 사용 가능한 스킬 목록을 얻을 수 있어 메모리 사용량을 최소화합니다.

skills/
├── code-review/
│   └── SKILL.md   # name: code-review, description: …
├── git-helper/
│   └── SKILL.md

구현 세부 사항은 저장소의 discovery module에서 확인할 수 있습니다.

2️⃣ 도구 등록

각 스킬을 OpenAI 함수 도구로 변환합니다. LLM은 이를 호출 가능한 함수로 인식합니다:

{
  "name": "activate_skill_code_review",
  "description": "Reviews code for bugs, security, best practices"
},
{
  "name": "activate_skill_git_helper",
  "description": "Git workflows and troubleshooting"
}

설명은 매우 중요합니다—LLM이 어떤 스킬을 활성화할지 결정하는 데 지침이 되기 때문입니다. 가능한 한 구체적이고 명확하게 작성하세요.

3️⃣ 활성화

LLM이 스킬 함수를 호출하면:

디스크에서 전체 SKILL.md 내용을 로드합니다.
이를 도구 결과(즉, 임시 시스템 프롬프트)로 모델에 반환합니다.
이제 LLM은 스킬의 지침에 따라 계속 진행합니다.

이러한 지연 로딩 방식 덕분에 20개의 스킬이 있더라도 실제로 사용되는 2개만 메모리에 읽어들입니다.

4️⃣ 실행

LLM은 스킬 지침을 읽고 해당 턴의 시스템 프롬프트 일부인 것처럼 따라 실행합니다. 작업이 완료되면 스킬 지침은 별도로 유지하지 않는 한 컨텍스트에서 자연스럽게 사라집니다. 멀티턴 상호작용을 위해 명시적으로 보관하지 않는 한 말이죠.

스킬은 어떻게 보이는가

---
name: code-review
description: Reviews code for bugs, security, and best practices
version: 1.0.0
---

# Code Review Skill

You are an expert code reviewer.

* Identify potential bugs and security vulnerabilities.
* Suggest improvements for readability and performance.
* Provide concrete code snippets for fixes.

각 스킬은 이와 동일한 구조를 따릅니다: 프론트‑머터 + 상세 마크다운 본문.

빠른 요약

단계	내용
Discovery	디렉터리를 스캔하고 프론트‑머터만 읽음.
Tool Registration	각 스킬을 OpenAI 함수로 등록.
Activation	LLM이 함수를 호출 → 전체 마크다운을 로드 → 도구 결과로 전송.
Execution	LLM이 현재 작업에 대한 스킬 지침을 따름.

이 패턴을 사용하면 시스템 프롬프트를 간결하게 유지하고, 전문성을 모듈화하며, 에이전트가 필요한 정확한 지식을 동적으로 가져올 수 있습니다. 즐거운 코딩 되세요!

Checklist

Security

SQL injection in queries
XSS in user inputs
Authentication bypasses

Quality

Readability
Maintainability
DRY violations

Performance

N+1 queries
Memory leaks
Inefficient algorithms

I’m happy to help translate the text, but I don’t see the passage you’d like me to translate. Could you please provide the text (including the source line beginning with Source:) that you want translated into Korean? Once I have it, I’ll return the translation in the requested format while preserving the original formatting and code blocks.

왜 이 패턴이 효과적인가

1. 컨텍스트 효율성

미리 10 KB의 지시문을 로드하는 대신 메타데이터 100 바이트만 로드합니다. 전체 지시문은 필요할 때만 불러옵니다. 토큰당 비용을 지불하고 있다면 이것이 중요합니다.

2. 모듈성

각 스킬은 독립적입니다. SKILL.md 파일을 추가하기만 하면 새로운 스킬을 넣을 수—코드 변경이 필요 없습니다. 스킬을 제거하고 싶다면 디렉터리를 삭제하면 됩니다.

3. 명확성

디버깅 시 어떤 스킬이 활성화됐고 어떤 지시문을 제공했는지 정확히 확인할 수 있습니다. 이는 단일 프롬프트보다 문제 해결을 훨씬 쉽게 만들어 줍니다.

4. 재사용성

프로젝트 간에 스킬을 공유하세요. 다른 사람이 만든 api-tester 스킬도 수정 없이 여러분의 에이전트에서 바로 사용할 수 있습니다. 스킬은 전문 지식의 공유 라이브러리가 됩니다.

Source: …

주요 설계 결정

지연 로딩

시작 시 모든 스킬을 메모리에 로드하지 마세요—이렇게 하면 처음부터 모든 것을 로드하는 것과 같은 효과가 됩니다.
필요할 때 로드하세요. 탐색 단계에서 프론트‑머터를 파싱하되, 전체 내용은 LLM이 실제로 요청할 때까지 디스크에 보관합니다.

함수 명명

스킬 함수에 명확히 접두사를 붙이세요, 예: activate_skill_code_review. 이렇게 하면 로그에서 무슨 일이 일어나고 있는지 바로 알 수 있습니다. 로그에 activate_skill_*가 보이면 스킬이 활성화된 것입니다.

대화 흐름

정확한 순서가 중요합니다. 흐름은 다음과 같습니다:

사용자가 메시지를 보냅니다.
LLM이 tool_calls(스킬 요청)와 함께 응답합니다.
중요: tool_calls가 포함된 어시스턴트 메시지를 대화에 추가하세요.
스킬 내용을 담은 툴 메시지를 추가합니다.
LLM이 스킬 지시를 이어서 수행합니다.
최종 응답을 반환합니다.

3단계를 건너뛰면 OpenAI가 요청을 거부합니다. tool_calls는 type 필드와 중첩된 function 객체를 올바르게 포함해야 합니다. 이는 흔히 발생하는 실수입니다. (자세한 내용은 OpenAI 도구 문서를 참고하세요.)

다중 툴 호출을 위한 루프

스킬은 체인될 수 있습니다. 어떤 스킬은 코드 실행을 활성화하고, 그 과정에서 또 다른 스킬이 필요할 수 있습니다. 에이전트는 툴 호출이 더 이상 없을 때까지 반복해야 합니다:

while True:
    response = llm.chat(messages=messages, tools=tools)
    if not response.get("tool_calls"):
        break
    handle_tool_calls(response)

스킬이 활성화된 후에도 매 호출마다 tools를 전달하세요. 그렇지 않으면 스킬이 코드 실행 같은 다른 도구를 사용할 수 없습니다. (전체 구현 예시에서 전체 루프 로직을 확인할 수 있습니다.)

실용적인 고려사항

스킬 범위

하나의 스킬 = 하나의 도메인. 집중하도록 하세요.

좋은 예시: code-review, git-helper, api-tester
나쁜 예시: developer-tools (너무 광범위)

스킬 구조

예시와 함께 명확한 섹션을 사용하세요:

스킬이 수행하는 작업
작업에 접근하는 방법
예상 출력 형식
좋은 결과 예시

한 덩어리의 텍스트는 효과적이지 않습니다. 구조화가 LLM이 지시를 따르는 데 도움이 됩니다.

오류 처리

스킬이 존재하지 않을 경우 어떻게 할까요? 도움이 되는 오류를 반환하세요, 예:

"Skill 'xyz' not found. Available: code-review, git-helper"

Common Mistakes & Troubleshooting

Loading Everything Upfront

Problem: Some implementations load all skills at startup, wasting memory and context tokens.

Fix: Load only metadata during discovery. Activate skills on demand.

Vague Skill Descriptions

The LLM uses skill descriptions to decide which to activate. Be specific.

❌ “Helps with code”
✅ “Reviews Python/JavaScript code for security vulnerabilities, PEP 8 compliance, and performance issues”

Include what the skill does, the task types it handles, and key capabilities.

Wrong Tool Calls Format

Error: Missing required parameter: messages[1].tool_calls[0].type

Cause: OpenAI requires a specific nested structure. tool_calls must have a type field and nest the function details under a function key.

Fix: Use the correct format with type: "function" and a nested function object. See the OpenAI tools documentation.

Forgetting to Include Tools After Skill Activation

Problem: After activating a skill, the LLM can’t use other tools like code execution.

Fix: Always pass tools in every LLM call. Don’t remove tools after skill activation because skills might need them.

No Structure in Skills

A wall of text doesn’t work. Use clear headings, bullet points, code examples, and expected output formats. The LLM follows structured instructions much better than prose.

When Skills Make Sense

Good fit:

Multi‑domain agents that handle code, git, and DevOps
Agents with specialized workflows
Teams sharing common patterns
Situations where you hit context limits

Not needed:

Single‑purpose agents
Agents with small, focused prompts
Prototypes and experiments

Don’t over‑engineer. If your system prompt is small and manageable, you probably don’t need skills.

표준

AgentSkills.io는 개방형 포맷을 정의합니다:

SKILL.md 명명 규칙
YAML front‑matter 스키마
디렉터리 구조
모범 사례

표준을 따르면 여러분의 스킬이 다른 구현에서도 작동합니다. 스킬은 프로젝트와 팀 간에 이식 가능해집니다.

첫 번째 스킬 만들기

디렉터리 생성
```
mkdir -p skills/my-first-skill
```
SKILL.md 를 만들고 YAML 프론트‑매터와 마크다운 지침을 추가합니다.
SkillsManager 를 에이전트에 통합합니다 – 전체 코드는 GitHub 저장소를 참고하세요.
테스트: 에이전트에게 스킬 사용을 요청하고 정상적으로 활성화되는지 확인합니다.

그게 전부입니다. 새로운 스킬을 추가하기 위해 코드 변경이 필요하지 않습니다— SKILL.md 파일만 넣으면 됩니다.

Bottom Line

에이전트 스킬은 로딩 메커니즘을 갖춘 구조화된 프롬프트입니다. 이 패턴이 효과적인 이유는 다음과 같습니다:

필요한 것만 로드하여 컨텍스트를 가볍게 유지합니다.
스킬이 독립적이므로 에이전트를 모듈식으로 구성할 수 있습니다.
스킬 재사용이 가능해 프로젝트 간에 스킬을 공유할 수 있습니다.
명확한 활성화 로그를 통해 디버깅이 간편합니다.

오후만 투자하면 작동하는 구현을 만들 수 있습니다. 핵심 SkillsManager는 약 130줄의 파이썬 코드로 구성되어 있습니다. (구현 보기)

하나의 스킬부터 시작하세요.
도움이 되는지 확인하세요.
그 다음에 확장하세요.

전체 작동 구현은 GitHub에서 확인할 수 있습니다. 이를 참고하거나 자체 에이전트의 시작점으로 활용하세요.

리소스

AgentSkills.io – 공식 사양
Claude Skills – Anthropic의 스킬 예시
Open Agent Skills – 커뮤니티 스킬 라이브러리
Working Implementation – 이 튜토리얼의 전체 코드
WTF is Frontmatter? – 마크다운 파일의 프런트‑머터/메타데이터 이해
Anatomy of a Prompt – 구조화된 접근법을 활용한 효과적인 AI 프롬프트 작성 가이드
OpenAI Function Calling – 공식 OpenAI 도구 문서