스킬을 만들었는데, 정말 재사용할 수 있을까? Skill X-Ray가 자기 자신을 검사한 이틀

📝 한줄 요약

AI 스킬 문서를 읽고 구조·선택 조건·작업 순서·검증 기준을 보여주는 Skill X-Ray를 만들었다. 처음에는 특정 스킬에 맞춘 시각화에 가까웠지만, 자기 자신을 분석하면서 하드코딩과 파일 충돌을 찾아냈고, 서로 다른 스킬에도 적용할 수 있는 검증형 도구로 고쳤다.

바쁘시면 이것만 읽어도 돼요:

• 스킬 문서는 길고 기술 용어가 많아서, 읽는 것만으로는 언제 선택되고 무엇을 검증하는지 파악하기 어려웠다.

• 처음에는 구조를 레고처럼 보여주는 화면을 만들었지만, 사용자가 궁금한 것은 화면 기능보다 그 안의 실제 의미였다.

• 한국어 V1 주석판을 거쳐, 실제 내용·구체 행동·사용 예·영어 표현·오해 방지를 함께 설명하는 V2로 발전시켰다.

• Skill X-Ray가 자기 자신을 분석하자, 범용 도구라는 설명 뒤에 남아 있던 특정 대상용 하드코딩이 드러났다.

• 대상별 해설을 데이터로 분리하고, 원본·주석·이전 버전의 해시와 브라우저 동작을 함께 검증했다.

• 이후 write-post와 포정해우처럼 구조가 전혀 다른 스킬에도 V2를 적용해 전체 검증을 통과했다.

• 이 작업에서 가장 크게 배운 것은 "화면을 만들었다"와 "검증 가능한 도구를 만들었다"는 전혀 다른 말이라는 점이었다.

🎯 이런 분들께 도움돼요

• AI 스킬을 만들었지만 문서가 실제로 어떻게 작동하도록 설계됐는지 한눈에 보고 싶은 사람

• 영어와 기술 용어 때문에 다른 사람이 만든 스킬을 이해하기 어려운 비개발자

• AI가 만든 결과물을 예쁜 화면에서 끝내지 않고 테스트와 증거까지 묶고 싶은 사람

• 한 번 성공한 작업을 다음 대화와 다른 프로젝트에서도 다시 쓰고 싶은 사람

😫 문제 상황: 스킬 문서는 있는데 구조가 보이지 않았다

이 작업의 출발점에는 두 문제가 함께 있었다. 결과물은 이미 있었지만 매번 프로젝트 안에서 파일과 절차를 다시 골라야 했고, 영어와 기술 용어 중심의 분석 화면은 비개발자가 실제 의미를 이해하기 어려웠다. 그래서 목표도 두 가지였다. 분석을 다시 부를 수 있는 스킬로 만들고, 그 결과를 한국어 심층 해설로 읽을 수 있게 만드는 것이었다.

Hermes의 스킬은 단순한 프롬프트 모음이 아니다. 어떤 요청에서 선택할지, 무엇을 입력으로 받을지, 어떤 순서로 처리할지, 언제 완료라고 말할지까지 적힌 작업 계약에 가깝다.

문제는 이 계약이 긴 SKILL.md 안에 섞여 있다는 점이었다. 제목과 목록은 많았지만 다음 질문에 바로 답하기는 어려웠다.

• 이 스킬은 어떤 요청에서 선택되는가?

• 반대로 언제 사용하면 안 되는가?

• 문서에 적힌 작업 순서와 실제 실행 증거는 어떻게 다른가?

• 결과물은 무엇이며 무엇을 확인해야 완료인가?

• 별도 참고 파일과 도구 의존성은 실제로 존재하는가?

처음에는 원문을 읽고 사람이 직접 정리하면 된다고 생각할 수 있다. 하지만 스킬마다 같은 일을 반복해야 했고, 정리하는 사람에 따라 해석도 달라질 수 있었다. 무엇보다 선언된 절차를 실제 실행된 사실처럼 잘못 말할 위험이 있었다.

그래서 스킬을 하나의 분석 대상으로 보고, 구조와 증거의 경계를 같은 형식으로 보여주는 도구가 필요했다.

🌱 처음에는 무엇을 놓쳤나

첫 시도는 "잘 보이게 만드는 것"에 가까웠다. 스킬을 시작 조건, 입력 재료, 작업 순서, 도구, 결과물, 품질 검사 블록으로 나누고 레고처럼 배치했다. 구조를 훑기에는 좋았다.

그런데 사용자의 반응은 다른 곳을 가리켰다.

난 여기서 정밀정보가 무엇을 의미하는지를 잘 모르겠어. 여러 용어들과 여러 개념들을 알기 쉽게 풀어서 설명해주는 매뉴얼이 필요해.

처음에는 일반 용어사전을 만들었다. 이것도 방향이 빗나갔다. 사용자가 원한 것은 별도 교과서가 아니라, 현재 화면의 각 항목이 이 스킬에서 무슨 뜻인지 바로 옆에서 설명해주는 해설이었다.

X-Ray 정밀원본에 나오는 설명들이 영어로 다 되어 있는데, 그것들을 한국어로 설명해주는 친절한 해설서를 만들어줘.

여기서 첫 번째 교훈을 얻었다. 기능을 설명하는 것과 내용을 읽어주는 것은 다르다. 탭이 무엇을 하는지 알려주는 것만으로는 부족했다. 그 탭 안에 적힌 숫자와 판정과 원문이 왜 그런 값이 됐는지까지 연결해야 했다.

🛠️ 사용한 도구

• Hermes Agent와 TARDIS: 요구사항 정리, 스킬화, 산출물 조율

• Python 기반 분석기: SKILL.md 구조와 증거를 JSON·Markdown·HTML로 변환

• 자체 포함형 HTML: 외부 서비스 없이 탭·검색·펼치기 기능 제공

• Playwright Chromium: 데스크톱·모바일 화면과 실제 상호작용 검증

• SHA-256과 manifest: 원본·주석·이전 버전·최종 산출물의 무결성 확인

🔧 작업 과정

구조를 보여주는 화면에서, 내용을 읽어주는 V1으로

정밀원본의 순서를 바꾸지 않고 Overview → Routing → Structure → Runtime → Doctor → Evidence를 그대로 유지했다. 각 필드와 숫자 옆에는 세 가지를 붙였다.

1. 쉬운 뜻

2. 현재 보고서에서의 의미

3. 흔히 할 수 있는 오해

이 방식은 원문과 해설을 오가며 읽을 수 있다는 장점이 있었다. 하지만 모바일 검증에서 3열 표가 한 글자씩 줄바꿈되는 문제가 나왔다. 데스크톱에서 멀쩡해 보인다는 이유로 완료할 수 없었다. 표를 모바일용 세로 카드로 바꾸고 다시 캡처해 확인했다.

이때부터 스크린샷은 장식이 아니라 검증 기록이 됐다.

V1을 지우지 않고 V2를 새 방으로 만들다

사용자는 다음 단계에서 요구를 더 구체화했다.

기능 뿐 아니라 실제로 해당 내용이 무엇인지, 해당 스킬이 구체적으로 어떤 기능을 하는지, 거기에 적힌 영어 표현은 구체적으로 무엇인지도 알고 싶어.

V2에는 첫 화면부터 스킬의 입력·처리·출력·하지 않는 일을 넣었다. 그리고 원본의 모든 섹션마다 다음 내용을 붙였다.

• 원문이 실제로 말하는 내용

• 스킬이 선언한 구체 행동

• 그 행동을 이해할 수 있는 사용 예

• 원문에 실제로 등장하는 영어 표현

• 선언과 실행 증거를 혼동하지 않기 위한 주의사항

이전 버전을 덮어쓰지는 않았다. V1의 해시를 기록하고 V2에서 다시 확인했다. "더 발전시켜 달라"는 요청을 "이전 결과를 없애도 된다"로 해석하지 않았기 때문이다.

도구를 스킬로 만들면서 완료 조건을 다시 정의하다

로컬 프로젝트에는 이미 분석기와 여러 화면, 검증기가 있었다. 하지만 다음 실행 때는 사람이 파일과 명령을 다시 골라야 했다.

그러면 이것을 스킬로 만들어줘.

여기서 코드를 복사한 두 번째 구현을 만들지 않았다. 기존 프로젝트를 원본으로 두고, Hermes 스킬은 적절한 분석 화면을 고르고 실행 순서를 조율하는 얇은 어댑터로 만들었다.

각 실행은 새 타임스탬프 폴더에 저장했다. 검증 JSON 중 하나라도 PASS가 아니면 완료로 보고하지 않도록 막았다. 새 Hermes 세션에서도 처음부터 불러와 같은 결과를 낼 수 있는지 확인했다.

첫 새 세션 검증은 실패했다. 현재 대화에서는 알아서 이해하던 작업 순서를 새 세션의 스킬 판독기가 workflow로 인식하지 못했다. 제목 구조를 고친 뒤 다시 불러와 검증했다. 이 실패 덕분에 "지금 대화에서 되는 도구"와 "다음 대화에서도 재사용되는 스킬"의 차이가 분명해졌다.

자기 자신을 분석하자 범용이라는 착각이 깨졌다

skill x-ray도 skill로 만들어진 거지?

설치된 Skill X-Ray를 다시 분석 대상으로 넣었다. 이른바 self-X-ray였다. 여기서 예상하지 못한 문제가 나왔다.

화면은 다른 스킬도 분석하는 것처럼 보였지만, 일부 렌더러와 검증기는 최초 개발 대상의 섹션 개수와 문구를 고정값으로 갖고 있었다. "범용"이라는 설명과 실제 구현 사이에 틈이 있었던 셈이다.

검증값이 현재 보고서의 실제 섹션·판정·출처 개수를 읽도록 고쳤다. 처음 사용한 대상도 다시 실행해 회귀가 없는지 확인했다. 자기 분석은 멋진 데모가 아니라, 도구가 자기 가정을 들춰내는 회귀시험이 됐다.

V2 설명을 화면 코드 밖으로 꺼내다

그럼 v2 정밀주석판은?

더 큰 문제는 V2였다. 최초 대상의 한국어 설명이 화면 생성 코드 안에 직접 들어 있었다. 다른 스킬을 넣어도 화면은 만들어질 수 있지만, 해설 내용은 틀릴 수 있었다. 가장 위험한 종류의 성공이었다. 보기에는 정상인데 의미가 거짓인 결과였다.

대상별 해설을 별도의 annotations 데이터로 분리했다. 이 데이터에는 대상 이름과 원문 해시, 원본 섹션 순서, 실제 내용, 구체 행동, 사용 예, 영어 표현, 오해 방지, 용어사전을 담았다.

범용 렌더러는 이 데이터를 읽어 화면을 만들고, validator는 다음을 확인했다.

• 대상 이름과 원본 해시가 맞는가

• 모든 원본 섹션이 정확히 한 번씩, 같은 순서로 표현됐는가

• 영어 표현이 실제 원문에 존재하는가

• V1 파일이 바뀌지 않았는가

• 탭·검색·펼치기 기능이 브라우저에서 동작하는가

• 데스크톱과 모바일에서 내용이 화면 밖으로 넘치지 않는가

이제 V2는 "예쁘게 쓴 한국어 설명"이 아니라 원본과 연결된 데이터 계약이 됐다.

비동기 작업의 성공 보고보다 파일 해시가 더 정확했다

가장 당황스러운 문제는 마지막에 생겼다. 고품질 주석과 빠른 검증용 임시 주석이 같은 파일명에 쓰였다. 두 작업은 모두 성공했다고 보고했지만, 나중에 끝난 임시 작업이 먼저 만든 고품질 파일을 덮어썼다.

파일 크기와 해시를 비교하지 않았다면 성공한 줄 알고 끝냈을 것이다. 이전 결과를 삭제하지 않고 고품질본을 별도 경로에 다시 만든 뒤, 새로운 출력 폴더에서 전체 과정을 재실행했다.

여기서 배운 원칙은 단순했다. 여러 에이전트가 같은 산출물을 만들 때는 "완료했습니다"라는 메시지보다 쓰기 경로, 파일 크기, 최종 해시가 더 믿을 만하다.

✅ 결과: 하나의 예시가 서로 다른 스킬을 읽는 도구가 됐다

Skill X-Ray는 현재 다음 산출물을 한 묶음으로 만든다.

• 기계가 다시 읽을 수 있는 JSON

• 사람이 검토하기 쉬운 Markdown

• 영어 정밀 HTML

• 한국어 LEGO 구조도

• 초보자용 설명판

• 원문 순서를 보존한 V1 주석판

• 대상별 실제 내용을 해설하는 V2 심층판

• 데스크톱·모바일 스크린샷과 validation JSON

• 모든 파일의 경로와 해시를 기록한 manifest

Before vs After

실제 검증 범위

canonical 회귀 테스트도 5개 모두 통과했다. 세 대상의 V2에서 탭 전환, 전체 펼치기·접기, 검색·초기화, 링크, V1 해시 보존, 콘솔·페이지 오류, 데스크톱·모바일 수평 넘침을 확인했다.

이 숫자들은 스킬의 우수성을 점수화한 것이 아니다. 각 원본을 빠짐없이 표현하고 검증했다는 범위 기록이다.

ALT

첫 번째 기록 값 - 스크린샷

💬 이 과정에서 배운 AI 활용 팁

효과적이었던 것

1. 원본과 해설을 분리하면 화면을 다시 만들지 않고도 다른 대상에 적용할 수 있다.

2. 새 세션에서 다시 실행해야 현재 대화의 숨은 문맥에 기대는 부분을 찾을 수 있다.

3. 결과 파일뿐 아니라 validation JSON과 해시를 함께 남겨야 완료를 재확인할 수 있다.

4. 이전 버전을 지우지 않으면 개선 전후를 직접 비교할 수 있다.

5. "모른다"와 "실패했다"를 구분해야 한다. runtime log 미제공은 실행 실패가 아니라 관찰 범위 밖이다.

이렇게 하면 안 돼요

1. 특정 대상에 맞춘 문구와 개수를 범용 검증 규칙처럼 고정하면 안 된다.

2. HTML이 열렸다는 이유만으로 기능이 정상이라고 판단하면 안 된다.

3. 스크린샷 파일이 있다는 것과 사람이 화면을 확인했다는 것을 같은 말로 쓰면 안 된다.

4. 여러 에이전트가 같은 경로에 쓰게 두고 완료 메시지만 믿으면 안 된다.

5. 문서에 적힌 workflow를 실제로 성공한 작업처럼 표현하면 안 된다.

🌍 다른 업무에 적용한다면?

같은 방식은 계약서나 운영 절차에도 적용할 수 있다. 원문을 그대로 보존하면서 각 조항 옆에 쉬운 뜻, 실제 행동, 사용 예, 오해 방지를 붙이고, 모든 조항이 한 번씩 반영됐는지 검사할 수 있다.

조직의 표준운영절차를 분석할 때는 트리거·담당자·승인·기록·예외 경로를 구조화하고, 문서에 적힌 절차와 실제 로그에서 확인된 절차를 분리할 수 있다. "규정에 있다"와 "현장에서 실행됐다"를 구분하는 원칙은 스킬 분석 밖에서도 그대로 유효하다.

🤝 배워서 남 주기

Skill X-Ray를 만들면서 가장 아까웠던 것은 분석 결과보다 반복해서 얻은 검증 원칙이었다. 다른 사람이 같은 시행착오를 되풀이하지 않도록 다음을 재사용 가능한 형태로 남겼다.

• 대상 스킬을 분석하는 표준 실행 스킬

• V2 annotations 데이터 형식

• 데스크톱·모바일 브라우저 검증 절차

• 원본과 이전 버전을 보존하는 해시·manifest 규칙

• 선언과 실행 증거를 구분하는 해석 규칙

• 이 제작 과정과 실패를 기록한 DEVLOG

독자는 코드를 읽지 않아도 "이 스킬은 무엇을 받고, 무엇을 하고, 무엇을 만들며, 어디까지 증명됐는가"를 확인할 수 있다.

🕊️ 누구의 어려움을 줄일 수 있나

스킬을 만든 사람은 자신이 쓴 문서를 잘 안다. 처음 보는 사람은 그렇지 않다. 긴 영어 문서와 기술 용어 앞에서 사용을 포기하거나, 내용을 다 이해하지 못한 채 설치할 수 있다.

Skill X-Ray는 이 간극을 줄인다. 비개발자는 구조와 실제 예를 통해 스킬을 이해하고, 제작자는 누락된 선택 조건이나 검증 기준을 발견할 수 있다. 팀은 "실행됐다고 주장할 수 있는 범위"를 같은 증거로 확인할 수 있다.

🚀 앞으로의 계획

다음 단계는 단순히 분석 대상을 늘리는 것이 아니다.

• 실제 runtime log를 연결해 선언된 workflow와 관찰된 실행을 비교한다.

• 자주 발견되는 라우팅·검증 결함을 자동 수정하지 않고 수리 후보로 제안한다.

• 여러 스킬의 관계를 묶어 Agent X-Ray 수준의 흐름 지도로 확장한다.

• V2 주석 작성 품질을 재사용 가능한 검토 기준으로 더 단단하게 만든다.

자동 수리는 신중하게 접근할 예정이다. 구조를 잘못 읽은 도구가 스킬 원문까지 바꾸면 진단보다 큰 문제를 만들 수 있기 때문이다.

📋 재사용 가능한 프롬프트

프롬프트 1: 스킬의 구조와 증거 경계 분석

[스킬 이름 또는 SKILL.md 경로]를 분석해 주세요. 사용 조건, 사용하면 안 되는 조건, 입력, 처리 순서, 출력, 도구·참고 파일, 검증 기준을 분리해 주세요. 문서에 선언된 내용과 실제 실행 로그에서 관찰된 사실을 섞지 말고, 증거가 없으면 UNKNOWN으로 표시해 주세요. 결과는 비개발자도 이해할 수 있는 한국어 설명과 근거 위치를 함께 제시해 주세요.

프롬프트 2: 기존 분석을 대상별 V2 심층판으로 확장

기존 [V1 분석 파일]을 보존한 채 [대상 스킬] 전용 V2를 만들어 주세요. 원본의 모든 섹션을 같은 순서로 한 번씩 반영하고, 각 섹션에 실제 내용, 구체 행동, 사용 예, 원문 기반 영어 표현, 오해 방지를 붙여 주세요. 대상 원본·주석·V1의 해시를 기록하고, 탭·검색·펼치기·링크·데스크톱·모바일 overflow·브라우저 오류를 실제로 검증해 주세요.