Upstage AI Ambassador 2기 활동의 일환으로 제작한 프로젝트입니다.
들어가며 — 이전 프로젝트에서 시작된 아이디어
요즘 주식에 관심을 가지게 되면서 매일 반복하는 루틴이 생겼다.
관심 종목 주가 확인 → 관련 뉴스 탐색 → "왜 올랐지? 왜 떨어졌지?" 원인 파악.
이 과정이 생각보다 꽤 시간을 잡아먹는다. 종목이 여러 개면 더 말할 것도 없고.
그래서 지난번에 Upstage Solar Pro3 + n8n을 활용해 주가 변동 분석을 자동화하는 워크플로우를 먼저 구현했었다.
매일 오후 4시 자동 실행
→ 관심 종목 불러오기
→ 종목별 뉴스 수집
→ AI 기반 주가 변동 원인 분석
→ 최종 리포트 생성
→ 이메일 자동 전송
n8n으로 자동화 파이프라인을 구성하고, Upstage Solar가 AI 분석을 담당하는 구조였다.
이번엔 그 연장선에서 더 고도화된 버전을 만들었다. 단순히 뉴스를 요약하는 걸 넘어서, 기술적 분석(이동평균선, 볼린저밴드 등) + 재무제표 분석까지 결합해 실제 투자 판단에 쓸 수 있는 수준으로 올리고 싶었다.
그냥 자동화 스크립트를 짜도 되지만, 이번엔 Claude Code의 Agent Skill이라는 개념을 적극 활용해보기로 했다. 거기에 Upstage의 Solar Pro3 LLM과 Document AI API를 결합하면, 단순 자동화를 넘어서 진짜 "AI 애널리스트"처럼 작동하는 시스템을 만들 수 있겠다 싶었다.
이 글에서는 Agent Skill이 무엇인지부터, 실제 주식 브리핑 스킬을 설계하고 점진적으로 고도화해나간 전 과정을 담아보도록 하겠다.
1. Agent Skill
Agent Skill은 AI 코딩 에이전트에게 특정 작업 방법을 지시하는 구조화된 마크다운 문서다.
핵심은 SKILL.md 파일 하나다. 이 파일을 ~/.claude/skills/ 폴더에 넣어두면, Claude Code가 사용자의 요청에 따라 해당 Skill을 알아서 인식하고 실행한다.
my-skill/
├── SKILL.md ← 에이전트가 읽는 지시서 (필수)
├── scripts/ ← 실행할 파이썬 스크립트
└── data/ ← 설정 파일, 캐시
Skill은 단순한 스크립트가 아니다. 에이전트한테 "이럴 때는 이렇게 해"라고 알려주는 레시피다.
SKILL.md 구조
---
name: stock-briefing
description: 투자 성향(공격형/안정형)에 맞는 일일 주식 브리핑을 제공합니다.
"오늘 주식 어때", "주가 현황", "매수/매도 판단" 등의 요청에 사용합니다.
allowed-tools: Bash(python *), Read
---
# 주식 브리핑 스킬
## 실행 단계
1. UPSTAGE_API_KEY 환경변수 확인
2. 투자 프로필(profile.json) 존재 여부 확인
3. 관심 종목별 주가·기술적 지표·재무·뉴스 수집
4. Solar Pro3 AI가 종합 분석 후 시그널 출력
## Gotchas
- KOSPI 종목은 반드시 .KS suffix 필요 (005930 → 005930.KS)
- yfinance 재무 데이터 없는 소형주는 기술적 분석만 진행
- 이격도 108 이상은 매도권이므로 공격형도 관망 처리
여기서 description이 제일 중요하다. 에이전트가 Skill을 쓸지 말지를 이 필드만 보고 결정하기 때문이다. Anthropic 공식 가이드에 따르면 현재 모델은 Skill을 과소 트리거하는 경향이 있어서, 사용자가 실제로 쓸 만한 말투를 최대한 다 넣어줘야 한다.
2. Upstage API를 에이전트가 직접 읽게 하기
스크립트를 직접 짤 필요 없이, Upstage가 제공하는 에이전트 전용 문서 URL 하나만 Claude Code에 던져주면 알아서 코드를 작성해준다.
이 URL 참고해서 Upstage API 활용한 주식 브리핑 스크립트 작성해줘:
https://console.upstage.ai/api/docs/for-agents/raw
만들 것:
- 투자 성향 설정 후 프로필 저장
- 관심 종목 주가·뉴스 매일 수집
- Solar Pro3로 매수/매도/주목 시그널 생성
- SKILL.md도 같이 만들어줘
이 URL에 접근하면 에이전트가 Upstage의 주요 API를 모두 파악할 수 있다. 나는 크게 3가지 API를 활용해보았다.
| Chat (solar-pro3) | 기술적·재무·뉴스 종합 분석 및 시그널 생성 |
| Document Parse | 재무 PDF 리포트 분석 (향후 확장) |
| Information Extraction | 뉴스 핵심 정보 구조화 |
에이전트는 이 문서를 읽고 인증 방식(Bearer 토큰), 엔드포인트, 모델명, 파라미터를 모두 파악한 뒤 코드를 짜준다. 코드 한 줄 직접 쓰지 않아도 동작하는 스크립트가 나온다.
3. 설계 단계: 만들기 전에 먼저 생각하기
코드보다 설계가 먼저다. Skill을 만들기 전에 다음 질문을 먼저 정리했다.
Q1. 이 Skill은 무엇을 하는가?
투자 성향(공격형/안정형)에 맞춰 관심 종목의 주가·기술적 지표·재무 상태·뉴스를 분석하고, Solar Pro3가 매수/매도/주목 시그널과 근거를 생성한다.
Q2. 사용자가 어떤 말로 부를까?
"오늘 주식 어때", "삼성전자 지금 사도 돼?", "주가 브리핑해줘"
→ 이것들이 description 필드의 트리거 키워드가 된다.
Q3. 에이전트(LLM)가 할 일 vs 코드(스크립트)가 할 일
작업 담당 이유
| 주가 데이터 수집 | 스크립트 (yfinance) | LLM이 실시간 데이터를 직접 읽을 수 없음 |
| 기술적 지표 계산 | 스크립트 (수식) | 수치 계산은 코드가 정확 |
| 재무제표 수집·분석 | 스크립트 (yfinance) | 결정적 작업 |
| 뉴스 수집 | 스크립트 (Google News RSS) | 반복 자동화 |
| 종합 분석 + 시그널 생성 | Solar Pro3 | 판단·맥락·자연어 생성 |
| 사용자 대화·에러 안내 | 에이전트 (SKILL.md) | 대화는 에이전트 역할 |
Q4. 자주 발생할 에러는?
종목코드 형식 오류 (035720.KQ는 카카오, 005930.KS가 삼성전자), API 키 미설정, 재무 데이터 없는 소형주 등
→ 이게 SKILL.md의 Gotchas 섹션에 들어간다.
4. 실제 구현 흐름
Step 1. 폴더 생성
mkdir -p ~/.claude/skills/stock-briefing/scripts
Step 2. Claude Code에서 스크립트 자동 생성
위에서 소개한 Upstage 문서 URL을 Claude Code에 던지면 utils.py, setup_profile.py, daily_briefing.py, alert_check.py가 자동으로 생성된다.
Step 3. API 키 등록
echo 'export UPSTAGE_API_KEY=발급받은_키' >> ~/.zshrc && source ~/.zshrc
Step 4. 투자 프로필 설정
python3 ~/.claude/skills/stock-briefing/scripts/setup_profile.py
투자 성향: 1) 공격형 2) 안정형 → 1
관심 종목: 삼성전자, NVDA → 입력
급변 기준: 5% → 설정 완료
Step 5. 일일 브리핑 실행
Claude Code 안에서:
/stock-briefing
또는 터미널에서 직접:
python3 ~/.claude/skills/stock-briefing/scripts/daily_briefing.py
5. 고도화 과정
학습 이전에 Claude만의 지식을 가지고 구현된 첫 결과는 다음과 같았다.
조회 중... 삼성전자 (005930.KS)
🔴 219,500원 ▼2.23%
📰 삼성전자, '파업리스크'에 주가 발목 잡히나…투심 위축에 2%대 하락
🤖 Solar Pro 3 AI 분석 생성 중...
시그널: 주목
근거: 파업 리스크로 단기 하락 압력이 있으나,
장기 성장 모멘텀과 AI·반도체 수요 회복 기대감이 유효합니다.
뉴스만 보고 분석하는 단편적인 수준으로 실제 투자 판단에 쓰기에는 턱없이 부족한 결과였다.
그래서 다음 두 가지를 직접 학습시켰다.
1. 기술적 분석 자료 입력
이동평균선(정배열/역배열/골든크로스), 볼린저밴드, 이격도, 캔들 패턴, 지지·저항선 같은 기술적 분석 개념을 정리한 강의 자료를 Claude Code에 직접 넣어주고 반영하도록 했다.
여기서 Anthropic 공식 가이드의 핵심 원칙이 빛을 발한다.
"Claude는 이미 매우 똑똑하다."
당연한 걸 설명하지 말고, 에이전트가 반복적으로 틀리는 패턴만 SKILL.md에 기록하면 된다.
예를 들어 이격도 108이 나왔을 때 공격형도 "관망" 처리해야 하는데, 처음엔 에이전트가 이 부분을 놓쳤다. 발견할 때마다 Gotchas에 추가했고, 브리핑 품질이 점점 올라갔다.
2. 재무제표 분석 자료 입력
- 안정성: 유동비율(100% 이상), 부채비율(200% 이하) 기준
- 수익성: ROE 15% 이상 = 우량 (워렌 버핏 기준)
- 현금흐름: 우량 기업 패턴 — 영업(+), 투자(−), 재무(−)
- 이상신호: 순이익(+)인데 영업현금흐름(−)이면 가짜 이익 가능성
이 내용을 직접 정리해서 스크립트에 반영하도록 했다.
6. 고도화 후 실제 출력 결과
══════════════════════════════════════════════
📈 주식 일일 브리핑 — 2026년 04월 26일
투자 성향 : 공격형 | 급변 기준 : ±5.0%
══════════════════════════════════════════════
━━━ 005930.KS 삼성전자 ━━━━━━━━━━━━━━━━━━━
현재가 🔴 219,500원 ▼2.23%
📊 기술적 분석
이동평균선 정배열
볼린저밴드 중간(76%)
이격도 108.3 → 매도권
지지/저항 지지선 167,000 / 저항선 229,500
거래량 평균 대비 0.8배 (보통)
추세 상승
💰 재무 건전성
유동비율 233% (정상) | 부채비율 31% (정상)
ROE 10.4% (보통) | 영업이익률 13.1%
현금흐름 영업(+) 투자(−) 재무(−) — 우량패턴 ✅
이상신호: ✅ 이상없음
재무 등급: A (우량)
📰 주요 뉴스
• 삼성전자, '파업리스크'에 주가 발목 잡히나
• 삼성전자 총파업 태세에 증권가 촉각
• "반도체 가격상승 압력" 전망
🤖 Solar Pro 3 종합 분석 (기술적 + 재무 + 뉴스)
[005930.KS | 삼성전자]
시그널: 관망
핵심 근거:
1. [기술적] 정배열이지만 이격도 108.3으로 매도권 위치
2. [재무] ROE 10.4%, 재무등급 A로 펀더멘털 탄탄
3. [뉴스] 총파업 태세로 투심 위축, 단기 리스크 상존
파업 리스크 해소 시 강매수 전환 가능성 있음
처음엔 뉴스만 보고 "주목" 한 마디였는데, 기술적 분석 + 재무 등급까지 결합되니 훨씬 구체적인 판단 근거가 나온다.
7. Skill의 핵심 구조 — SKILL.md 최종본
---
name: stock-briefing
description: 투자 성향(공격형/안정형)에 맞는 일일 주식 브리핑을 제공합니다.
yfinance로 OHLCV 데이터와 재무제표를 가져와 기술적 지표 + 재무 건전성을
계산하고, Upstage Solar Pro3가 종합 매매 시그널을 생성합니다.
"주식 브리핑", "오늘 주식 어때", "주가 현황", "매수/매도 판단" 등에 사용합니다.
allowed-tools: Bash(python *), Read
---
슬래시 커맨드로 3가지 모드를 지원한다.
| /stock-briefing setup | 투자 성향 + 관심 종목 설정 |
| /stock-briefing | 일일 브리핑 실행 |
| /stock-briefing alert | 급변(±5%) 종목만 즉시 체크 |
마무리
이번 프로젝트에서 얻은 가장 큰 교훈은
Skill은 처음부터 완성본을 만들려 하지 말고, 에이전트가 틀리는 패턴을 발견할 때마다 SKILL.md에 추가하면서 점진적으로 키워나가는 것이다.
n8n으로 자동화 파이프라인을 만들었을 때는 "뉴스 기반 분석"에 머물렀는데, Agent Skill + Upstage Solar Pro3 조합으로 기술적 분석과 재무 분석까지 결합하니 실제 투자 판단에 쓸 수 있는 수준이 됐다.
다음 단계로는 여러 사람이 쓸 수 있는 웹앱 형태로 전환하거나, 백테스팅으로 시그널 정확도를 검증해보는 것을 계획 중이다.
Upstage /api/docs/for-agents/raw 문서를 활용하면 API 코드를 거의 직접 작성하지 않고도 동작하는 스크립트를 만들 수 있다는 점, Agent Skill을 처음 만들어보려는 분들에게 이 방법을 강력히 추천한다!
[참고 자료]