스킬(Skills)은 엉망입니다. 이제 해결해 봅시다.

여기에 문제가 있습니다. 당신은 zeroclaw를 위한 스킬(skill)을 작성합니다. 로컬(locally)에서는 잘 작동하죠. 당신은 그것을 푸시(push)합니다. 다른 누군가가 그것을 설치하려고 시도합니다. 아무것도 작동하지 않습니다. 에러 메시지에는 "의존성 누락(missing dependency)"이라고 나오지만, 어떤 것인지 알려주지는 않습니다. 혹은 설치는 되지만 감사(audit)가 조용히 실패합니다. 아니면 테스트 하네스(test harness)가 그냥... 실행되지 않습니다.

익숙한 상황인가요?

저는 zeroclaw 스킬(skills) 생태계가 성장하는 것을 지켜봐 왔습니다. 더 많은 사람들이 스킬을 작성하고 있습니다. 더 많은 사람들이 똑같은 벽에 부딪히고 있습니다. v0.7.6 릴리스는 그 벽들을 허무는 것에 관한 것입니다.

실제로 무엇이 고장 나는가

구체적으로 들어가 봅시다. 제가 매주 목격하는 세 가지 실패 모드(failure modes)입니다:

1. 설치 지옥 (Install hell)

zeroclaw skills install my-skill
# → Error: Failed to resolve dependency graph
# → (다른 출력 없음)

당신은 추측할 수밖에 없습니다. 피어 의존성(peer dependency) 충돌인가요? 누락된 Python 버전인가요? 스킬 매니페스트(skill manifest)의 순환 참조(circular reference)인가요? 로더(loader)는 아무것도 알려주지 않습니다.

2. 감사 맹목 (Audit blindness)

zeroclaw skills audit ./my-skill
# → Audit complete. 0 issues found.
# → (스킬이 첫 사용 시 즉시 충돌함)

감사(audit)는 통과했습니다. 하지만 실제 런타임 에러(runtime errors) — 누락된 환경 변수(environment variables), 호환되지 않는 도구 시그니처(tool signatures), 잘못된 출력 스키마(output schemas) — 를 확인하지 않았습니다. 그것은 매니페스트 형식(manifest format)만 확인했습니다. 그게 전부였습니다.

3. 테스트를 하지 않는 테스트 하네스 (Test harness that doesn't test)

zeroclaw skills test ./my-skill
# → Running 3 test cases...
# → All passed.
...

테스트 하네스(test harness)는 모의 데이터(mock data)를 대상으로 당신의 스킬을 실행합니다. 하지만 모의 데이터는 실제 도구 출력(tool outputs)과 일치하지 않습니다. 당신의 스킬은 로컬에서는 통과하지만, 실제 환경(in the wild)에서는 실패합니다.

왜 이런 일이 발생하는가

현재의 아키텍처(architecture)는 스킬을 정적 패키지(static packages)로 취급합니다. skill.json에 메타데이터(metadata)를 정의하고, 몇몇 함수를 가리키고, 그것이 작동할 것이라고 가정합니다. 하지만 스킬은 동적(dynamic)입니다. 그것들은 도구(tools)를 호출합니다. 그것들은 런타임 상태(runtime state)에 의존합니다. 그것들은 샌드박스(sandbox)와 상호작용합니다.

로더(loader)는 런타임 계약(runtime contract)을 검증하지 않습니다. 감사(audit)는 실행을 시뮬레이션(simulate)하지 않습니다. 테스트 하네스(test harness)는 입력을 퍼징(fuzz)하지 않습니다.

그 결과 도처에서 오탐(false positives)이 발생합니다. "내 컴퓨터에서는 잘 작동해"라는 말은 "내 특정 도구와 특정 데이터가 있는 내 특정 환경에서는 잘 작동해"라는 말이 되어버립니다.

v0.7.6 수정 사항

세 가지 개선 사항을 출시합니다. 혁명적인 것은 아닙니다. 그저 처음부터 있었어야 할 기능들입니다.

1. 의존성 해결(dependency resolution)을 포함한 설치

zeroclaw skills install ./my-skill --resolve --verbose
# → 의존성 해결 중... (Resolving dependencies...)
# →   python>=3.10 발견 (system: 3.11.2 ✓)
...

로더(loader)가 설치하기 전에 의존성 트리(dependency tree)를 탐색합니다. 무언가 누락되었다면, 무엇이 왜 누락되었는지 알려줍니다. 더 이상 소리 없는 실패(silent failures)는 없습니다.

2. 런타임 검증(runtime validation)을 포함한 감사(Audit)

zeroclaw skills audit ./my-skill --deep
# → 매니페스트(Manifest): 유효함
# → 도구 시그니처(Tool signatures): 3/3 런타임 스키마(runtime schema)와 일치
...

이제 감사가 실제로 스킬의 도구들을 선언된 스키마(schemas)에 따라 실행합니다. 작성한 내용과 런타임(runtime)이 기대하는 내용 사이의 불일치를 잡아냅니다.

만약 스킬(skill)이 권한이 없는 도구(tool)를 호출하려고 시도하면, 샌드박스(sandbox)가 이를 차단하고 위반 사항을 로그(log)에 기록합니다. 이제 누군가 권한을 변경해서 "내 스킬이 갑자기 왜 안 되지?"라며 의아해하는 일은 없을 것입니다.

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

당신은 스킬을 한 번 작성합니다. 퍼징(fuzzing)을 통해 테스트합니다. 런타임 검증(runtime validation)으로 감사(audit)합니다. 의존성 해결(dependency resolution)을 통해 설치합니다. 그리고 다른 사람의 환경에서도 망가지지 않을 것이라는 확신을 가지고 배포합니다.

v0.7.6 릴리스는 새로운 기능에 관한 것이 아닙니다. 기존 기능들이 형편없지 않게 만드는 것에 관한 것입니다. CLI는 무엇이 잘못되었는지 알려주어야 합니다. 로더(loader)는 문제가 프로덕션(production)에 도달하기 전에 잡아내야 합니다. 테스트 하네스(test harness)는 실제로 테스트를 수행해야 합니다.

만약 zeroclaw skills가 불안정하다고 느껴서 피해 오셨다면 — 다시 시도해 보세요. 마찰(friction)이 제거되고 있습니다. 그리고 만약 여전히 무언가 고장 난다면, 이슈(issue)를 등록해 주세요. 저희는 귀를 기울이고 있습니다.

AI 에이전트(AI agents)를 디버깅하는 것이 마치 매트릭스(The Matrix)를 읽는 것처럼 느껴져서는 안 됩니다.
저희 커뮤니티에서 신뢰할 수 있는 자율 워크플로우(autonomous workflows)를 구축하고 있는 다른 엔지니어들과 함께하세요: TracePilot Discord