에이전트 스킬(Agent Skills)에는 사각지대가 있습니다 — 그리고 이를 해결하는 방법은 다음과 같습니다

지난 1년 동안 AI 코딩 에이전트(AI coding agents)를 활용해 개발해 오셨다면, 아마 에이전트 스킬(Agent Skills)을 발견하셨을 것입니다. 그 전제는 우아합니다. 워크플로우(workflows)를 휴대 가능하고 버전 관리가 가능한 스킬 폴더로 패키징하여, 어떤 에이전트든 가져와서 사용할 수 있게 만드는 것입니다. 한 번 작성하면 어디서든 사용할 수 있습니다.

저는 이에 완전히 몰입해 왔습니다. 저는 Google Conductor 워크플로우와 Matt Pocock의 에이전트 패턴(agentic patterns)을 결합한 15개의 스킬 컬렉션인 ram-agent-skills를 오픈소스로 공개했습니다. 제가 매일 사용하는 conductor, grill-me, to-prd, tdd와 같은 스킬들이 포함되어 있습니다.

하지만 몇 달간 실제 환경에서 사용해 본 결과, 벽에 부딪혔습니다. 그리고 진지하게 스킬을 구축하는 사람이라면 누구나 이 벽에 부딪힐 것이라고 생각합니다.

문제점: 스킬은 인간 참여(human-in-the-loop) 요구사항을 표현할 수 없습니다

제 말은 이렇습니다. conductor 스킬을 예로 들어보겠습니다. 이것은 구조화된 개발 워크플로우입니다. 사양(spec)을 생성하고, 승인을 받고, 구현 계획을 세우고, 다시 승인을 받고, 단계별로 구현하며, 각 커밋(commit) 전에 수동 검증을 요청합니다.

이러한 모든 승인 단계에는 인간이 필요합니다. 그리고 현재 스킬이 인간의 입력을 요청할 수 있는 유일한 방법은 지침(instructions)에 다음과 같이 작성하는 것뿐입니다:

_"진행하기 전에 사용자에게 프로젝트 이름, 기술 스택(tech stack), 그리고 목표를 물어보세요."

그러면 에이전트는 질문을 즉흥적으로 만들어냅니다. 도구는 자신이 원하는 방식대로 이를 렌더링합니다. 인간은 자유 형식의 텍스트로 답변합니다. 에이전트는 돌아온 결과가 무엇이든 파싱(parse)합니다.

이는 엄격해야 할 워크플로우에서 네 가지의 실패 지점(failure points)을 만듭니다.

그 결과:

• 동일한 스킬임에도 Claude Code, Cursor, Copilot에서 완전히 다르게 느껴집니다.
• 필수 입력 사항이 검증 없이 건너뛰어질 수 있습니다.
• 어떻게 물어볼지(확인 대화창인지, 다중 선택인지, 순위 지정 목록인지 등)를 표현할 방법이 없습니다.
• 사양을 구현하는 모든 도구가 인간의 입력을 수집하는 과정을 처음부터 다시 만들어야 합니다.

오늘날의 스킬은 인간의 입력을 수집하기 위한 UI 요구사항을 도구에 구애받지 않는(tool-agnostic) 일반적인 방식으로 전달할 수 없습니다.

그것이 바로 간극(gap)입니다.

해결책의 모습

저는 Agent Skills 명세(spec)에 human-interactions 필드를 추가하는 제안을 작업해 왔습니다. 핵심 아이디어는 간단합니다:

스킬은 자신의 SKILL.md 프론트매터(frontmatter)에 단일 2-토큰 신호를 추가합니다:

---
name: conductor
description: Structured development track management...
...

그리고 새로운 references/INTERACTIONS.md 파일이 전체 스키마(schema)를 보유하며, 이는 시작 시점이 아니라 스킬이 활성화될 때만 로드됩니다. 이는 의도적인 설계입니다. 컨텍스트 비대화(Context bloat)가 MCP의 사용성을 망쳤기 때문입니다. 우리는 그 실수를 반복하지 않을 것입니다.

이 스키마를 통해 스킬 작성자는 무엇을 언제 수집할지를 선언할 수 있습니다. 도구(tool)는 그것을 어떻게 렌더링할지를 결정합니다.

- id: project-setup
  trigger: before-start
  title: "Set up your conductor track"
...

동일한 스키마가 Claude.ai에서는 풍부한 양식(rich form)으로, 터미널에서는 순차적인 프롬프트(sequential prompts)로, Copilot에서는 채팅 카드(chat card)로 렌더링됩니다. 스킬 작성자는 의도(intent)를 작성하고, 도구는 표현(presentation)을 처리합니다.

사례의 80%를 커버하는 네 가지 트리거(trigger) 유형

이 제안은 워크플로 중심의 스킬에서 나타나는 실제 패턴에 매핑되는 네 가지 트리거를 정의합니다:

before-start — 실행이 시작되기 전 한 번 실행됩니다. 에이전트가 스스로 추론할 수 없는 필수 컨텍스트(context)를 위한 자리입니다. 스택(stack), 목표(goal), 우선순위(priorities) 등이 해당됩니다. 스킬 본문이 로드되기도 전에 수집됩니다.

on-phase — 명명된 단계(phase) 경계에서 실행됩니다. conductor의 경우, 이는 "명세 완료 — 계획 전 승인" 및 "계획 완료 — 구현 전 승인"에 해당합니다. 단계 이름은 자유 형식(freeform)이므로, 스킬이 사용하는 워크플로 구조가 무엇이든 이에 매핑됩니다.

on-demand — 에이전트가 시작합니다. 스킬 본문이 에이전트에게 언제 이를 호출할지 알려줍니다. 실행 도중 모호한 상황이 발생했을 때 명확히 하기 위해 사용됩니다.

on-confirmation — 파괴적이거나 되돌릴 수 없는 작업을 수행하기 전, 명시적인 인간의 승인을 기다리며 차단(block)합니다. on-skip: abort(기본값) 설정 시, 건너뛰기를 하면 스킬이 깔끔하게 중단되며, 조용히 계속 진행되는 일은 절대 없습니다.

동적 옵션: 코드베이스를 이해하는 스킬

정적인 옵션 목록은 일반적인 스킬에는 괜찮습니다. 하지만 실제 워크플로 스킬은 사용자가 있는 곳에서 사용자와 만나야 합니다.

이 제안은 정적 배열 (static arrays)과 함께 동적 옵션 소스 (dynamic option sources)를 지원합니다:

- id: tech-stack
  type: multi-select
  label: "Detected tech stack — confirm or adjust"
...

v1에서는 두 가지 소스가 제안됩니다:

• file — 리포지토리 (repo)에 이미 존재하는 파일을 읽으며, 에이전트 (agent)는 extract 힌트를 사용하여 관련 옵션을 추출합니다. 코드 실행 (code execution)이 없으므로 새로운 공격 표면 (attack surface)이 발생하지 않습니다.
• agent — 에이전트가 이미 보유한 컨텍스트 (context)로부터 옵션을 추론합니다. "src/ 내의 어떤 모듈이 이 변경 사항과 관련이 있는가?"와 같은 작업에 사용됩니다.

스크립트 기반 동적 옵션 (옵션을 생성하기 위해 번들된 스크립트를 실행하는 방식)은 적절한 샌드박스 실행 보안 모델 (sandboxed execution security model)이 마련될 때까지 명시적으로 연기되었습니다. 이러한 연기 사항을 명시하는 것은 중요합니다. 이는 가능성을 차단하지 않으면서도 제안 내용을 깔끔하게 유지해 줍니다.

스킬 작성자에게 의미하는 바

만약 여러분이 현재 스킬을 구축하고 있다면, 이는 워크플로 (workflows) 내의 인간 참여 (human-in-the-loop) 부분에 대해 생각하는 방식을 변화시킵니다. 다음과 같이 작성하는 대신:

"커밋하기 전에 사용자에게 확인을 요청하십시오."

모든 도구가 올바르게 렌더링할 수 있는 구조화된 체크포인트 (checkpoint)를 작성하게 됩니다:

- id: commit-confirm
  trigger: on-confirmation
  title: "Manual verification — ready to commit?"
...

이제 스킬은 에이전트뿐만 아니라 인간을 위한도 진정한 계약 (contract)이 됩니다.

레퍼런스 구현 (Reference implementation)

이를 구체화하기 위해, ram-agent-skills 내의 conductor 스킬이 human-interactions를 사용하도록 업데이트했으며, 명세서 (spec)의 모든 기능 — 모든 트리거 타입 (trigger type), 모든 필드 타입 (field type), 정적 및 동적 옵션 모두 — 에 대해 각 선택 이유를 설명하는 주석과 함께 완전히 주석이 달린 워크스루 (walkthrough)인 새로운 human-interaction-demo 스킬을 추가했습니다.

브랜치는 여기 있습니다: ram-agent-skills/tree/human-interactions-rfc

토론에 참여하세요

이것은 초안 RFC (draft RFC)이며, 완성된 명세서 (spec)가 아닙니다. 목표는 내용이 확정되기 전에 커뮤니티의 검토를 받는 것입니다.

이 RFC는 **agentskills/agentskills#413**에서 논의에 열려 있습니다. 의견을 나눌 가치가 있는 몇 가지 질문은 다음과 같습니다:

• on-phase 단계 이름(phase names)을 자유 형식으로 유지해야 할까요, 아니면 명세서(spec)에서 일반적인 패턴을 위한 기본 어휘(base vocabulary)를 정의해야 할까요?
• 수집된 값(collected values)을 에이전트(agent)에게 구조화된 참조(project-setup.track-type)로 노출해야 할까요, 아니면 자연어(natural language)로 주입해야 할까요?
• 초기 세트에서 누락되어 즉시 사용하고 싶은 트리거 유형(trigger types)이나 필드 유형(field types)이 있습니까?

Agent Skills 생태계는 빠르게 성장하고 있습니다 — 16k 개의 스타(stars)를 기록 중이며, Claude Code, Cursor, Copilot, Windsurf 등에서 구현되고 있습니다. 명세서(spec) 수준에서 인간 참여형(human-in-the-loop) 방식을 올바르게 설정하는 것이 중요합니다. 저희가 놓치고 있는 것이 무엇인지 알려주세요.

Ramakrishnan Meenakshi Sundaram은 ANZ Bank의 VP Engineering이자 Agent Skills 생태계의 기여자입니다. 그의 스킬 컬렉션(skill collection)은 github.com/ramki982/ram-agent-skills에서 확인할 수 있습니다.