JYP Garden

수업 #10 — 100개의 워크플로우를 버렸다

Properties1
tagssource, agentic-architecture, harness-engineering, knowledge

7 min read

수업 #10 — 100개의 워크플로우를 버렸다

Source: bbojjak-viewer.vercel.app/lessons/lesson-10 Type: article By: 뽀짝이 / 뽀짝이의 서재 (지피터스 AI스터디) Valid as of: 2026-04-28

Key Insight

에이전트 스킬 = 폴더 하나(SKILL.md + scripts/ + references/). n8n(트리거→자동실행)과 달리 에이전트가 설명서를 읽고 판단해서 실행 — “맥락을 이해하고 예외에 대응해야 하는가?”가 스킬/n8n 선택의 핵심 질문이다.

핵심 Takeaway

  • 스킬 = 폴더 하나: SKILL.md + scripts/ + references/ + .env. 에이전트가 설명서를 읽고 판단해서 실행. n8n의 “트리거→자동실행”과 달리 예외 상황에 유연 대응 (출처: “스킬이란 뭘까?” 섹션)
  • SKILL.md = 설명서이자 진입점: name + description으로 스킬 식별. 세션 시작 시 모든 스킬 description 스캔. description 부정확하면 적절한 스킬이 있어도 매칭 실패 (출처: “SKILL.md” 섹션)
  • references/ = “왜 이 값인지” 문서: API 키, 엔드포인트, ID 매핑 등을 설명과 함께 기록. n8n에서는 블록에 하드코딩. 스킬에서는 마크다운으로 git 관리 (출처: “references” 섹션)
  • 스킬 로드 우선순위: 워크스페이스 > 공유(~/.claude/skills/) > 번들. 공유 폴더로 여러 에이전트가 스킬 공유. n8n과 달리 폴더 복사로 이식 (출처: “스킬이 사는 곳” 섹션)
  • 선택 기준 = 판단 필요 여부: n8n = 단순반복·웹훅중계. 스킬 = 맥락필요·복잡예외·여러시스템. “맥락을 이해하고 예외에 대응해야 하는가?” (출처: “왜 n8n이 아니라 스킬인가?” 섹션)

상세 요약

n8n의 3가지 구조적 한계

  1. 수정 어려움: GUI에 로직이 흩어져 검색·diff 불가. n8n 블록 12개 = TypeScript 100줄 (동일 기능)
  2. 디버깅 까다로움: JSON 덩어리 로그, 블록 추적 필요. 스킬은 “line 47: fetch failed” 즉시 파악
  3. 문서화 없음: 시간 지나면 만든 사람도 “이거 뭐지?” 상태

스킬 구조 상세

~/.claude/skills/{이름}/
├── SKILL.md              ← YAML(name, description) + 실행 절차
├── scripts/              ← 핵심 로직 (TypeScript/Python)
├── references/           ← API 정보, ID 매핑, 설명 문서
└── .env                  ← 환경변수

SKILL.md 프론트매터:

---
name: ai-talk-manager
description: AI토크 이벤트의 전 과정을 관리합니다.
  Zoom 회의 생성, UTM 링크 단축, 베터모드 이벤트 게시, Airtable 등록을 자동화합니다.
---

description이 요청-스킬 매칭의 핵심. 실제 사고: openclaw-lesson 스킬을 description에서 못 찾아 수동 발행 → 태그 누락.

스킬이 n8n보다 좋은 이유: 맥락 이해

n8n: 베터모드 게시 실패 → 처음부터 워크플로우 재실행 (Zoom, Bitly 포함)

스킬: “아, 제목 규칙이 잘못됐구나” → 게시글만 수정 재게시. Zoom, Bitly는 이미 완료됐으므로 건드리지 않음.

에이전트가 전체 맥락을 이해하므로 실패한 부분만 수정 가능.

scripts/ 활용 기준

스크립트가 필요한 경우:

  • 재현 가능성 필요 (같은 스크립트 = 같은 결과)
  • --dry-run 플래그 등 테스트 가능하게 설계
  • 복잡한 로직 (API 여러 개, 조건 분기 복잡)

스크립트 없이 SKILL.md만으로 가능한 경우:

  • 간단한 절차 (에이전트가 직접 API 조합)

전환 결과 (9일간)

  • n8n 100개 → 핵심 5개 스킬로 전환, 2개 n8n 유지, 93개 비활성 유지
  • 수정 속도: 15분 → 2분
  • n8n에 남긴 것: 스케줄러/웹훅 중계 (판단 불필요) + 기수별 운영 트리거 (단순 시간 기반)

연결되는 위키 페이지

그래프 뷰