본문으로 건너뛰기

잡탕이 된 스킬을 해체하고 워크플로 슬롯에 재분배했다

리히토

2026.05.31

잡탕이 된 스킬을 해체하고 워크플로 슬롯에 재분배했다 본문 이미지

헤르메스 전용으로 비개발자가 손으로 만들어둔 만능 잡탕 스킬 1개를, Claude Code에서도 쓸 수 있는 라이브러리 번들 1개로 해체. 파일 9개, 약 1,500줄. 동작 확인용 smoke test 6/6 통과. PDF 본문→Markdown 추출 이식은 다음 작업.


이런 분들께

  • 처음엔 치밀한 계획 없이 시작했는데, 그때그때 흐름대로 만든 AI 스킬들이 어느새 서로 중복돼서 한 번 정리하고 싶은 사람

  • 자기가 만든 첫 AI 스킬이 점점 커져서 손대기 무서운 사람

  • "AI에게 시키기"를 넘어서, AI가 다시 호출할 수 있는 작은 도구로 쪼개고 싶은 사람


🪤 시작: 가장 원시적인 스킬을 왜 굳이 해체했나

처음 만든 스킬 zotero-note-sync(Zotero — 학술 논문 레퍼런스 매니저)는 만능 잡탕이었습니다.

원래는 "Zotero에서 논문 하나 찾아서 → 거기 PDF를 AI로 요약 → 노트 만들기"였는데, 시간이 지나며 PDF 직접 입력, 프런트매터 렌더링, 상태 관리까지 한 덩어리에 다 흡수돼 있었죠.

게다가 이 스킬은 원래 헤르메스 에이전트 전용으로 비개발자인 제가 손으로 만들어둔 거였습니다. 나름 이것저것 신경쓴다고는 썼으나, 제대로 된 기획 없이 만든 스킬이었죠 (해줘 메타 + 처음에 만들어준 스킬에다가 여러 말을 앉아서 기워 고침). 게다가 점점 '이러이러한 조건 때도 쓸수있게 해줘'를 붙였더니 점점 비대해졌죠.

제 작업 환경도 고민이었습니다. 제가 쓰는 컴퓨터가 여러 대로 분산돼 있고, 헤르메스 에이전트가 깔린 건 그중 한 대 (맥북)뿐입니다. 여러 곳에 헤르메스 에이전트를 깔아 관리하는 건 부담이 컸고, 한편 Claude Code는 모든 컴퓨터에서 돌릴 수 있죠.

그래서 스킬 해체, 정리의 동기는 두 가지로 정리할 수 있겠습니다.

1. 스킬을 정리해서 책임 경계를 명확히 한다

2. 다양한 환경(여러 컴퓨터·여러 에이전트)에서 동일 작업을 호출할 수 있게 만든다

이번에는 해체 작업 전에 흐름을 먼저 그리고 시작했습니다. Claude Code와 대화하면서 "어떤 단계로 워크플로를 나눌지" 흐름을 짠 뒤, 그 자리에 맞게 잡탕에서 부품을 떼어내는 게 이번 작업이었습니다. 그려뒀던 큰 흐름은 대략 이랬어요.

  • Pubmed -> Zotero

    • Pubmed mcp 등을 연결. 자연어로 원하는 주제 검색

    • 조건에 맞게 검색된 논문의 매우 간단한 한줄 요약을 주면 사용자가 인용하고 싶은 논문 선택

    • 고른 논문을 조테로에 추가

      • 기존의 방식 (크롬의 zotero extension을 쓰거나, 직접 pdf를 받아 추가하는것)

      • 새로 원하는 방식: 쓰기 권한이 있는 API key와 pyzotero라이브러리를 이용하여, 조테로 라이브러리에 논문 추가 (여기에는 정규화된 논문 정보키 (better bibtex), PMID, 저장된 pdf의 상대 경로 등이 포함)

    • 조테로에 연결된 pdf는 어느 컴퓨터에서나 접근 가능한 NAS에 저장되어있음.

    • 따라서 원하는 조건의 논문을 조테로에서 조회하면, 조테로에 논문 item마다 메타데이터에 pdf 파일 경로가 저장 되어있기 때문에, 다음 단계가 가능해집니다.

  • L0(원문 추출): 조테로에서 조회한 경로를 따라가서, 해당 PDF에서 깨끗한 본문 Markdown만 뽑기

  • L1(요약·합성): L0 결과를 받아 제가 원하는 방식으로 AI가 요약·재구성

즉 이번 해체는 "잘게 쪼개기"가 아니라 이미 그려둔 워크플로 슬롯에 부품을 재분배하는 작업이었습니다. 잡탕 안의 함수들을 보고 "이건 L0 PDF 경로 헬퍼 자리", "이건 공용 코어가 들고 있어야 할 Zotero 통신층" 식으로 행선지가 미리 정해진 상태로 시작했죠.

잡탕을 까보니, 이 스킬이 L0/L1 경계를 너무 심하게 깔아뭉개고 있어서 분리 자체가 만만치는 않았습니다만, 클로드 코드와 이야기하면서 재분배하였습니다.


🏠 새 집 결정: 다른 AI 에이전트도 쓸 수 있게 별도 워크스페이스로

기존 헤르메스에 묶여 있던 스킬을, Claude Code에서도 동등하게 호출할 수 있는 별도 워크스페이스로 옮기기로 했습니다. 위치 자체보다 중요한 건 "특정 에이전트에 의존하지 않는 형태로 정돈한다"는 원칙이었어요.

핵심 결정 하나만 짚자면: 공용 venv(Python 가상환경 — 의존 라이브러리를 한곳에 모은 격리 폴더)와 공용 secrets(API 키 등 비밀값 저장소)를 새 위치로 분리하기로 했습니다.


🧐 서브에이전트 병렬 리뷰가 잡은 버그

코드 이식을 어느 정도 진행하고 나서, /kkirikkiri(관점이 다른 서브에이전트들을 병렬로 띄워주는 도구)의 analysis 프리셋으로 리뷰어 3명을 관점을 일부러 다르게 띄웠습니다 (gptaku님 플러그인 안의 스킬 사용 -https://github.com/fivetaku/gptaku_plugins)

  • 리뷰어 A: 보안

  • 리뷰어 B: 호환성 (헤르메스 원본과의 듀얼 거주)

  • 리뷰어 C: 구조

각각 관점별로 다른 코멘트를 주었습니다.

특히 호환성 관점이 잡은 한 건은 보안·구조 관점에선 잘 안 보이고, 호환성 시각에서만 드러나는 한계점이었습니다.

환경변수 3개로 경계를 다시 그었고 (STATE_DIR / SECRETS_DIR / STRICT), 이를 통헤 헤르메스 및 클로드 코드 둘다 사용가능하도록 처리하였음 -> 스킬이 완성형이 아니라, 스킬 마무리 된후 테스트 예정.

(Smoke test: 본격적인 테스트를 진행하기 전, 치명적인 결함이 없는지 핵심 기능들의 작동 여부만 빠르고 가볍게 확인하는 기초적인 검증 단계)

AI 코드 리뷰는 하나보다 관점이 다른 여러 에이전트를 병렬로. 같은 코드를 다른 시각이 짚어주지 않으면, 한 시각에서만 보이는 버그는 끝까지 안 보일 수도 있습니다.


📜 묻혀 있던 절차를 재현 가능한 스크립트로

기존에 흩어져 있던 절차 중에는 NAS의 PDF를 Zotero 항목의 메타데이터에 첨부 파일 경로만 입력하는 방식이 있었습니다. (상단에 설명한, 드래그 앤 드롭 하지 않아도 자동 저장해둔 pdf를 연결시켜줌)

그런데 이 내용이 참고 문서에만 적혀 있었어요. 코드는? 없었습니다.

  • (과거 세션) 헤르메스가 즉석에서 명령으로 7편을 처리. 테스트 자체는 성공.

  • (그 뒤) 재사용 가능한 스크립트로 박아두지 않음. 절차는 참고 문서에만 적힌 채로 잊혀짐.

  • (이번 세션) 그 절차를 정식 스크립트(`attach_linked_file.py`)로 박아 다시 호출 가능하게.

에이전트가 즉석 명령으로 처리한 일을 다음을 위해 박아두지 않은 것이 진짜 문제였어요.

어찌저찌 그 당시 생성한 아티팩트들을 재료로 해서 스킬로 확정지었습니다.

교훈: "스킬 작동 테스트 성공"이 곧 "스크립트의 존재"를 의미하지는 않습니다. 즉석으로 해결한 일은 그 자리에서 스크립트로 박지 않으면, 다음에 그게 있었는지조차 잊습니다. 추후에 남은 일로 확실하게 적어두거나, 가능하다면 스크립트로 만들어두는 습관을 가져야겠단 생각이 들었습니다.


✅ 결과

  • 잡탕 1개 → 라이브러리 번들 1개 (파일 9개, 약 1,500줄)

절대경로 잔재 0, 옛 프로필 잔재 0

  • smoke test 6/6 통과

  • 옛 잡탕 스킬 자체는 아직 과도기라, 헤르메스 쪽에 그대로 둠 (인수인계 task로 분리)

옛 잡탕 vs 새 번들 — 한눈에

추상적인 "해체"가 아니라 실제 파일·문서가 어떻게 바뀌었는지.

scripts 파일 분포 — 어디서 어디로

즉 줄 수가 절반 가까이 줄어든 게 핵심이 아닙니다. 책임이 명확해지고, 다른 스킬이 부분만 가져다 쓸 수 있게 됐다는 게 더 큰 변화예요.

앞으로 남은 일: PDF 본문 추출 -> markdown 파일로


📎 최종 스킬 구조

50-projects/med-research-skills/
├── .env.example
├── .gitignore
├── README.md
├── requirements.txt
├── .venv/                     # 공용 Python 가상환경
└── zotero-library-operations/
├── SKILL.md               
├── references/
└── scripts/
   ├── zotero_api.py
   ├── pdf_paths.py
   ├── zotero_tag_cleanup.py
   └── attach_linked_file.py
~/.config/med-research-skills/secrets/ (zotero ID, API key 관련)
├── zotero.json                # 0600 (읽기 key, 읽기 권한만)
└── zotero-write.json          # 0600 (write 전용 key)

6

함께 이야기해요 6

로그인하고 댓글을 남겨 주세요

유피테르 프로필 이미지
유피테르2026.05.31

지난번에 말씀하신 스킬 분리하셨군요! 확실히 스킬을 분리하니까 스킬이 어떻게 적용되었는지 역추적이 가능하다는 것이 중요한 부분인 것 같습니다. 스킬 적동 테스트 성공 이후 즉시 그 자리에서 스크립트로 박아놓아야 한다는 점은 저에게도 좋은 시사점이 됩니다. 감사합니다.

리히토 프로필 이미지
리히토2026.05.31

넵 그자리에서 저장 안하면 증발해버리더라고요 .. (저도 까먹지 말고 에이전트도 정상 작동한 과정은 확실히 스킬로 확정지을건지 저한테 다시 물어보라고 좀 잡도리해야겠어요...)

Giacomo 프로필 이미지
Giacomo2026.05.31

zotero-note-sync가 커져버린 과정을 “처음 만든 게 엉망이었다”로 끝내지 않고, 왜 커졌는지와 어디서 책임 경계가 무너졌는지를 다시 짚으신 점이 좋았습니다. PDF 입력, 프런트매터, 상태 관리, 요약까지 한 덩어리에 붙어버린 상황은 AI 스킬을 조금씩 고쳐 쓰다 보면 정말 자연스럽게 생기는 문제인데, 그걸 숨기지 않고 해체 대상으로 삼으신 게 인상 깊었어요.

특히 PubMed → Zotero → L0 원문 추출 → L1 요약·합성이라는 흐름을 먼저 그린 뒤에, 잡탕 스킬 안의 기능들을 그 자리에 다시 배치하신 판단이 좋았습니다. 그냥 파일을 여러 개로 나눈 게 아니라, “이 기능은 Zotero 통신층”, “이건 PDF 경로 헬퍼”, “이건 L0 추출 쪽”, “이건 L1 요약 쪽”처럼 워크플로 안에서 각 부품이 있어야 할 위치를 다시 정한 작업으로 보였습니다. 이 차이가 꽤 크다고 느꼈어요.

여러 컴퓨터와 여러 에이전트 환경을 고려해서 Hermes 전용 스킬을 Claude Code에서도 쓸 수 있는 별도 라이브러리 번들로 옮긴 것도 실무적으로 의미 있어 보였습니다. 특정 런타임에만 묶인 개인 요령이 아니라, 공용 venv와 secrets 위치를 분리하고 STATE_DIR / SECRETS_DIR / STRICT 같은 경계까지 다시 잡으신 건 “내 환경에서 한 번 되는 자동화”를 “여러 환경에서 다시 호출 가능한 작업 단위”로 바꾸는 과정에 가까웠습니다.

관점이 다른 서브에이전트들을 병렬로 리뷰시킨 부분도 좋았습니다. 보안, 호환성, 구조를 나눠서 보게 하니까 한 관점에서는 잘 안 보이던 문제가 드러났고, 특히 Hermes 원본과 Claude Code 쪽의 듀얼 거주 문제를 호환성 관점에서 잡아낸 흐름이 좋았어요. 이건 단순히 AI에게 코드 리뷰를 시킨 게 아니라, 서로 다른 검증 시각을 붙여서 구조의 약한 부분을 찾아낸 사례처럼 보였습니다.

여기서 더 강해질 수 있는 지점은, 지금 나눠두신 각 단계마다 “무엇을 받으면 시작할 수 있고, 무엇을 내보내야 끝난 것으로 볼지”를 조금 더 명확히 박아두는 것 같아요. PubMed 단계는 검색 조건과 논문 선택 기준이 흔들리지 않는지, Zotero 단계는 PMID·Better BibTeX·PDF 경로 같은 메타데이터가 빠지지 않는지, L0 단계는 PDF에서 깨끗한 본문 Markdown이 추출되는지, L1 단계는 요약이 원문 근거를 벗어나지 않는지를 각각 따로 확인하는 식입니다.

이렇게 해두면 나중에 문제가 생겼을 때 “스킬 전체가 이상하다”로 돌아가지 않고, 어느 칸이 흔들렸는지를 바로 좁힐 수 있을 것 같습니다. 예를 들어 PDF 본문 → Markdown 추출을 붙일 때도 대표 논문 몇 개를 고정 샘플로 두고, 경로 찾기 성공 여부, 본문 추출 품질, 표/초록/본문 구분, L1 요약 입력으로 넘겨도 되는 정도를 따로 확인하면 좋을 것 같아요. 그러면 구조가 커져도 각 단계가 자기 역할을 통과했는지 확인할 수 있어서, 유지보수가 훨씬 쉬워질 것 같습니다.

“스킬 작동 테스트 성공”이 곧 “재사용 가능한 스크립트가 남아 있다”는 뜻은 아니라는 대목도 정말 좋았습니다. 과거에 즉석 명령으로 7편을 처리했던 성공이 있었지만, 그 절차가 코드로 고정되지 않아 다시 쓰기 어려웠다는 부분이 현실적이었어요. 이번에 attach_linked_file.py처럼 재사용 가능한 스크립트로 박아둔 건, 다음 세션과 다음 에이전트가 이어받을 수 있는 형태로 기억을 남긴 작업이라고 느꼈습니다.

결과에서 파일 9개, 약 1,500줄, smoke test 6/6 통과도 물론 의미 있지만, 더 중요한 건 책임이 명확해지고 다른 스킬이 필요한 부품만 가져다 쓸 수 있게 됐다는 점 같아요. 비대해진 첫 스킬을 버린 게 아니라, 그 안에 쌓인 시행착오를 다시 분해해서 호출 가능한 구조로 바꾼 사례라서 좋았습니다. PDF 본문 추출까지 붙으면 이 번들이 단순 Zotero 보조 스킬을 넘어서, 연구 자료 수집부터 원문 정리와 요약까지 이어지는 꽤 탄탄한 연구 워크플로의 기반이 될 것 같습니다.

리히토 프로필 이미지
리히토2026.05.31

피드백 감사합니다.. 앞으로는 스킬 만들때 최대한 쪼개서.. 그리고 용도가 명확한 단위로 나눠서 해야겠단 생각이 들었습니다... 재구성하는게 꽤 머리가 아프더라고요 ㅠ.ㅠ얼른 위키 써먹고 싶은데 pdf 본문 추출이 생각보다 잘 안되서 이쪽도 애먹고 있는데 빨리 추출 끝내고 인제스트해보겠습니다 +_+

유피테르 프로필 이미지
유피테르2026.05.31

@리히토

pdf 본문 추출 시에 marker ai를 한 번 써보세요. 이게 ai인데 local에서 돌아가면서 tesseract보다 더 성능이 괜찮은 것 같습니다. 물론 pdf마다 특성이 다 달라서 확신하기는 어렵겠지만요

딩돌이 프로필 이미지
딩돌이2026.05.31

좋네옹 병렬리뷰시키는것

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기