이 레포가 무엇을 하는 물건인가.
유전체학자에게는 변이 분석 도구가, 구조생물학자에게는 단백질 구조 검색 도구가, 약화학자에게는 분자 조회 도구가 있습니다. Science Skills는 이 전문 도구들을 AI 에이전트가 스스로 골라 쓸 수 있는 "스킬"로 포장한 것입니다. 에이전트는 질문을 받으면 어떤 도구를 꺼낼지 판단하고, 정해진 스크립트로 실제 과학 데이터베이스를 조회한 뒤, 그 결과를 근거로 답합니다.
Science Skills는 과학 연구 작업을 위한 34개의 에이전트 스킬 모음집입니다. 다루는 분야는 유전체학(genomics), 구조생물학(structural biology), 약화학(cheminformatics), 학술 문헌 검색(literature search) 등으로 폭넓습니다. 각 스킬은 에이전트에게 "이런 작업은 이렇게 하라"는 사용 설명서 + 실행 스크립트 + 참고 자료를 한 묶음으로 제공해, 그 분야 전문 작업 능력을 에이전트에 더해 줍니다.
중요한 건 스킬(skill)이라는 단위입니다. 스킬 하나는 폴더 하나이고, 그 안의 SKILL.md라는 파일이 "언제 나를 써야 하는지, 어떻게 쓰는지"를 적어 둔 핵심 설명서입니다. 에이전트는 이 설명을 읽고 스스로 적절한 스킬을 발동합니다. 사람이 일일이 "이제 PubChem을 써"라고 지시하지 않아도 됩니다.
SKILL.md 파일로, 맨 위 YAML 머리말(frontmatter)에 스킬 이름과 "이런 질문이 오면 나를 써라"는 description이 적혀 있습니다. 에이전트는 이 description을 보고 어떤 스킬을 꺼낼지 결정합니다. 나머지 본문에는 실제 작업 절차·주의사항·예제 코드가 담깁니다. (이 글을 만든 도구 자체도 같은 Agent Skills 표준을 씁니다.)트렌딩 이유 · 경쟁 대비 장점.
첫째, 만든 곳이 Google DeepMind입니다. AlphaFold·AlphaGenome을 만든 그 팀이, 자신들의 모델과 30여 개 공공 과학 DB를 에이전트가 쓰도록 직접 패키징했습니다. Google의 에이전트 코딩 IDE인 Antigravity와 함께 공개되며 "과학 워크플로를 에이전트로 자동화한다"는 흐름의 간판 사례가 됐습니다.
둘째, 기술 보고서가 내세우는 두 단어 — 효율(efficiency)과 신뢰(reliability)입니다. LLM은 과학 사실을 그럴듯하게 지어내는(환각) 약점이 있고, 외부 도구를 마구 붙이면 토큰(비용)이 폭증합니다. Science Skills는 이 둘을 정면으로 공략합니다: 필요한 설명만 그때그때 불러오는 점진적 공개(progressive disclosure)로 토큰을 아끼고, 모든 사실 조회를 검증된 스크립트로 강제하는 그라운딩(grounding)으로 환각을 줄입니다.
| 비교 항목 | 그냥 LLM에게 묻기 | Science Skills 방식 |
|---|---|---|
| 사실 정확성 | 기억에 의존 → 그럴듯한 환각 위험 | 실제 DB를 조회해 근거 제시 (그라운딩) |
| 최신성 | 학습 시점에 멈춤 | 호출 시점의 최신 DB 데이터 |
| 토큰/비용 | 긴 도구 명세를 항상 끼고 다님 | 필요한 SKILL.md·참고문서만 그때 로드 |
| 안전성 | API를 무제한 두드려 차단당하기 쉬움 | 스크립트가 속도 제한·재시도·ToS 준수 강제 |
| 전문성 | 분야 절차를 모름 | 변이 분석·스플라이싱 해석 등 전문 워크플로 내장 |
"이 변이가 어느 조직에서 유전자 발현을 바꾸나?" 같은 질문에 LLM이 기억만으로 답하면, 출처 없는 숫자와 가짜 인용이 섞입니다. 과학·의학에서는 한 글자 틀린 사실이 잘못된 판단으로 이어집니다.
예컨대 PubChem 스킬은 규칙에 "확인 가능한 사실은 반드시 DB 쿼리로 검증하라. 내부 지식에만 의존하지 말라"고 못 박습니다. 에이전트가 임의로 답하는 길을 막고, 정해진 스크립트로 실제 데이터를 가져오게 만드는 것이 신뢰성의 출발점입니다.
언어·실행 환경·공용 인프라를 한눈에.
의외로 코드는 Python 100%이고, 화려한 프레임워크가 없습니다. 이 레포의 본질은 "프로그램"이 아니라 에이전트에게 줄 지식과 도구의 묶음이기 때문입니다. 그래서 스택의 주인공은 라이브러리가 아니라 실행 규율 — 어떻게 깨끗하게 실행하고(uv), 어떻게 점잖게 API를 두드리고(공용 HTTP 클라이언트), 어떻게 토큰을 아끼느냐(SKILL.md 구조)입니다.
| 레이어 | 기술 | 역할 |
|---|---|---|
| 스킬 형식 | Agent Skills 표준 (SKILL.md + YAML) | 에이전트가 읽는 사용 설명서. description으로 발동 판단. |
| 배포/설치 | skills.sh · npx skills add · plugin.json | 한 줄 설치. Antigravity의 "Science" 플러그인으로도 제공. |
| 실행 환경 | uv (Python 패키지 매니저) | 스킬별 의존성을 격리 설치·실행. uv run로만 구동. |
| 공용 인프라 | scienceskillscommon · http_client.py | 모든 스킬이 공유하는 HTTP 클라이언트(속도 제한·재시도). |
| HTTP 전송 | urllib (파이썬 표준 라이브러리) | 외부 의존성 0. requests조차 안 씀 — 가볍고 깨지지 않게. |
| 분석 도구 | pandas · numpy · matplotlib · AlphaGenome SDK · PyMOL | 변이 점수 표 처리·시각화·구조 렌더(스킬별 선택 설치). |
| 의존성 선언 | 스킬마다 pyproject.toml | 그 스킬이 필요로 하는 패키지만 명시 → uv가 격리 설치. |
| 데이터 출처 | AlphaGenome·UniProt·PDB·PubChem·PubMed 등 30+ | 코드가 아니라 "원격 권위 출처"가 진짜 데이터 계층. |
uv run 스크립트.py로만 실행하라고 규칙으로 정해 뒀습니다. 그러면 uv가 그 스킬 전용 가상환경을 자동으로 만들어 필요한 패키지(pandas 등)를 격리 설치합니다. 첫 실행은 ~10초, 이후엔 캐시로 즉시. "스킬마다 깨끗한 1회용 실험실을 따로 차려준다"는 비유가 맞습니다.references/·docs/ 문서를 펼쳐 읽습니다. 두꺼운 매뉴얼을 통째로 외우는 대신, 목차만 알아두고 필요한 장만 펴 보는 방식입니다.질문 한 개가 답이 되기까지, 무엇이 어떻게 흐르는가.
Science Skills에는 중앙 서버나 거대한 런타임이 없습니다. 구조는 얇은 계층 네 개로 단순합니다 — ① 에이전트가 어떤 스킬을 쓸지 고르고 → ② 그 스킬의 SKILL.md를 읽고 → ③ 정해진 스크립트를 uv run으로 돌리고 → ④ 스크립트가 공용 HTTP 클라이언트로 외부 DB를 점잖게 두드립니다.
구조가 한눈에 안 들어와도 괜찮습니다. 가장 흔한 동작 하나 — "이 유전 변이가 질병과 관련 있을까?"라는 질문이 보고서가 되기까지를 따라가 보면 전체가 잡힙니다.
① 스킬 선택: 에이전트가 질문을 보고 각 스킬의 description을 훑어 alphagenome-single-variant-analysis가 맞다고 판단합니다.
② 설명서 로드: 그 스킬의 SKILL.md를 펼쳐 작업 체크리스트와 주의사항을 읽습니다(이때 비로소 토큰을 씁니다).
③ 사전 준비: 규칙대로 uv 설치를 확인하고, 라이선스 고지 파일을 만들고, .env의 API 키 존재를 점검합니다(키 내용은 절대 들여다보지 않음).
④ 스크립트 실행: uv run scripts/visualize_variant_effects.py ...로 격리 환경에서 실행. 시스템 파이썬은 건드리지 않습니다.
⑤ 점잖은 호출: 스크립트가 http_client를 통해 AlphaGenome API를 호출합니다. 속도 제한·재시도·백오프가 자동 적용돼 서버에 무례하지 않게 굽니다.
⑥ 해석: 결과 점수표와 그림을 받아, docs/interpretation-guide.md의 규칙(점수 크기 기준 등)에 따라 의미를 읽습니다.
⑦ 보고서 + 자기검증: report-templates.md 양식으로 report.md를 쓰고, 마지막에 스스로 링크·주장을 재검토(self-critique)한 뒤 결과물(artifact)로 만듭니다.
scienceskillscommon/http_client.py 한 곳에 모았습니다. 여기엔 API별 속도 제한, 자동 재시도(429·5xx), 지수 백오프+지터, Retry-After 헤더 존중, 사전 백프레셔(X-Throttling-Control), gzip 해제, 스트리밍이 전부 들어 있는데 — 놀랍게도 외부 라이브러리 없이 파이썬 표준 urllib만으로 구현했습니다.SKILL.md는 요리법, 에이전트는 셰프, 스크립트는 조리도구, http_client는 예의 바른 장보기 담당. 셰프는 메뉴(질문)를 보고 알맞은 요리법을 펴고, 도구로 요리하되, 장은 매번 가게 규칙(속도 제한)을 지키는 담당이 대신 봐 옵니다. 덕분에 어느 가게에서도 출입금지(차단)를 안 당합니다.
/tmp의 잠금 파일(fcntl.flock)로 프로세스들이 같은 한도를 공유하게 만듭니다. 식당 여러 명이 한 장바구니 한도를 나눠 쓰는 셈입니다.어떤 폴더가 무슨 일을 하나.
루트는 단순합니다. 거의 모든 것이 skills/ 아래에 있고, 그 안에 분야별 스킬 폴더 34개와 모두가 공유하는 scienceskillscommon 한 개가 나란히 놓여 있습니다. 스킬 폴더는 전부 SKILL.md + scripts/ + references(또는 docs)/라는 똑같은 3종 구조를 따릅니다.
| 경로 | 역할 |
|---|---|
skills/ | 전부 여기에. 분야별 스킬 34개 + 공용 모듈 1개가 평평하게 나열. |
scienceskillscommon/ | 모든 스킬이 import하는 공용 HTTP 클라이언트. "예의 바른 장보기" 로직의 단일 출처. |
SKILL.md | 각 스킬의 심장. YAML 머리말(name·description) + 절차·규칙·예제. |
scripts/ | 실제 일을 하는 파이썬 파일들. 에이전트가 uv run으로 호출. |
references/ · docs/ | 심화 API 명세·해석 가이드·예제. 필요할 때만 펼쳐 읽음(토큰 절약). |
docs/examples/ | AlphaGenome 스킬의 "골든 예시" — 정답 분석 사례. 에이전트가 따라 배움. |
SKILL_LICENSES.md | 34개 스킬이 건드리는 외부 DB의 이용약관 링크 표. 법적 준수의 지도. |
분야는 크게 다섯 갈래입니다: 유전체학(AlphaGenome·Ensembl·gnomAD·ClinVar·dbSNP·GTEx·ENCODE·JASPAR·UniBind·UCSC), 구조·단백질(AlphaFold DB·PDB·Foldseek·PyMOL·서열 정렬/유사도·InterPro·Human Protein Atlas·QuickGO·Reactome·STRING), 약화학(PubChem·ChEMBL), 문헌(arXiv·bioRxiv·EuropePMC·OpenAlex·PubMed), 임상·약물(ClinicalTrials·openFDA·OpenTargets) — 그리고 NCBI 서열·EMBL-EBI 온톨로지 같은 공통 인프라 스킬이 더해집니다.
이 레포에서 배울 만한 것 + 어디를 보면 되는지.
이 레포 전체가 Agent Skills 형식의 모범 사례집입니다. SKILL.md의 description이 곧 라우터라는 점이 핵심 — "어떤 질문에 이 스킬이 발동되는가"를 description에 잘 적는 것이 스킬 설계의 절반입니다. 34개 스킬의 description을 비교해 읽으면 "발동되는 설명문" 쓰는 감이 잡힙니다.
scienceskillscommon/http_client.py는 그 자체로 훌륭한 교본입니다. 속도 제한(파일 락), 지수 백오프+지터, Retry-After 헤더 파싱, X-Throttling-Control 사전 백프레셔, gzip 스트리밍을 requests 없이 urllib만으로 구현했습니다. "외부 의존성을 늘리지 않으면서 프로덕션급 견고함을 얻는 법"을 한 파일에서 배울 수 있습니다.
"기억으로 답하지 말고 DB로 검증하라"는 규칙, 출력에 출처·고지 포함, 골든 예시로 학습, 마지막 자기검증(self-critique) 단계 — 이 모든 장치가 합쳐져 신뢰성을 만듭니다. RAG를 넘어 "에이전트가 어떻게 거짓을 줄이나"를 절차 수준에서 들여다볼 수 있습니다.
"시스템 파이썬 금지, 무조건 uv run"이라는 단순한 규칙이 어떻게 환경 충돌을 없애는지, 그리고 설명을 잘게 쪼개 필요할 때만 펼치는 구조가 어떻게 토큰을 아끼는지 — 에이전트 도구를 설계할 때 바로 빌려 쓸 수 있는 실전 패턴입니다.
새 스킬 스크립트가 공용 클라이언트 위에 어떻게 얹히는지 보여주는 개념 코드입니다(패턴을 단순화한 예시):
# scienceskillscommon 위에 새 스크립트를 얹는 최소 패턴
import http_client
# 출처별 클라이언트 — 초당 3회로 제한
api = http_client.HttpClient(
"https://eutils.ncbi.nlm.nih.gov/entrez/eutils/",
qps=3, # 속도 제한(여러 프로세스가 공유)
)
# 429/5xx는 자동 재시도 + 지수 백오프, Retry-After 존중
data = api.fetch_json("esummary.fcgi?db=pubmed&id=123456")
그리고 스킬을 발동시키는 SKILL.md 머리말과 핵심 규칙은 대략 이런 모양입니다:
---
name: pubchem-database
description: >
Query PubChem, search by name/CID/SMILES... Use when a user
asks about a specific chemical, drug, or molecule.
---
# PubChem Database
## Core Rules
- Verify Facts: ALWAYS verify with a DB query.
Do not rely solely on internal knowledge.
모든 스킬이 같은 모양(SKILL.md + scripts + 공용 클라이언트)을 가지면, 에이전트는 스킬의 속을 몰라도 "설명 읽고 → 스크립트 돌리기"만 하면 됩니다. 새 분야를 더하는 일이 "정해진 틀에 폴더 하나 더 넣기"로 줄어듭니다. 34개가 한 사람의 솜씨처럼 일관된 이유입니다.
돌리려면 무엇이 필요한가.
좋은 소식은 무거운 하드웨어가 필요 없다는 점입니다. 실제 계산(변이 예측 등)은 대부분 원격 API가 대신하므로 GPU도 필요 없습니다. 로컬에는 uv와 파이썬, 그리고 인터넷 연결만 있으면 됩니다.
| 항목 | 요구사항 |
|---|---|
| 필수 도구 | uv (첫 스킬 실행 시 에이전트가 설치 안내) · Python 3 |
| 설치 방법 | npx skills add google-deepmind/science-skills/ 또는 Antigravity의 "Science" 플러그인 |
| 네트워크 | 외부 과학 DB(HTTPS) 접근 — 거의 모든 스킬이 원격 호출 |
| API 키(필수) | AlphaGenome — 키 없으면 동작 안 함 |
| API 키(선택) | OpenAlex · ClinVar 등 — 없어도 되지만 있으면 호출 한도 ↑ |
| GPU | 불필요 (계산은 원격, 로컬은 표·그림 처리 정도) |
| 호환 에이전트 | Antigravity 외에도 Agent Skills 표준을 지원하는 도구 |
# 설치 — 한 줄
npx skills add google-deepmind/science-skills/
# API 키는 .env에 직접 추가(예: AlphaGenome). 키를 채팅에 붙여넣지 말 것!
printf "Enter key: " && read -s key && echo "ALPHAGENOME_API_KEY=$key" >> ~/.env
스킬 규칙은 키를 에이전트 대화 맥락에 절대 노출하지 말라고 못 박습니다. 키를 채팅에 붙이면 그 값이 컨텍스트에 남아 유출 위험이 생기기 때문입니다. 대신 위 명령처럼 .env에 숨겨 넣고, 스크립트가 dotenv로 자동 로드합니다. 에이전트는 cat·echo·printenv로 키를 들여다보지 않도록 설계돼 있습니다.
난이도별로 손에 익히는 단계.
각 스킬은 PubChem·NCBI·UniProt 등 외부 DB를 호출합니다. SKILL_LICENSES.md에 출처별 약관 링크가 정리돼 있으니, 특히 대량 조회·재배포 전에는 해당 약관을 확인하세요. 스킬이 속도 제한을 강제하는 것도 이 때문입니다.
npx skills add로 설치 후, 키가 필요 없는 literature-search-arxiv 스킬을 발동시켜 본다. "trustworthy AI agents 최신 arXiv 논문 찾아줘"처럼 물어, 에이전트가 스킬을 골라 실제 arXiv API를 조회하는 흐름을 관찰.
uv run scripts/pubchem_api.py resolve --name "aspirin"으로 CID를 얻고, 이어서 properties --cid 2244로 분자량·XLogP 등을 가져온다. 결과 JSON을 jq로 파싱해 보며 "이름 → 식별자 → 속성"의 표준 워크플로를 체득.
공용 클라이언트에서 429를 받으면 어떤 경로로 재시도되는지(_open_stream → _compute_backoff → Retry-After)를 코드로 따라간다. 파일 락(fcntl.flock)이 어떻게 여러 프로세스의 속도를 하나로 묶는지도 확인.
무료 공개 API 하나(예: 공공데이터 REST)를 골라, SKILL.md(발동 description 포함) + scripts/ 스크립트를 작성한다. HTTP 호출은 scienceskillscommon의 HttpClient를 import해 쓰고, 속도 제한·재시도를 공짜로 얻는다. Agent Skills 표준을 직접 만들어 보는 단계.
키를 발급받아 .env에 넣은 뒤, SKILL.md의 9단계 체크리스트(Step 0~8: 골든 예시 검토(MANDATORY) → 준비 → 질의 파싱 → 조직/모달리티 해석 → 시각화 → 해석 → 보고서 → 자기검증 → artifact 생성)를 그대로 따라 한 변이를 분석한다. 골든 예시(docs/examples/)와 결과를 비교해 보기.
한 주씩 따라가는 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | Agent Skills 표준 이해 + 설치·발동 | README · 여러 SKILL.md의 description 비교 · 실습 1 |
| 2주차 | uv 패키지 매니저 · 의존성 격리 | uv 공식 문서 · 각 스킬의 pyproject.toml |
| 3주차 | 견고한 HTTP 클라이언트 설계 | http_client.py 정독 · 실습 3 |
| 4주차 | 그라운딩 · 환각 줄이기 · 자기검증 | PubChem/AlphaGenome SKILL.md의 Core Rules · 기술 보고서 |
| 5주차 | 분야 도메인 맛보기 (분자·문헌·서열) | PubChem · arXiv · UniProt 스킬 실습 |
| 6주차 | 나만의 스킬 제작 · 공용 모듈 재사용 | CONTRIBUTING.md · 실습 4 |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| Agent Skill | AI 에이전트 능력을 확장하는 표준 폴더. 핵심은 SKILL.md. |
| SKILL.md | 스킬의 설명서. YAML 머리말(name·description) + 절차·규칙·예제. |
| description | "이런 질문에 나를 써라"를 적은 발동 트리거. 사실상 라우터 역할. |
| Progressive Disclosure | 필요한 설명만 그때 펼쳐 읽어 토큰을 아끼는 방식. |
| Grounding | 답을 실제 DB·출처에 묶어두는 것. 환각을 줄이는 핵심 장치. |
| uv | Rust 기반 초고속 파이썬 패키지 매니저. uv run으로만 실행. |
| HttpClient | 속도 제한·재시도·백오프를 담은 공용 HTTP 클라이언트(urllib 기반). |
| 백오프 / 지터 | 실패 시 점점 더 오래 기다렸다 재시도(+무작위 흔들기로 충돌 방지). |
| Retry-After | "이만큼 뒤에 다시 와"라고 서버가 알려주는 헤더. 클라이언트가 존중. |
| 백프레셔 | 한도에 닿기 전에 미리 속도를 늦추는 것(X-Throttling-Control). |
| 파일 락 | 여러 프로세스가 한 속도 한도를 공유하게 하는 잠금(fcntl.flock). |
| AlphaGenome | DeepMind의 유전 변이 효과 예측 모델/API. 대표 스킬의 엔진. |
| OSINT가 아님 | 여기선 과학 DB(UniProt·PubChem·PubMed 등)가 데이터 출처. |
| Antigravity | Google의 에이전트 코딩 IDE. Science Skills의 기본 탑재처. |
| plugin.json | 이 묶음을 "science" 플러그인으로 식별하는 메타파일. |