huggingface/upskill

에이전트의 트레이스(traces)를 기반으로 에이전트 기술(skills)을 생성하고 평가합니다. 교사 모델(teacher models, 비용이 높고 느림)을 사용하여 학생 모델(student models, 비용이 저렴하고 빠름)이 더 어려운 작업을 안정적으로 수행할 수 있도록 기술을 생성합니다.

팁

UPskill v2 - 권장되는 기본 설정 파일은 이제 Hugging Face Jobs에서 평가를 실행합니다. 작업 생성 및 결과 캡처를 위해 HF_TOKEN을 설정하고 --artifact-repo <dataset-name>을 사용해야 합니다.

upskill 설치:

uv pip install upskill
# 또는 단순히 uv 사용
uvx upskill

새로운 기술 생성

upskill generate "write good git commit messages"
# 또는 이전 에이전트 트레이스 기반
upskill generate "document the pattern" --from ./trace.md
...

교사 모델(teaching model)로 기술을 생성하고 학생 모델(student model)에서 이를 평가합니다.

upskill generate "write good git commit messages" --model sonnet --eval-model haiku

기술에 대해 모델 세트를 벤치마크합니다.

upskill eval ./skills/git-commit-messages/ -m haiku -m sonnet
# 로그가 터미널에 보기 좋게 출력됩니다

나중에 결과 확인.

upskill runs --skill git-commit-messages

이 저장소는 fast-agent에서 영감을 받은 CI 흐름을 사용하며, 포맷(format), 린트(lint), 타입 체크(typecheck), 테스트(test) 단계가 분리되어 있습니다.

개발 의존성 설치:

uv sync --extra dev

로컬에서 품질 게이트(quality gates) 실행:

uv run scripts/format.py
uv run scripts/lint.py
uv run scripts/typecheck.py
...

또는 전체 시퀀스를 실행하기 위해 헬퍼 스크립트를 사용하십시오:

uv run scripts/check.py

uv sync --extra dev를 포함하려면 --sync를 추가하고, 더 빠른 정적 분석만을 수행하려면 --skip-tests를 사용하십시오.

체크를 다시 실행하기 전에 자동 포맷팅을 수행하려면:

uv run --extra dev scripts/format.py --write

현재 강제되는 표준:

• 포맷팅을 위한 ruff format --check
• 스타일, 임포트(imports), 현대화(modernization), bugbear, 단순화(simplify), 임포트 위생(import-hygiene) 규칙을 위한 ruff check
• Ruff를 통한 순환 복잡도(cyclomatic complexity) C90 (max-complexity = 15 적용)
• src, tests, scripts 전반에 걸친 type check
• src/ 내의 중복 코드를 표시하기 위한 scripts/cpd.py --check를 통한 pmd cpd
• 테스트 스위트를 위한 pytest

CI 강제 적용(enforcement)은 .github/workflows/ci.yml에 정의되어 있으며,

main 브랜치를 대상으로 하는 push 및 pull request 시 실행됩니다.

upskill은 명시적인 모델 역할이 부여된 별도의 단계(phases)를 사용합니다:

Skill generation (기술 생성): SKILL.md 생성 및 개선

Test generation (테스트 생성): 합성 평가 케이스(synthetic evaluation cases) 생성

Evaluation (평가): 평가 모델(evaluator model)을 대상으로 테스트 실행

Benchmark (벤치마크): 여러 실행/모델에 걸친 반복 평가

명령어별 모델 플래그(Model flags):

Command	Flag	Meaning
generate	--model	기술 생성/개선 모델
generate	--test-gen-model	테스트 생성 모델 재정의
generate	--eval-model	선택 사항인 추가 교차 모델 평가 단계
eval	-m/--model	평가 모델(evaluator model) (반복 가능)
eval	--test-gen-model	테스트 생성 모델 재정의 (테스트가 생성될 때)
benchmark	-m/--model	벤치마크할 평가 모델
benchmark	--test-gen-model	테스트 생성 모델 재정의 (테스트가 생성될 때)
runs / plot	-m/--model	과거 결과 필터링 전용

upskill eval 명령어에서 여러 개의 -m 값을 전달하거나 --runs > 1을 전달하면 항상 **벤치마크 모드(benchmark mode)**로 진입합니다.

벤치마크 모드에서는 베이스라인 비교(baseline comparison)가 항상 꺼져 있으므로, --no-baseline 옵션은 중복됩니다.

자동 평가 및 개선을 통해 작업 설명(task description)으로부터 기술(skill)을 생성합니다.

upskill generate TASK [OPTIONS]

Arguments (인자):

TASK

• 기술이 가르쳐야 할 내용에 대한 설명

Options (옵션):

-e, --example

• 입력 -> 출력 예시 (반복 사용 가능)

-f, --from PATH

• 기존 기술 디렉토리 또는 에이전트 트레이스(agent trace) 파일로부터 개선 (자동 감지)

-m, --model MODEL

• 기술 생성 모델 (예: 'sonnet', 'haiku', 'anthropic.claude-sonnet-4-20250514')

--test-gen-model MODEL

• 이번 실행에 대한 테스트 생성 모델 재정의

-o, --output PATH

• 기술 출력을 위한 디렉토리

--no-eval

• 평가 및 개선 건너뛰기

--eval-model MODEL

• 기술을 평가할 다른 모델

--executor [local|jobs]

• 평가/개선 (evaluation/refinement)을 위한 실행 백엔드 (Execution backend); 설정 (config)을 덮어씁니다.

--artifact-repo TEXT

• 원격 fast-agent 작업 아티팩트 (artifacts)를 위한 데이터셋 저장소 (Dataset repo) (--executor jobs 사용 시 필수)

--max-parallel N

• 최대 동시 평가 실행 횟수; 설정 (config)을 덮어씁니다.

--runs-dir PATH

• 실행 로그 (run logs) 저장 디렉토리 (기본값: ./runs)

--log-runs / --no-log-runs

• 실행 데이터 기록 (기본값: 활성화 (enabled))

예시 (Examples):

# 기본 사용법 (Basic usage)
upskill generate "parse JSON Schema files"
# 성능이 낮은 모델들을 위해 기술 (skills) 생성 및 평가
...

출력 (Output):

Generating skill with sonnet...
Generating test cases...
Evaluating on sonnet... (attempt 1)
...

기존 기술 (skill)을 테스트 케이스 (test cases)에 대해 평가합니다. 베이스라인 비교 (baseline comparison)를 포함한 단일 모델 평가 또는 멀티 모델 벤치마킹 (multi-model benchmarking)을 지원합니다.

upskill eval SKILL_PATH [OPTIONS]

인자 (Arguments):

SKILL_PATH

• SKILL.md가 포함된 기술 (skill) 디렉토리 경로

옵션 (Options):

-t, --tests PATH

• 테스트 케이스 (Test cases) JSON 파일

-m, --model MODEL

• 평가 대상 모델 (Model(s)) (멀티 모델 벤치마킹을 위해 반복 사용 가능)

--test-gen-model MODEL

• 테스트를 생성해야 하는 경우, 테스트 생성 모델 (test generation model)을 덮어씁니다.

--runs N

• 모델당 실행 횟수; 설정 (config)을 덮어씁니다.

--no-baseline

• 베이스라인 비교 생략 (단순 평가 모드에서만 작동하며, 벤치마크 모드에서는 무시됨)

-v, --verbose

• 테스트별 결과 표시

--executor [local|jobs]

• 평가를 위한 실행 백엔드 (Execution backend); 설정 (config)을 덮어씁니다.

--max-parallel N

• 최대 동시 평가 실행 횟수; 설정 (config)을 덮어씁니다.

--log-runs / --no-log-runs

• 실행 데이터 기록 (기본값: 활성화 (enabled))

--runs-dir PATH

• 실행 로그 (run logs) 저장 디렉토리

예시 (Examples):

# 베이스라인 비교를 포함한 기본 평가
upskill eval ./skills/my-skill/
# 상세 출력 (verbose output) 포함
...

벤치마크 출력 (Benchmark output):

Evaluating my-skill across 2 model(s)
3 test case(s), 5 run(s) per model
haiku
...

테스트 케이스 JSON 형식 (Test cases JSON format):

[
{"input": "Write a commit for adding login", "expected": {"contains": ["feat", "login"]}},
{"input": "Fix the null pointer bug", "expected": {"contains": ["fix", "bug"]}}
...
]

생성된 모든 기술 (skills)을 트리 뷰 (tree view)로 나열합니다.

upskill list [OPTIONS]

옵션 (Options):

-d, --dir PATH

• 나열할 기술 (skills) 디렉토리

-v, --verbose

• 기술 (skill) 내용 미리보기 표시

예시 (Examples):

# 기본 디렉토리의 기술 (skills) 나열
upskill list
# 사용자 정의 디렉토리에서 나열
...

출력 (Output):

./skills
├── git-commit-messages
│ ├── 명확하고 관례적인 커밋 메시지를 작성하세요...
...

실행 결과 (run results)를 플롯 (plot)으로 보거나 CSV로 내보낼 수 있습니다. 기본적으로 베이스라인 (baseline) 대 기술 (with-skill) 성능의 시각적 비교를 보여줍니다.

upskill runs [OPTIONS]

옵션 (Options):

-d, --dir PATH

• 실행 (runs) 디렉토리

-s, --skill TEXT

• 기술 (skill) 이름으로 필터링 (중복 사용 가능)

-m, --model TEXT

• 모델 (model) 이름으로 과거 실행 데이터 필터링 (중복 사용 가능)

--metric [success|tokens]

• 표시할 지표 (metric) (기본값: success)

--csv PATH

• 플롯 대신 CSV로 내보내기

예시 (Examples):

# 결과 플롯 보기 (기본값)
upskill runs
# 기술 (skill) 및 모델 (models)로 필터링
...

플롯 출력 (Plot output):

skill: git-commit-messages
haiku
baseline ████████████░░░░░░░░ 60%
...

매트릭스 뷰 (Matrix view) (여러 기술 및 모델):

┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ skill ┃ haiku ┃ sonnet ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
...

기술 (skills)은 표준 디렉토리 형식으로 저장됩니다:

./skills/{skill-name}/
├── SKILL.md # 주요 기술 지침 (Main skill instructions)
├── references/ # 보조 문서 (선택 사항)
...

SKILL.md 예시 (Example SKILL.md):

# git-commit-messages
모범 사례를 따르는 명확하고 관례적인 커밋 메시지를 작성하세요.
## 지침 (Instructions)
...

기본적으로, upskill은 모든 실행 (runs)을 ./runs/에 기록합니다. 각 실행은 다음과 같이 생성됩니다:

./runs/
├── 2025_01_21_15_30/ # 배치 폴더 (타임스탬프)
│ ├── run_1/
...

--no-log-runs 옵션으로 비활성화할 수 있습니다.

skill_generation_model: sonnet # 기본 스킬 생성 모델 (Default skill generation model)
eval_model: haiku # 기본 평가 모델 (Default evaluation model, 선택 사항)
test_gen_model: null # 선택 사항인 테스트 생성 모델 (Optional test generation model)
...

test_gen_model

폴백 동작 (fallback behavior):

• CLI
  --test-gen-model 옵션은 단일 실행(single run)에 대해 설정(config)을 덮어씁니다. - 설정될 경우, 테스트 생성 시 test_gen_model을 사용합니다. - 설정되지 않을 경우, 테스트 생성은 skill_generation_model로 폴백(fallback)됩니다. - eval / benchmark의 경우, 여러 평가 모델을 탐색(sweeping)할 때 생성된 테스트가 안정적으로 유지되도록 의도적으로 eval_model이 아닌 skill_generation_model을 사용합니다.

하위 호환성 (Backward compatibility): model은 skill_generation_model의 레거시 별칭(legacy alias)으로서 설정 파일에서 여전히 허용됩니다.

CLI 플래그는 실행 설정에 대해 설정(config) 값을 덮어씁니다:

--executor는 executor를 덮어씁니다.
--runs는 num_runs를 덮어씁니다.
--max-parallel은 max_parallel을 덮어씁니다.
--jobs-secrets는 jobs_secrets를 덮어씁니다.

executor: jobs로 설정하더라도, --artifact-repo와 같이 필수적인 Jobs 전용 CLI 입력값이 여전히 필요합니다.

jobs_secrets는 원격 HF Jobs 실행으로 전달할 환경 변수 이름들의 쉼표로 구분된 목록입니다. 여기에는 실제 비밀 값(literal secret values)이 아닌 HF_TOKEN 또는 ANTHROPIC_API_KEY와 같은 비밀 이름(secret names)이 포함되어야 합니다.

jobs_image는 HF Jobs가 원격 실행을 위해 어떤 컨테이너 이미지(container image)를 사용할지 제어합니다.

설정 조회 순서 (Config lookup order):

UPSKILL_CONFIG 환경 변수 (path)
./upskill.config.yaml (프로젝트 로컬)
~/.config/upskill/config.yaml (레거시 폴백)

FastAgent 설정을 사용자 정의하려면 프로젝트 디렉토리에 다음을 배치하세요:

default_model: sonnet
logger:
progress_display: true
...

# Anthropic 모델에 필요함
ANTHROPIC_API_KEY=sk-ant-...
# OpenAI 모델에 필요함
...

from upskill import (
generate_skill,
generate_tests,
...

upskill은 FastAgent 모델 형식을 사용합니다:

<provider>.<model>.<reasoning_effort?>

예시:

sonnet - Anthropic Claude Sonnet (별칭)
haiku - Anthropic Claude Haiku (별칭)
opus

• Anthropic Claude Opus (별칭)anthropic.claude-sonnet-4-20250514

• Full model nameopenai.gpt-4.1

• OpenAI GPT-4.1openai.o3-mini.low

• OpenAI o3-mini with low reasoning effortgeneric.llama3.2:latest

• Local model via Ollamageneric.my-model

• Local model via llama.cpp or other OpenAI-compatible server

upskill은 모든 OpenAI 호환 엔드포인트(llama.cpp, vLLM 등)를 통해 로컬 모델을 지원합니다.

llama.cpp 서버 사용 시:

# llama.cpp 서버 시작
./llama-server -m model.gguf --port 8080
# 엔드포인트를 fast-agent 설정/환경 변수를 통해 구성한 후 평가합니다.
...