블로그 | 모하지?

Spring AI Agentic Patterns (Part 1): Agent Skills — 스프링 AI에서 스킬을 설계하는 법

Spring AI로 에이전트 애플리케이션을 만들다 보면 금방 부딪히는 문제가 하나 있다.
에이전트가 해야 할 일을 어디까지 프롬프트에 적고, 어디부터 구조화된 자산으로 분리할 것인가 하는 문제다.

작은 실험에서는 시스템 프롬프트에 지시문을 길게 적어두는 방식도 통한다. 하지만 기능이 늘어나고, 작업 종류가 많아지고, 모델을 바꿔가며 써야 하는 상황이 오면 프롬프트만으로는 유지보수가 어려워진다.

Spring 팀이 소개한 Agent Skills는 바로 이 지점을 해결하려는 접근이다. 이 글에서는 Spring 공식 블로그 글 Spring AI Agentic Patterns (Part 1): Agent Skills의 핵심을 한국어로 정리하고, 실제로 Spring AI 애플리케이션 개발에 이 개념을 어떻게 가져가면 좋은지까지 같이 풀어보겠다.

Agent Skills가 뭐길래 중요한가

Agent Skills는 간단히 말하면 에이전트가 필요할 때 꺼내 읽는 작업 지침 패키지다.

기본 구조는 단순하다.

SKILL.md : 필수. 메타데이터와 작업 지침이 들어감
scripts/ : 필요하면 실행용 스크립트 포함
references/ : 참고 문서 포함
assets/ : 템플릿, 리소스 파일 포함

즉 프롬프트 안에 모든 지식을 하드코딩하는 대신, 능력을 폴더 단위로 분리해서 필요할 때 로드하는 방식이다.

이 구조가 중요한 이유는 두 가지다.

프롬프트를 짧게 유지할 수 있다
에이전트는 시작할 때 스킬의 이름과 설명만 읽고, 실제 작업이 필요할 때만 전문을 불러온다.
스킬을 재사용하고 버전 관리할 수 있다
프로젝트별로 복붙한 프롬프트 조각을 관리하는 대신, 스킬 자체를 코드와 함께 관리할 수 있다.

Spring AI에서 이게 왜 의미가 있나

이 글에서 강조하는 포인트는 Spring AI의 Agent Skills 구현이 특정 LLM에 묶여 있지 않다는 점이다.

즉 스킬을 한 번 정의해두면,

OpenAI
Anthropic
Google Gemini
기타 Spring AI가 지원하는 모델

위에서 같은 개념으로 재사용할 수 있다.

이건 꽤 큰 장점이다. 많은 에이전트 프레임워크가 모델 공급자나 특정 플랫폼 구현에 강하게 묶이는 반면, Spring AI 쪽 구현은 도구 기반 접근으로 설계돼 있어서 상대적으로 이식성이 높다.

한마디로 정리하면, Agent Skills는 “특정 모델용 비법 프롬프트”가 아니라, 애플리케이션 안에서 재사용 가능한 작업 단위에 가깝다.

동작 방식은 생각보다 단순하다

Spring AI 쪽 Agent Skills는 대략 세 단계로 작동한다.

1) Discovery

시작할 때 각 스킬의 name, description 정도만 읽어서 레지스트리를 만든다.

2) Semantic Matching

사용자 요청이 들어오면, 모델이 “이 요청엔 어떤 스킬이 맞는지”를 판단한다.

3) Execution

필요한 스킬이 결정되면 그때 SKILL.md 전체를 읽고, 필요하면 스크립트나 참고 문서도 추가로 연다.

이 구조가 좋은 이유는 progressive disclosure 덕분이다. 모든 스킬을 처음부터 다 문맥에 넣는 게 아니라, 필요한 것만 단계적으로 꺼낸다.

즉 스킬 수가 많아져도 컨텍스트를 비교적 얇게 유지할 수 있다.

SkillsTool, ShellTools, FileSystemTools의 역할

원문 글에서는 Spring AI 구현에서 핵심 도구 셋으로 다음을 소개한다.

SkillsTool : 어떤 스킬을 로드할지 결정하고 불러오는 중심 도구
FileSystemTools : 참고 파일을 읽는 도구
ShellTools : 스크립트를 실행하는 도구

여기서 중요한 건, Spring AI가 스킬을 “마법처럼 자동 실행되는 기능”으로 취급하지 않는다는 점이다.

실제로는 이런 흐름이다.

모델이 스킬 사용을 결정한다.
스킬 본문을 읽는다.
필요하면 파일을 읽는다.
필요하면 스크립트를 실행한다.

즉 모델 추론 + 도구 호출 + 파일 접근이 명시적으로 연결된다. 이 구조는 디버깅과 통제가 쉽다는 장점이 있다.

참조 문서와 스크립트를 함께 넣는 방식이 강력하다

원문 글에서 꽤 실용적으로 보이는 부분은, 스킬이 단순 지침문 하나로 끝나지 않고 참고 문서와 스크립트를 함께 번들링할 수 있다는 점이다.

예를 들어,

특정 개념을 설명해야 할 때는 research_methodology.md를 읽고
유튜브 링크가 오면 get_youtube_transcript.py를 실행해 전사를 가져오고
그 결과를 다시 모델이 해석하는 식이다.

이 방식의 장점은 분명하다.

코드 본문 자체를 프롬프트에 넣을 필요가 없다.
모델은 결과물만 받으면 된다.
스킬은 점점 더 복합적인 워크플로우를 담을 수 있다.

즉 Agent Skills는 “정적인 설명 문서”가 아니라, 실행 가능한 작업 패키지로 확장될 수 있다.

Spring AI에서 실제로 어떻게 시작하나

글의 Getting Started 섹션은 꽤 직관적이다.

핵심은:

spring-ai-agent-utils 의존성을 추가하고
SkillsTool, FileSystemTools, ShellTools를 ChatClient에 연결하고
.claude/skills/... 아래 스킬 폴더를 만들면 된다.

즉 기존 Spring AI 애플리케이션 구조를 완전히 갈아엎는 방식이 아니다.
기존 ChatClient 기반 앱에 도구 몇 개를 추가해서 스킬 개념을 얹는 접근이다.

이게 실무적으로 중요한 이유는, 이미 돌아가는 Spring AI 앱에 점진적으로 Agent Skills를 붙일 수 있기 때문이다.

이 접근이 특히 잘 맞는 상황

다음과 같은 경우라면 Agent Skills 접근이 특히 잘 맞는다.

1) 업무 지침이 자주 바뀌는 경우

예를 들어 리뷰 기준, 문서 작성 규칙, 운영 체크리스트 같은 건 코드보다 문서 자산으로 분리하는 게 낫다.

2) 도메인별 전문 지식을 나누고 싶은 경우

예를 들어

코드 리뷰 스킬
장애 대응 스킬
문서 요약 스킬
배포 점검 스킬 처럼 나눌 수 있다.

3) 모델 공급자를 자주 바꿔보는 경우

스킬 자체를 특정 모델에 묶지 않기 때문에, 실험이 훨씬 수월해진다.

4) 프롬프트를 길게 유지하고 싶지 않은 경우

지침을 프롬프트가 아니라 스킬 자산으로 옮기면 기본 컨텍스트가 깔끔해진다.

한계도 분명하다

원문에서도 제한사항을 숨기지 않는다. 이건 오히려 장점이다.

1) 스크립트 실행은 샌드박스가 아니다

ShellTools로 실행되는 스크립트는 로컬 머신에서 직접 돈다.
즉 안전하지 않은 스크립트를 넣으면 파일시스템/네트워크 접근 문제가 생길 수 있다.

2) 기본적으로 human-in-the-loop가 없다

승인 단계 없이 스킬과 스크립트가 바로 실행될 수 있다. 민감한 작업에서는 별도 승인 플로우가 필요하다.

3) 스킬 버전 관리가 내장되어 있지 않다

스킬 파일을 바꾸면 그 즉시 동작이 달라진다. 운영 환경에서는 디렉토리 버전 분리 같은 전략이 필요하다.

즉 Agent Skills는 강력하지만, 그대로 운영 환경에 던져 넣기보다 권한/승인/버전 전략을 같이 설계해야 한다.

Anthropic의 네이티브 Skills와 뭐가 다른가

이 글은 또 하나 중요한 비교를 한다. 바로 Anthropic의 네이티브 Skills와의 차이다.

차이를 아주 짧게 정리하면:

Anthropic Skills: Anthropic의 클라우드 샌드박스 안에서 실행
Generic Agent Skills: 내 환경에서 실행

이 차이 때문에 선택 기준도 달라진다.

Anthropic 네이티브 Skills가 맞는 경우

안전한 샌드박스가 중요할 때
문서 생성 기능 같은 내장 기능을 활용하고 싶을 때

Generic Agent Skills가 맞는 경우

모델 이식성이 중요할 때
로컬 리소스 접근이 필요할 때
애플리케이션 코드와 함께 배포하고 싶을 때

그리고 둘은 상호 배타적이기보다, 상황에 따라 같이 쓸 수도 있다는 점도 흥미롭다.

이 글에서 실제로 얻어야 할 핵심

이 글을 읽고 가져가야 할 핵심은 단순히 “Spring AI에도 스킬 기능이 있다”가 아니다.

더 중요한 포인트는 이거다.

에이전트의 능력을 프롬프트에 몰아넣지 말고, 스킬이라는 재사용 가능한 단위로 분리하라.

이 한 가지 관점만 잡아도 설계가 많이 달라진다.

프롬프트는 얇아지고
작업 지침은 버전 관리되고
스크립트는 필요할 때만 실행되고
모델은 바꿔도 자산은 유지된다.

이건 단순한 편의 기능이 아니라, 에이전트 애플리케이션을 운영 가능한 구조로 만드는 방향에 가깝다.

마무리

Spring AI의 Agent Skills는 “AI가 더 똑똑해지는 기능”이라기보다, 에이전트가 해야 할 일을 더 잘 조직하는 방식에 가깝다.

그래서 이 글은 단순 기능 소개를 넘어, 앞으로 이어질 Agentic Patterns 시리즈의 출발점 역할을 한다.

시리즈를 따라가면서 보면 대략 이런 흐름이 된다.

Part 1: Agent Skills
Part 2: AskUserQuestionTool
Part 3: TodoWriteTool
Part 4: Subagent Orchestration
Part 5: A2A Integration

즉 “에이전트를 어떻게 부품화하고, 상호작용시키고, 확장할 것인가”가 시리즈의 큰 주제다.

Spring AI Agentic Patterns (Part 1): Agent Skills 한국어 정리