첫 번째 Hermes Agent Skill 구축하기: 전체 가이드

저는 왜 나의 Hermes Agent가 세션 사이의 모든 것을 계속 잊어버리는지 알아내기 위해 20분 동안 터미널을 응시했습니다. 동일한 컨텍스트(Context). 동일한 프롬프트(Prompts). 동일한 좌절감. 그러다 저는 단순한 에이전트를 당신의 작업 방식을 실제로 기억하는 무언가로 바꿔주는 확장 계층(extensibility layer)인 스킬(skills)을 발견했습니다.

제가 저질렀던 실수들—당신은 반복할 필요 없는 실수들—을 포함하여, 처음부터 첫 번째 Hermes 스킬을 구축하는 정확한 방법을 소개합니다. 이 글을 끝낼 때쯤이면, 당신의 에이전트에게 당신의 관례(conventions), 도구(tools), 그리고 워크플로(workflow)를 가르치는 작동 가능한 스킬을 갖게 될 것입니다.

저는 지금까지 6개의 스킬을 게시했습니다. 그중 3개는 무엇이 실제로 작동하는지 알아내기 전까지 처참하게 실패했습니다. 이 가이드는 그러한 실패들을 압축하여 처음부터 끝까지 약 30분 안에 따라 할 수 있는 경로로 만들어 놓았습니다.

스킬(Skills)이란 실제로 무엇인가?

스킬을 에이전트의 절차적 기억(procedural memory)이라고 생각하세요. 그것들은 프롬프트(prompts)가 아니라, 에이전트에게 특정 작업을 당신이 원하는 방식으로 처리하도록 지시하는 구조화된 문서(structured documents)입니다. 이 차이는 매우 중요합니다.

프롬프트는 "테스트를 작성해줘"라고 말합니다. 반면 스킬은 "xdist와 함께 pytest를 사용하고, fixtures를 conftest.py에 넣으며, coverage 임계값과 함께 실행하고, 데이터베이스 마이그레이션이 실패할 때 어떻게 해야 하는지는 다음과 같다"라고 말합니다. 그 차이가 보이시나요?

스킬은 일회성 지침이 아니라 재사용 가능한 절차(reusable procedures)입니다.

Hermes 스킬은 YAML 프론트매터(frontmatter)가 포함된 SKILL.md 파일로 존재합니다. 에이전트가 스킬의 도메인(domain)과 일치하는 작업을 만나면, 전체 지침을 로드하고 이를 따릅니다. 매번, 일관되게 말이죠. 당신이 선호도를 다시 설명할 필요 없이 말입니다.

제가 이 강력함을 처음 깨달은 순간은 모든 대화에서 "스페이스 대신 탭을 사용하는 것을 기억해"라고 입력하는 것을 멈췄을 때였습니다. 저는 그것을 스킬에 넣었습니다. 에이전트는 그냥... 그것을 따랐습니다. 영원히 말이죠. 반복해서 말할 필요가 없는 그 정적의 순간, 그때 저는 스킬의 개념을 완전히 이해했습니다.

SKILL.md의 구조 분석

모든 스킬은 두 부분으로 구성됩니다: 프론트매터(frontmatter, 메타데이터)와 본문(body, 지침). 둘 중 하나라도 잘못되면 스킬이 로드되지 않거나 작동하지 않을 수 있습니다. 저는 첫 번째 스킬인 코드 리뷰 체크리스트를 만들었을 때 trigger_conditions 필드를 오타로 작성해서 계속 무시당하는 것을 겪으며 이를 어렵게 배웠습니다.

---
name: my-awesome-skill
category: productivity
...

프론트매터는 --- 구분 기호로 감싸진 YAML 형식입니다. 본문은 Markdown 형식입니다. 끝입니다. 이것이 전체 구조입니다. 간단하지만 엄격합니다.

전문가 팁: 항상 version과 platforms를 포함하세요. 저는 두 번째 스킬을 만들 때 이들을 생략했고, 동료의 Mac에서 로드되지 않는 이유를 디버깅하느라 40분을 허비했습니다. 그것은 플랫폼 필터 문제였습니다. 저 같은 실수를 하지 마세요.

아무도 알려주지 않는 것이 있습니다: category 필드는 발견 가능성(discovery)에 영향을 미칩니다. Hermes는 이 필드를 사용하여 작업 유형을 감지할 때 관련 스킬을 표시합니다. 만약 코드 리뷰 스킬의 카테고리를

저는 제가 반복하는 것들을 메모 파일에 적어둡니다. 일주일 후에 이를 검토하죠. 세 번 이상 나타나는 항목들이 스킬이 됩니다. 기술적으로는 단순해 보이지만 완벽하게 작동합니다.

2단계: 프런트매터(Frontmatter) 작성하기

스킬을 위한 디렉터리를 만드세요. 저는 ~/.hermes/skills/에 두지만, 프로젝트 로컬 경로를 사용해도 됩니다. 파일 이름은 반드시 SKILL.md여야 하며, skill.md나 README.md가 아닙니다. 정확한 이름입니다. 대소문자를 구분합니다.

---
name: project-setup
category: software-development
...

category 필드를 주목하세요. Hermes는 이를 사용하여 스킬을 정리하고 관련성을 판단합니다. 새로운 카테고리를 만들기보다는 기존 카테고리 중에서 선택하는 것이 나중에 발견하기 더 쉽습니다.

제가 일찍 알았으면 좋았을 한 가지: prerequisites.skills 필드는 단순한 메타데이터가 아닙니다. Hermes는 실제로 사용자의 스킬을 실행할 때 선행 스킬(prerequisite skills)을 먼저 로드합니다. 제 디버깅 스킬은 로깅 스킬에 의존하기 때문에, 저는 그 종속성을 선언하고 Hermes가 순서를 자동으로 처리하게 합니다. 이것이 강력합니다.

3단계: 실제로 작동하는 본문 작성하기 (지침)

여기가 제가 첫 시도 때 잘못했던 부분입니다. 저는 마치 사람 독자를 위한 문서를 작성하듯이 지침을 썼습니다. 모호하고, 추상적이며,

규칙: 모든 지침은 당신의 프로젝트를 한 번도 본 적 없는 주니어 개발자에게 건네줄 수 있는 수준이어야 합니다. 만약 그들이 명확히 하기 위해 질문을 던져야 한다면, 질문할 필요가 없어질 때까지 지침을 다시 작성하세요.

4단계: 트리거(Triggers) 및 조건(Conditions) 추가하기

스킬(Skills)은 모든 메시지에 대해 자동으로 로드되지 않습니다. Hermes에게 언제 스킬을 활성화할지 알려줘야 합니다. 이것이 trigger_conditions 필드이며, 스킬이 마법처럼 느껴지게 만드는 데 있어 가장 중요한 요소입니다.

metadata:
  hermes:
    tags: [project-setup]
...

트리거가 없으면 스킬은 사용되지 않은 채 그대로 방치됩니다. 좋은 트리거가 있다면, 마치 에이전트가 당신의 마음을 읽는 것처럼 느껴집니다. 저의 project-setup 스킬은 제가 "spin up a new project" 또는 "scaffold something for X"라고 말할 때마다 실행되는데, 왜냐하면 그것들이 제가 실제로 사용하는 문구들이기 때문입니다.

저는 일주일 동안 제가 어떤 문구를 사용하는지 추적한 다음, 가장 흔히 사용하는 문구들을 트리거로 추가합니다. 지루하게 들릴 수도 있겠지만, 5분이면 충분합니다. 그리고 무한한 좌절감을 아껴줍니다. 저는 두 번째 스킬을 만들 때 이 단계를 놓쳤습니다. 완벽한 지침을 작성했지만, 제가 선언한 것과 다른 어휘를 사용하는 바람에 스킬이 전혀 활성화되지 않았습니다.

흔한 트리거의 함정: 트리거 키워드를 너무 기술적으로 설정하는 것입니다. 저는 init_repository를 트리거로 설정했었습니다. 하지만 저는 계속 "set up a new project"라고 말했습니다. 단어가 달랐죠. 에이전트는 매칭에 실패했습니다. 공식적인 작업 명칭이 아니라, 당신이 작업 흐름(flow)에 있을 때 실제로 타이핑하는 정확한 단어를 사용하세요.

5단계: 테스트하기 (모두가 건너뛰는 부분)

저는 세 번째 스킬을 테스트도 하지 않고 배포했습니다. 결과는 제 개발 환경에만 존재하는 경로를 하드코딩(hardcoded)했기 때문에 새 기기에서 실패했습니다. 창피한 일이었습니다. 수정하는 데는 3분이 걸렸지만, 마치 3시간 동안 쌓아온 자부심이 증발하는 기분이었습니다. 테스트 없이 배포하지 마세요. 절대로요.

다음은 6개월간의 스킬 작성 경험을 통해 다듬어진 저의 전체 테스트 체크리스트입니다:

Fresh context test (새로운 컨텍스트 테스트): 새로운 세션을 열고 스킬을 실행해 보세요. 이전 대화 맥락 없이도 작동하나요? 이는 "앞서 논의한 바와 같이"와 같은 가정을 잡아내는 데 도움이 됩니다.
Edge case test (예외 케이스 테스트): 전제 조건이 설치되지 않았을 때는 어떻게 되나요? 파일이 이미 존재할 때는요? 네트워크가 끊겼을 때는요? 사용자가 약간 예상치 못한 말을 할 때는 어떻게 되나요?
Cross-platform test (교차 플랫폼 테스트): 여러 플랫폼을 지정했다면 각 플랫폼에서 테스트하세요. 경로 구분자(Path separators), 셸 명령(Shell commands), 환경 변수(Environment variables)는 서로 다릅니다.
Interference test (간섭 테스트): 로드된 다른 스킬과 충돌하나요? 예전에 코드를 서로 다르게 포맷팅하려고 시도하는 두 개의 스킬이 있었던 적이 있습니다. 결과는... 엉망이었습니다.
Repeat test (반복 테스트): 연속으로 3번 실행해 보세요. 일관된 결과를 생성하나요? 스킬 지침(Skill instructions)에서의 비결정성(Non-determinism)은 소리 없는 살인마와 같습니다.

제가 가장 좋아하는 테스트 트릭: 스킬을 실행한 다음, 의도적으로 약간 잘못된 입력을 줍니다. 좋은 스킬은 오류를 우아하게 처리하고 사용자에게 무엇이 잘못되었는지 알려줍니다. 나쁜 스킬은 조용히 충돌하거나 쓰레기 값(Garbage)을 생성합니다. 두 경우 모두 배포 전에 발견한다면 수정 가능합니다.

실패한 3가지 스킬 (그리고 그들이 내게 가르쳐준 것)

스킬 #1: "Universal Code Reviewer (범용 코드 리뷰어)." 너무 광범위했습니다. 보안, 성능, 스타일, 아키텍처 등 모든 것을 리뷰하려고 시도했지만, 제대로 해내는 것은 아무것도 없었습니다. 지침(Instructions)들이 서로 모순되었습니다. 교훈: 하나의 스킬에는 하나의 도메인(Domain)만 담으세요. 이를 대체한 저의 "React Testing Reviewer" 스킬은 명확하고 좁은 초점을 가지고 있기 때문에 10배 더 잘 작동합니다. 구체성(Specificallyness)은 제약이 아니라 초능력입니다.

스킬 #2: "데이터베이스 마이그레이션 어시스턴트 (Database Migration Assistant)." PostgreSQL에 맞춰 하드코딩되었지만, 해당 의존성 (dependency)을 명시하지 않았습니다. MySQL에서는 조용히 실패했습니다. 에이전트는 그냥... 아무것도 하지 않았습니다. 오류도 없었습니다. 아무것도요. 교훈: 프론트매터 (frontmatter)에 항상 전제 조건과 가정을 명시하세요. 그리고 본문에도요. 스킬이 작동하는 데 무엇이 필요한지 명확하게 밝히세요.

스킬 #3: "문서 생성기 (Documentation Generator)." 소스 코드를 실제로 읽지 않고 주석으로부터 추론했기 때문에, 완전히 틀린 내용을 담은 아름다운 문서를 생성했습니다. 문서는 권위 있어 보였지만, 존재하지 않는 동작을 설명하고 있었습니다. 교훈: 스킬은 속임수를 쓸 수 없습니다. 읽기, 확인, 검증이라는 실제 작업을 수행해야 합니다. 사실로 위장된 가정은 정보가 없는 것보다 더 나쁩니다.

각 실패를 진단하고 수정하는 데 약 10분 정도가 걸렸습니다. 처음에 더 구체적이고, 가정에 대해 더 정직하며, 테스트를 더 철저히 했다면 아낄 수 있었던 10분이었습니다. 요즘 저는 스킬 작성 시간의 10%를 테스트를 위해 할당합니다. 그것은 제가 사용하는 시간 중 가장 가치 있는 10%입니다.

심화: 스킬 체이닝 (Chaining Skills Together)

3~4개의 스킬이 안정적으로 작동하기 시작하면, 이를 워크플로 (workflows)로 체이닝 (chaining)할 수 있습니다. 새로운 기능을 위한 저의 전형적인 워크플로는 다음과 같습니다:

project-setup: 디렉토리 구조를 스캐폴딩 (scaffolds)하고 파일을 생성합니다.
test-driven-development: RED-GREEN-REFACTOR 사이클을 강제합니다.
requesting-code-review: 보안 스캔 (security scan)과 품질 게이트 (quality gates)를 실행합니다.

마법 같은 점은 각 스킬이 자신의 도메인을 전문적으로 처리한다는 것입니다. 제가 보안 스캔을 실행하는 것을 기억할 필요가 없습니다. 코드 리뷰 스킬이 그것을 수행하니까요. 테스트 구조를 기억할 필요가 없습니다. TDD 스킬이 이를 강제하니까요. 린팅 (linting)을 확인할 필요도 없습니다. 그것은 프리 커밋 (pre-commit) 스킬에 내장되어 있습니다.

하지만 단순하게 시작하세요. 무언가를 체이닝하기 전에 하나의 스킬을 완벽하게 작동시키세요. 체이닝은 성공과 실패를 모두 증폭시킵니다. 평범한 스킬 3개가 연결된 체인은 끔찍한 경험을 만들어냅니다. 단 하나의 뛰어난 스킬은 훌륭한 경험을 만들어냅니다.

선행 조건(prerequisite) 시스템이 순서를 처리합니다. Hermes가 저의 코드 리뷰(code-review) 스킬을 로드할 때, 먼저 선행 조건으로 선언된 저의 로깅(logging) 스킬을 로드한 다음, 코드 리뷰 지침(instructions)을 로드합니다. 저는 이에 대해 고민할 필요가 없습니다. 에이전트가 의존성 그래프(dependency graph)를 알아서 처리하기 때문입니다.

제가 여전히 목격하는 흔한 실수들 (제 실수 포함)

텍스트의 벽을 작성하는 것. 만약 스킬 본문이 200줄을 넘어간다면, 아마 너무 많은 일을 하고 있는 것일 겁니다. 이를 분리하세요. 저의 가장 긴 스킬은 140줄입니다. 대부분은 60~80줄 사이입니다.