AI 에이전트 토큰 최적화: 워크플로우 대신 스킬(Skills)과 점진적 공개를 써야 하는 이유

AI 에이전트 엔지니어 @NoheDev가 X(구 트위터)를 통해 AI 코딩 에이전트의 효율적인 토큰 관리를 위해 기존 단일 마크다운 워크플로우(Workflows) 체계를 중단하고 업계 표준 스킬(Skills) 포맷으로 전면 전환해야 하는 기술적 이유와 구체적인 마이그레이션 경로를 공개했습니다.

이미지 출처: Google Antigravity Docs

대규모 언어 모델(LLM) 기반의 코딩 에이전트를 실무 개발에 투입할 때 가장 빈번하게 마주치는 병목은 컨텍스트 윈도우 한계와 이에 따른 비용 지출, 그리고 긴 프롬프트 처리에 수반되는 추론 지연입니다. 특히 수백 줄에서 수천 줄에 달하는 작업 절차와 규칙을 단 하나의 마크다운 파일에 전부 몰아넣는 레거시 워크플로우 방식은 실제 당장 수행하는 하위 작업에 필요하지 않은 방대한 지침까지 매 턴마다 모델 컨텍스트에 밀어넣어 불필요한 토큰 소모를 누적시키는 주요 원인으로 지목되어 왔습니다.

단일 마크다운 워크플로우의 한계와 토큰 낭비 구조

기존의 에이전트 워크플로우는 프로젝트 루트나 설정 디렉토리에 위치한 단일 .md 파일 안에 모든 작업 지침과 단계별 명령어를 나열하는 형태가 일반적이었습니다.

이러한 모놀리식(Monolithic) 접근 방식은 구조가 단순해 초기에 도입하기 쉽다는 장점이 있지만, 프로젝트 규모가 커지고 에이전트가 처리해야 할 업무 영역이 다변화되면서 심각한 확장성 문제에 직면하게 됩니다:

• 컨텍스트 오염과 주의력 분산: 에이전트가 전체 작업 중 단순한 테스트 실행 단계 하나만 처리하려 해도, 배포, 코드 리뷰, 데이터베이스 마이그레이션 등 무관한 다른 작업 지침까지 프롬프트에 상시 적재되어 모델의 주의 집중(Attention)을 분산시킵니다.
• 고정된 파일 크기 제약: 단일 마크다운 문서 내에서 모든 엣지 케이스와 스크립트 예제를 다루려다 보면 가독성이 급격히 저하되고, 토큰 예산을 초과하지 않기 위해 필수적인 가이드라인을 인위적으로 축약해야 하는 압박이 발생합니다.
• 캐시 및 비용 비효율성: 에이전트와의 멀티턴 대화가 이어질 때마다 거대한 워크플로우 본문 전체가 반복적으로 계산되거나 컨텍스트 윈도우의 앞자리를 차지하여 실질적인 코드 작업에 할당할 수 있는 여유 공간을 갉아먹습니다.

스킬(Skills) 아키텍처의 3대 핵심 이점: 점진적 공개·무제한 번들·에셋 구조화

@NoheDev는 워크플로우 방식을 폐지하고 업계 표준 스킬(Skills) 규격으로 전환함으로써 얻을 수 있는 결정적 이점으로 다음 세 가지를 제시했습니다.

1. 점진적 공개(Progressive Disclosure)를 통한 토큰 최소화

스킬 규격의 가장 핵심적인 메커니즘은 '점진적 공개' 원칙입니다. 에이전트 런타임이 초기 기동될 때는 모든 스킬의 세부 본문을 메모리에 올리지 않습니다. 대신 스킬의 명칭, 핵심 요약 설명, 호출 트리거 조건 등 수십 토큰 수준의 최소 메타데이터만을 인덱싱하여 에이전트에게 제공합니다. 이후 에이전트가 특정 작업을 해결하기 위해 해당 스킬이 필요하다고 판단할 때만 온디맨드(On-Demand) 방식으로 상세 지침과 페이로드를 컨텍스트에 불러옵니다. 이를 통해 상시 유지되는 베이스라인 토큰 비용을 획기적으로 낮출 수 있습니다.

2. 단일 파일 제약을 벗어난 무제한 번들 크기(Unrestricted Bundle Sizes)

기존 워크플로우처럼 하나의 단일 마크다운 문서에 모든 로직을 우겨넣을 필요가 없습니다. 스킬 구조에서는 각 도메인이나 작업 단위별로 독립적인 번들이 구성되므로, 전체 스킬 패키지의 전체 용량이나 세부 지침의 길이에 인위적인 상한선이 존재하지 않습니다. 복잡한 다단계 파이프라인이나 전문적인 분석 도구도 컨텍스트 과부하 우려 없이 완전하고 정교한 지침 문서로 분리 작성할 수 있습니다.

3. 디렉토리 기반의 체계적인 에셋 번들 구조(Better Asset Bundle Structure)

스킬 포맷은 단순 텍스트 프롬프트를 넘어 보조 에셋들의 물리적 구성을 표준화합니다. 스킬 폴더 내부에 참조용 JSON 스키마, 템플릿 파일, 자동화 헬퍼 스크립트, 예제 데이터 등을 서브디렉토리 형태로 함께 패키징할 수 있습니다. 에이전트는 필요에 따라 이러한 보조 에셋을 파일 단위로 직접 읽거나 실행 도구로 연계할 수 있어, 텍스트 프롬프트 안에 스크립트 코드를 원시 문자열로 하드코딩해야 했던 기존 워크플로우의 한계를 말끔히 해소합니다.

/migrate-workflows 스킬을 통한 전환과 2026년 11월 1일 지원 종료 일정

@NoheDev는 워크플로우의 공식 지원 종료(Deprecation) 일정이 2026년 11월 1일로 확정되었음을 알리며, 기존 사용자들을 위해 원클릭 전환 도구를 제공한다고 밝혔습니다.

사용자는 에이전트 환경에서 내장된 /migrate-workflows 스킬을 실행하여 기존의 단일 마크다운 워크플로우 파일들을 최신 스킬 디렉토리 구조로 자동 변환할 수 있습니다:

/migrate-workflows

해당 마이그레이션 도구는 기존 워크플로우의 단계별 로직을 분석하여 스킬 메타데이터와 점진적 공개를 지원하는 디렉토리 번들 형태로 안전하게 재배치해 줍니다. 2026년 11월 1일 이후에는 기존 워크플로우 형식이 완전히 비활성화될 예정이므로, 에이전트 기반 개발 환경을 운용하는 엔지니어는 조기에 마이그레이션을 완료하고 토큰 절감 효과를 검증하는 것이 권장됩니다.

원문 출처

본 포스트는 @NoheDev의 공식 X 발표 및 Google Antigravity 개발팀의 공식 워크플로우-스킬 마이그레이션 기술 문서를 기반으로 작성되었습니다. 다가오는 2026년 11월 1일 워크플로우 지원 종료 일정과 스킬 번들 규격에 관한 상세한 기술 정보는 아래 공식 링크를 통해 확인할 수 있습니다.

• @NoheDev 공식 X 발표: X 원문 포스트
• 워크플로우 지원 종료 및 스킬 전환 공식 문서: Google Antigravity Migration Docs