에이전트 기술 작성 및 구현 방법

소개

에이전트 스킬은 대형 언어 모델(LLM)이 관련될 때 일관되고 반복 가능한 방식으로 전문 작업을 수행하기 위해 불러올 수 있는 지침, 스크립트 및 리소스의 폴더입니다. 이러한 개념은 2025년 Claude에 의해 오픈 프레임워크로 소개되었으며, 이후 다른 조직과 에이전트 개발자들에 의해 점점 더 많이 채택되고 있습니다.

과거에는 LLM에게 작업을 부여할 때 LLM 워크플로를 위해 수동으로 컨텍스트를 제공해야 했습니다. 그러나 에이전트 스킬을 사용하면 리소스와 추가 지침을 LLM이 필요하다고 판단할 때만 접근할 수 있는 폴더로 분리할 수 있습니다.

예를 들어, LLM이 파워포인트 프레젠테이션을 생성하도록 하고 싶다면 매번 스타일 가이드, 그래픽 및 조직 템플릿을 수동으로 프롬프트에 추가하는 대신, 이를 Skill로 폴더에 추가해 두면 LLM이 프레젠테이션을 생성할 때마다 해당 리소스를 독립적으로 찾아 사용할 수 있습니다. 많은 수의 Skill을 추가할 수 있으며, LLM은 이를 도구처럼 참조할 수 있습니다.

이 튜토리얼에서는 PDF 파서를 위한 에이전트 스킬을 생성하며, 선택적으로 다른 참조 문서와 자산을 위한 폴더도 생성할 수 있습니다.

핵심 내용

에이전트 스킬은 SKILL.md 파일을 포함한 폴더로, 메타데이터와 지침이 들어 있어 LLM이 모든 프롬프트에 모든 컨텍스트를 요구하지 않고도 필요한 경우에만 전문 기능을 로드할 수 있도록 합니다. Claude는 2025년에 이 프레임워크를 도입했으며, 자원을 독립적으로 접근 가능한 모듈로 분리함으로써 보다 효율적인 에이전트 워크플로우를 가능하게 합니다.
에이전트가 스킬을 사용하려면 스킬을 발견하고, 불러오고, 실행할 수 있어야 합니다. 이는 사용자의 요청에 가장 적합한 스킬을 찾기 위해 사용 가능한 스킬을 파악하고 분석하는 과정을 포함합니다.
에이전트 스킬은 에이전트에 기능을 추가하는 중요한 기준이 될 가능성이 높습니다. 이는 에이전트에게 많은 맞춤화와 동적 잠재력을 제공합니다.

1단계 — 스킬 만들기

기술(skill)을 구현하는 가장 간단한 방법은 SKILL.md 파일이 포함된 폴더를 만드는 것입니다. 이 마크다운 파일에는 특정 작업을 수행하는 방법을 에이전트에게 설명하는 메타데이터와 지침이 포함되어 있습니다. 또한 폴더에 추가 자료, 템플릿, 스크립트, 참고 자료를 포함할 수도 있습니다.

Folder Structureyour-skill-name/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

스킬 폴더 이름은 스킬의 이름이 됩니다. 그런 다음 폴더 안에는 SKILL.md 파일과 포함하고 싶은 추가 자료가 들어 있습니다.

먼저, skills라는 폴더를 만드세요. 이 폴더에는 당신이 작성하는 모든 스킬이 들어갑니다. skills 폴더 안에 pdf-parsing이라는 폴더를 만드세요. 이 폴더에는 pdf-parsing 스킬과 관련된 모든 파일과 문서가 들어갑니다. pdf-parsing 폴더 안에 다음 내용을 담은 SKILL.md 파일을 만드세요.

---
name: pdf-processing
description: Extracts text from PDF files using PyPDF2.
---

# PDF Processing Skill

## When to use this skill
Use this skill when a user needs to extract text from a PDF file.

## How to Use this Skill
This skill provides the `extract_text()` function from the `parse_pdf.py` script. Import it into your agent script:

python
from skills.pdf_parsing.parse_pdf import extract_text

result = extract_text(
    file_path="/path/to/document.pdf",
    pages="all"  # or "1-3" or "1,2,3"
)

### Parameters
- `file_path` (str): Path to the PDF file
- `pages` (str): Pages to extract - "all", "1-3" (range), or "1,2,3" (specific pages)

### Returns
JSON object with:
- `success` (bool): Whether extraction succeeded
- `file_path` (str): Path to the processed file
- `total_pages` (int): Total pages in PDF
- `extracted_pages` (int): Number of pages extracted
- `pages` (list): Array of {page: number, text: string} objects

Alternatively, you can call the script directly from the command line:
command
python skills/pdf-parsing/parse_pdf.py extract_text --file_path /path/to/file.pdf --pages all

name과 description은 에이전트가 설명을 파싱할 수 있도록 마크다운 파일의 최상단 frontmatter에 반드시 필요합니다. Frontmatter는 마크다운 파일 상단에 위치하며, 메타데이터를 포함하는 섹션입니다. 에이전트는 각 스킬의 이 필드를 사용하여 요청에 가장 적합한 스킬을 식별합니다. frontmatter에는 라이선스, 호환성, 메타데이터, 허용 도구 등 선택적 필드를 포함할 수 있습니다. 맞춤형 에이전트 워크플로우의 경우 원하는 필드를 자유롭게 추가할 수 있습니다. 에이전트는 사용자의 요청과 함께 각 스킬의 frontmatter를 포함하여 어떤 스킬이 적절한지 식별합니다.

마크다운 본문의 나머지 부분에 대해서는 지침에 대한 특별한 요구 사항이 없습니다. 프롬프트 최적화 모범 사례를 따르고 LLM이 따르기 쉽도록 지침을 명확하게 유지하도록 해보세요. 나머지 본문은 에이전트가 사용할 스킬을 결정한 후에 쿼리될 예정입니다.

그런 다음 이 무료 PDF 파서 스크립트를 사용하거나 parse_pdf.py 파일을 만들고 PDF 파싱 기능이 있는 extract_text() 함수를 만드세요. 새로운 스킬을 추가할 때마다 필요한 모든 종속성을 설치해야 합니다. 연결된 스크립트를 사용할 경우 PyPDF2가 필요합니다.

pip3 install PyPDF2

이 명령은 PyPDF2 Python 패키지를 설치합니다.

2단계 — 기술 통합

에이전트가 기술(Skills)을 사용하려면 특정 단계를 따라야 합니다. 에이전트는 SKILL.md 파일이 있는 모든 디렉토리에서 기술을 발견하고, 각 마크다운 파일의 메타데이터(이름 및 설명)를 시작 시 로드하며, 사용자의 요청과 관련된 기술을 매칭하고, 마크다운 파일에서 전체 지침을 로드하여 기술을 활성화한 후, 참조된 파일을 로드하고 지침을 따르며 필요에 따라 코드를 실행하여 기술을 수행해야 합니다.

Claude Code나 Codex와 같은 일부 에이전트는 스킬을 워크플로우에 자동으로 통합하며, 점점 더 많은 에이전트 제공업체가 이러한 단계를 에이전트의 워크플로우에 통합하고 있습니다.

자신의 커스텀 에이전트에 스킬을 통합하고 싶다면, 주로 두 가지 방법이 있습니다. 파일 시스템 기반 패턴을 사용하거나 도구 기반 패턴을 사용할 수 있습니다. 파일 시스템 기반 패턴에서는 LLM 워크플로우가 컴퓨터 환경 내에서 작동하며, cat /path/to/my-skill/skill.md와 같이 실행되는 셸 명령어를 출력합니다. 반면, 도구 기반 접근법은 스킬을 LLM이 호출할 수 있는 도구로 변환하는 효과를 가집니다.

이 튜토리얼에서는 처음부터 기능이 있는 에이전트를 만드는 것은 범위를 벗어나지만, 이 에이전트 스크립트를 사용할 수 있습니다. 이 스크립트는 Linux-Console.net Gradient AI 플랫폼의 Serverless Inference 도구를 통해 Llama 3.3 70B를 사용합니다. Linux-Console.net Gradient AI 플랫폼에서 Serverless Inference를 사용하려면 모델 액세스 키가 필요합니다. 스크립트의 main() 함수에 모델 액세스 키를 추가하세요.

스크립트를 skills 폴더와 동일한 폴더에 넣은 후, 스크립트를 실행하세요.

python3 agent_example.py

열리는 텍스트 상자에 다음을 입력하세요: Please parse the text out of the PDF at /path/to/your/document.pdf. 그러면 PDF에서 추출된 텍스트가 출력되는 것을 확인할 수 있습니다.

============================================================
SIMPLE TOOL-BASED SKILLS EXAMPLE
============================================================

✅ Found 1 skills:
   - pdf-processing: Extracts text from PDF files using PyPDF2.

============================================================
CHAT (type 'quit' to exit)
============================================================

You: Please extract the text from: /Desktop/document.pdf

[Turn 1]
💭 LLM: {"function_call": {"name": "activate_skill", "arguments": {"skill_name": "pdf-processing"}}}
..........
The cost of an RV is 30,000

에이전트가 성공적으로 스킬을 찾고, 메타데이터를 추출하고, 스킬을 실행하며, PDF에서 텍스트를 반환했습니다.

3단계 — 기능 및 스킬 추가

LLM이 접근할 수 있도록 하고 싶은 다른 스크립트나 폴더를 추가하세요. 그런 다음 각 폴더와 스크립트의 기능에 대한 지침과 설명을 SKILL.md 파일에 추가하세요. 예를 들어, PDF를 생성하거나 편집할 수 있는 스크립트를 추가할 수 있습니다. 이러한 추가 파일은 관련된 특정 기능의 폴더에 반드시 추가해야 합니다.

원하는 만큼 많은 스킬을 추가할 수 있지만, 각 스킬 폴더에는 에이전트가 인식할 수 있도록 폴더 내에 SKILL.md 파일이 반드시 있어야 합니다. 또한, 에이전트가 많은 스킬의 메타데이터와 사용자의 의도를 매칭하는 것은 어려울 수 있으므로, 스킬의 수가 증가함에 따라 추가 검색 기능을 추가하거나 벡터 임베딩을 사용하여 사용자의 요청을 올바른 스킬과 매칭해야 할 수도 있습니다.

자주 묻는 질문

스킬들이 서로 소통하거나 다른 스킬을 호출할 수 있나요? 그리고 스킬 체이닝은 어떻게 구현할 수 있나요?

네, 스킬은 다른 스킬을 호출할 수 있습니다. 에이전트는 여러 스킬이 필요할 수 있는 상황을 인식하고 이를 연결할 수 있어야 합니다. 스킬 지침에서도 다른 스킬을 참조하는 것이 가능합니다.

외부 서비스에 접근해야 할 때, 스킬 내에서 인증 및 API 키를 어떻게 처리하나요?

스킬 파일에 자격 증명을 하드코딩하지 마세요. 환경 변수나 안전한 비밀 관리자를 사용하세요.

많은 스킬을 시작 시 로딩할 때 성능에 어떤 영향이 있으며, 지연 로딩 전략이 가능한가요?

수백 개의 스킬에 대한 메타데이터를 로드하는 것은 느릴 수 있습니다. 로드된 스킬을 캐싱하고 인덱싱을 사용하여 많은 스킬을 빠르게 검색하는 것을 고려하세요. 스킬 전체가 필요할 때까지 메타데이터만 로드하도록 검색 단계와 활성화 단계를 분리할 수 있습니다.

스킬을 어떻게 테스트하고 디버깅하나요?

기능을 통합하기 전에 개별 기능을 반드시 테스트하고, 어떤 기능이 선택되고 있는지와 그 이유를 확인할 수 있도록 기능에 자세한 로깅을 추가하세요.

결론

에이전트 스킬은 LLM 에이전트의 기능을 표준화하는 훌륭한 방법입니다. 사용자가 구조화된 방식으로 에이전트의 기능을 추가하고 개선할 수 있게 해줍니다. 이를 구현하는 방법은 특정 에이전트 워크플로우에 따라 달라지지만, 스킬을 바로 사용할 수 있는 에이전트 서비스의 수는 점점 증가하고 있으며, Claude Code, Codex, VSCode 등 일부 에이전트 제공업체가 이 표준을 채택하고 있습니다.

다음으로, 더 많은 스킬을 추가하고 프로젝트에 적합한 추가 기능으로 맞춤 설정하세요. 그런 다음, 벡터 임베딩이나 기타 검색 기능을 통해 에이전트 워크플로우의 스킬 매칭 기능을 향상시키세요.

Linux-Console.net 커뮤니티와 함께 학습해 주셔서 감사합니다.