darkrishabh/agent-skills-eval

agent‑skills‑eval – Agent Skills를 위한 테스트 러너

이것이 무엇인가

TypeScript/Node.js 라이브러리(CLI + SDK)로, Agent Skill이 언어 모델 기반 에이전트를 실제로 개선하는지 평가할 수 있습니다.
공개 agentskills.io 사양을 따릅니다. 스킬은 SKILL.md와 테스트 케이스를 설명하는 선택적 evals/evals.json을 포함하는 폴더입니다.

작동 방식

스킬 실행 – 러너는 SKILL.md를 대상 모델(스킬이 도움을 주려는 모델)에 보내는 프롬프트에 주입합니다.
기준 실행 – 동일한 프롬프트를 스킬 컨텍스트 없이 보냅니다.
판정 – 두 번째 모델(판정자)이 평가 파일에 정의된 어서션에 따라 두 출력을 평가합니다.
보고서 – 결과는 작업 공간 폴더(iteration‑N/…)에 기록되고 정적 HTML 보고서가 생성됩니다.

주요 기능

기능	중요성
스킬 유무 비교	스킬이 제공하는 실제 향상(또는 부족)을 보여줍니다.
판정자 평가 통과/실패	별도의 LLM을 사용하여 평가의 `assertions`/`expected_output`을 적용하여 재현 가능한 점수를 제공합니다.
빠른 실행 및 CI를 위한 CLI	한 줄 명령 `npx agent-skills-eval …`이 즉시 작동합니다. 플래그는 재현성을 위해 YAML 구성에 직접 매핑됩니다.
TypeScript SDK	평가기를 파이프라인, 대시보드 또는 사용자 정의 도구에 포함할 수 있습니다.
OpenAI 호환 제공자	OpenAI, Anthropic(호환 레이어를 통해), Together, Groq, 로컬 Llama 서버 또는 OpenAI 채팅 API를 지원하는 모든 서비스에서 작동합니다.
사용자 정의 제공자	작은 `Provider` 인터페이스를 구현하여 로컬 서버(Ollama, vLLM 등) 또는 독점 API에 연결합니다.
도구 호출 어서션	원시 텍스트뿐만 아니라 모델이 올바른 함수 호출을 수행했는지 어서션할 수 있습니다.
휴대용 아티팩트	모든 출력, 타이밍, 토큰 사용량, 평가 데이터는 JSON/JSONL로 저장되어 diff 및 다운스트림 분석이 쉽습니다.
정적 HTML 보고서	통과율, 어서션별 추론, 프롬프트/응답 쌍, 리소스 사용량을 시각화하는 자체 포함 사이트(`index.html`).
완전한 agentskills.io 사양 준수	`SKILL.md` 프론트매터, 평가 스키마, 아티팩트 레이아웃을 자동으로 검증합니다.

일반적인 워크플로우

# 1️⃣ 설치(또는 npx 사용)
npm i agent-skills-eval

# 2️⃣ 스킬 폴더에 대해 실행
npx agent-skills-eval ./skills \
  --target gpt-4o-mini \
  --judge  gpt-4o-mini \
  --baseline \
  --strict

명령은 agent-skills-workspace/iteration-1/…을 생성하며 JSON 결과와 report/index.html을 포함합니다.
브라우저에서 HTML 파일을 열어 각 스킬이 대상 모델에 도움이 되었는지 확인합니다.

구성

YAML 파일(agent-skills-eval.yaml)에 모든 옵션(루트 폴더, 작업 공간 경로, 모델 이름, API 기본 URL, 동시성 등)을 저장할 수 있습니다.
CLI 플래그는 항상 YAML 값을 재정의하므로 CI 파이프라인에 편리합니다.

SDK 예제

import { OpenAICompatibleProvider, evaluateSkills, consoleReporter } from "agent-skills-eval";

const provider = new OpenAICompatibleProvider({
  baseUrl: "https://api.openai.com/v1",
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-4o-mini",
  providerName: "openai",
});

await evaluateSkills({
  root: "./skills",
  workspace: "./agent-skills-workspace",
  baseline: true,
  target: { model: provider.model, provider },
  judge:  { model: provider.model, provider },
  onEvent: consoleReporter(),
});

SDK는 이벤트(진행 상황, 평가, 오류)를 스트리밍하며 추가 분석을 위해 JSONL로 기록할 수 있습니다.

사용 시기

스킬 개발자는 자신의 SKILL.md가 실제로 모델 성능을 향상시키는지에 대한 실증적 증거를 원합니다.
CI/CD 파이프라인은 스킬 라이브러리에 대한 자동 회귀 테스트가 필요합니다.
제품 팀은 여러 스킬을 나란히 평가하여 출시할 스킬을 결정합니다.
연구자는 통제된 기준선에서 다양한 프롬프트 또는 도구 호출 전략을 비교합니다.

설치 및 빠른 시작

npm install agent-skills-eval   # 또는 npx 사용
npx agent-skills-eval --help    # 모든 플래그 표시

최소 스킬 폴더는 다음과 같습니다:

my-skill/
├─ SKILL.md          # 설명 + 선택적 메타데이터
└─ evals/
   └─ evals.json    # prompt, expected_output, assertions을 포함한 하나 이상의 테스트 케이스

러너는 SKILL.md를 검증하고(--strict가 설정된 경우) 각 평가를 실행합니다.

확장성

자체 Provider를 구현합니다(name, model, 그리고 {output, latencyMs, inputTokens, outputTokens, costUsd}를 반환하는 비동기 complete(prompt)만 필요) 모든 백엔드를 연결할 수 있습니다.
아티팩트 계약(docs/artifact-contract.md)을 통해 다운스트림 도구는 전체 라이브러리를 가져오지 않고 JSON 결과를 사용할 수 있습니다.

문서 및 커뮤니티

전체 문서: https://darkrishabh.github.io/agent-skills-eval/
소스 코드, 이슈 트래커, 기여 지침은 GitHub에 있습니다.
프로젝트는 MIT 라이선스이며 PR을 통한 확장을 권장합니다.

agent‑skills‑eval은 Agent Skills 생태계에서 빠진 부분을 채웁니다: 단순한 SKILL.md를 측정 가능한 성능 향상으로 바꾸는 재현 가능한 나란히 평가 하네스입니다.

darkrishabh/agent-skills-eval

agent‑skills‑eval – Agent Skills를 위한 테스트 러너

관련