AgentScope SKILL.md 구조 및 활용 방법 (로컬 + Nacos 통합)

1. 핵심 개념 정리 ==========

1.1 SKILL.md 정의

LLM에게 제공되는 전문가 행동 매뉴얼

• 작업 흐름(SOP)을 기술하는 문서
• 실행 가능한 함수가 아님
• "사용자 요청 → 사고 과정 → 실행 단계"를 지도함

1.2 Skill 함수 정의

• 실제 실행 가능한 도구/함수
• 계산, 네트워크 요청 등 동작 수행 가능

1.3 관계 구조

2. 표준 형식 규격 =====================

---
# 메타데이터(시작 시 로딩)
name: "PDF 처리 전문가"
description: "PDF 텍스트 추출/병합/변환 작업 시 사용"
tags: ["pdf", "문서처리"]
version: "1.0.0"
---

# 기능 정의(요청 시 로딩)
## 적용 범위
- PDF 텍스트/테이블 추출
- 다중 파일 병합
- PDF to Markdown 변환

## 실행 순서
1. 파일 경로 및 페이지 확인
2. 관련 도구 호출
3. 결과 반환

## 예시
사용자: demo.pdf 1~3페이지 추출
실행: extract_pdf 도구 사용

3. 로컬 기반 SKILL.md 처리 =========================

3.1 디렉토리 구조

프로젝트/
 ├ 스킬/
 │  ├ pdf_skill/
 │  │  └ SKILL.md
 │  └ code_skill/
 │     └ SKILL.md
 └ 메인.py

3.2 로딩 코드 (표준형)

from agentscope.agents import UserAgent, ReActAgent
from agentscope.skill import SkillLoader

# 로컬 SKILL.md 로드
local_skill = SkillLoader.load_from_path("./skills/pdf_skill/SKILL.md")

# 전체 디렉토리 로드
all_skills = SkillLoader.load_from_directory("./skills")

print(f"로드된 스킬 수: {len(all_skills)}")
for skill in all_skills:
    print(f"- {skill.name}: {skill.description}")

# Agent 생성
agent = ReActAgent(
    name="보조자",
    skills=all_skills,
    debug_mode=True
)

# 테스트 실행
agent("PDF 파일 1~3페이지 추출 요청")

4. Nacos 기반 스킬 관리 ==============================

4.1 저장 방식

Nacos에서 지원하는 두 가지 저장 옵션:

A. 단순 구성 정보 저장

• DataID: pdf_skill.SKILL.md
• 그룹: SKILL_GROUP
• 내용: SKILL.md 전체 텍스트 복사

B. 공식 추천 방식

• Nacos 콘솔 → AI → Skill 관리
• Skill 생성 → SKILL.md 업로드

4.2 로드 코드

from agentscope.extension.nacos import NacosSkillRepository

# Nacos 연결 설정
nacos_client = NacosSkillRepository(
    서버주소="127.0.0.1:8848",
    네임스페이스="공개",
    그룹="SKILL_GROUP",
    아이디="nacos",
    비밀번호="nacos"
)

# 스킬 로드
single_skill = nacos_client.get_skill("pdf_skill")
all_skills = nacos_client.list_skills()

# Agent 생성
agent = ReActAgent(
    name="처리자",
    skills=all_skills,
    verbose=True
)

# 테스트
agent("PDF 파일 처리 요청")

5. 로컬+Nacos 병합 활용 ===============================

from agentscope.skill import merge_skills

# 로컬 스킬 로드
local_skills = SkillLoader.load_from_path("./skills")

# Nacos 스킬 로드
remote_skills = NacosSkillRepository(...).list_skills()

# 병합 처리
combined_skills = merge_skills(local_skills, remote_skills)

# Agent 생성
agent = ReActAgent(skills=combined_skills)

6. 핵심 기능: 단계적 로딩 =============================

6.1 초기 로딩(시작 시)

• 이름, 설명만 로드
• 토큰 소비량 최소화

6.2 매칭 시 로딩(질의 시)

• 전체 SKILL.md 본문 로드

6.3 실행 시 로딩

• 외부 파일/스크립트/리소스 로드

7. 차이점 비교표 ===========

8. 요약 (3가지 핵심) ==============

9. SKILL.md는 LLM에게 전달되는 실행 안내서이며 실제 실행은 수행하지 않음

10. Skill 함수는 실제로 작업을 수행하는 실행 가능한 도구

11. Agent는 SKILL.md를 기반으로 사고 후 Skill 함수를 호출하여 작업을 완료함