Skill 품질 관리를 위한 Rubric 설계와 시스템 구현 (새 탭에서 열림)

Skill은 코딩 에이전트가 개발 과정에서 호출해 사용하는 문서형 도구이므로, 내용이 좋아도 호출되지 않으면 아무런 가치가 없다. 글은 Skill 품질을 6개 섹션 30개 항목으로 평가하고, 형식처럼 결정적으로 검증할 수 있는 항목은 규칙 기반으로, 호출 적합성처럼 의미 판단이 필요한 항목은 LLM 기반으로 분리해야 한다고 주장한다. 특히 BLOCKER가 하나라도 있으면 F 등급으로 처리해 Merge 차단 여부를 단순하게 판단하는 것이 핵심이다.

Skill 평가가 어려운 이유

• Skill은 컴파일이나 테스트처럼 명확한 통과·실패 기준이 없다.
• 결함이 있어도 호출되지 않거나, 호출돼도 효과가 없는 상태로 조용히 남을 수 있다.
• 대표적인 문제는 다음 두 가지다.
  • 트리거 실패: 호출 조건을 본문에 작성하고 description에는 적지 않아 에이전트가 Skill을 호출하지 못하는 문제
  • 형식 위반: name이 kebab-case가 아니거나, name과 폴더명이 달라 Skill 자체가 인식되지 않는 문제

규칙 기반 검사와 모델 기반 검사의 분리

• 형식·구조처럼 결과가 명확한 항목은 정규식, 카운트, AST 파싱 등 결정적 도구로 검사한다.
• 트리거의 의미나 설명의 충분성처럼 문맥 판단이 필요한 항목은 LLM이 평가한다.
• 30개 평가 항목은 다음처럼 나뉜다.
  • 규칙 검사 17개
  • 모델 검사 13개
• 역할을 섞으면 문제가 발생한다.
  • 결정적 결함을 LLM에 맡기면 애매한 상태를 통과시키는 False Negative가 생긴다.
  • 의미적 판단을 정규식으로 처리하면 표현의 다양성을 놓쳐 False Positive가 늘어난다.
• 규칙 검사는 비용이 거의 없어 모든 PR에서 실행할 수 있고, LLM 검사는 규칙 검사를 통과한 Skill에만 적용해 비용을 줄인다.

6개 섹션 30개 항목의 평가 구조

• 각 항목은 BLOCKER, MAJOR, MINOR 심각도를 가진다.
• 결과는 S부터 F까지 5단계 등급으로 표시한다.
• BLOCKER가 하나라도 있으면 무조건 F다.
• 세부 등급은 작성자에게 상태를 알려주는 신호로 사용하고, 실제 Merge 차단은 F 여부만으로 결정한다.
• 이 방식은 등급의 미세한 차이를 두고 불필요하게 논쟁하는 일을 줄인다.

타당성: Skill이 정말 필요한가

• Skill을 만들 만한 가치가 있는지 평가한다.
• 핵심 질문은 다음과 같다.
  • 반복적으로 발생하는 작업인가?
  • 코딩 에이전트가 일반적인 지시만으로 처리하기 어려운가?
  • Skill로 만들어 제공할 때 지속적인 이점이 있는가?
• 일회성 작업이나 에이전트에게 그대로 시켜도 되는 작업은 Skill로 만들 필요가 없다.
• 다른 섹션이 이미 만들어진 Skill의 품질을 점검한다면, 타당성 섹션은 애초에 만들지 말았어야 할 Skill을 걸러내는 역할을 한다.
• 이 섹션에는 3개 항목이 있으며 모두 MAJOR 수준이다.

구조: 형식 오류를 결정적으로 차단

• 구조 섹션은 8개 항목으로 구성되며, 그중 5개가 BLOCKER다.
• 예시로 다음을 검사한다.
  • frontmatter 존재 여부와 YAML 파싱 가능 여부
  • name의 kebab-case 준수 여부
  • name과 폴더명 일치 여부
  • description 길이가 1~1024자 범위인지 여부
  • 본문에 허용되지 않은 XML 태그가 포함됐는지 여부
• 구조 검사는 전부 규칙 기반으로 처리하며 LLM을 사용하지 않는다.
• frontmatter 자체가 파싱되지 않는 경우에는 즉시 반환하지만, 그 외 오류는 가능한 한 끝까지 검사한다.
• 여러 오류를 한 번에 반환해 PR 작성자가 한 번의 피드백으로 모두 수정할 수 있도록 설계했다.
• 형식 검사는 정교함보다 매번 동일한 결과를 내고 누락 없이 동작하는 것이 중요하므로, 단순한 구현을 유지한다.

트리거: Description에 WHAT과 WHEN을 함께 작성

• 에이전트는 Skill을 호출할지 결정할 때 이름과 description만 본다.
• Skill 본문은 호출이 결정된 뒤에 읽힌다.
• 따라서 본문에만 다음과 같은 조건을 작성하면 호출되지 않는다.
  • “언제 사용하는가”
  • “어떤 상황에서 호출하는가”
  • Use when ...
• description에는 Skill이 무엇인지뿐 아니라 언제 사용해야 하는지도 포함해야 한다.
• 트리거 섹션은 6개 항목으로 구성되며, 본문에만 트리거 조건이 있는 경우 BLOCKER로 처리한다.
• 처음에는 when, use when, “할 때”, “사용 시” 같은 표현을 정규식으로 검사했지만 한계가 있었다.
  • 한국어 표현을 놓치면 잘못된 BLOCKER가 발생한다.
  • 이모지, 완곡한 표현, 다양한 문장 구조를 모두 규칙으로 포괄하기 어렵다.
• 최종적으로는 “Description이 본문의 트리거 조건을 의미적으로 충분히 포함하는가?”를 LLM이 판단하도록 전환했다.

운영 방식과 설계 원칙

• BLOCKER 구조 오류는 LLM 평가 전에 차단해 불필요한 모델 호출을 줄인다.
• 구조 검사 결과를 오류 목록으로 한 번에 제공해 수정 비용을 낮춘다.
• 복잡한 전략 패턴 같은 확장 설계보다 현재 요구사항에 맞는 단순한 검사 코드를 우선한다.
• 규칙 기반과 모델 기반의 책임 영역을 명확히 나누는 것이 Rubric 전체의 핵심 원칙이다.

실무에서는 먼저 frontmatter, 이름 규칙, 폴더 구조 같은 형식 검사를 자동화하고, 이를 통과한 Skill에 대해서만 트리거 적합성과 내용 품질을 LLM으로 평가하는 방식을 권장한다. 특히 description에는 Skill의 기능(WHAT)과 사용 시점(WHEN)을 모두 명시해야 하며, BLOCKER 하나만으로도 배포나 Merge를 막도록 운영하면 호출되지 않는 Skill을 조기에 줄일 수 있다.