AI 스킬을 위한 Homebrew 구축: 설치 흐름 및 평가 시스템 포함

문제점

지난 분기에는 백엔드 FastAPI 작업을 위해 SKILL.md 파일을 수동으로 작성하는 데 오후를 보냈습니다. 사용 가능한 프롬프트 세트, 세 가지 템플릿, 그리고 설정 파일까지 갖추었을 때, 팀의 다른 누구도 이 일을 하지 않을 것이라는 것을 깨달았습니다. 엔지니어링 스킬은 너무 경직되어 있거나(특정 스택에 대한 수동 작성 프롬프트), 아니면 너무 일반적입니다(

Local-first는 말 그대로 Local-first를 의미합니다. SkillForge는 127.0.0.1에 바인딩되며, 텔레메트리(telemetry)를 전송하지 않고, 생성된 스크립트를 자동으로 실행하지 않습니다. 유일한 외부 트래픽은 사용자가 설정한 LLM 제공업체(LLM provider)로 향하는 트래픽뿐입니다. 스킬(Skills)은 ~/.skillforge/skills 디렉토리 아래 디스크에 저장됩니다. 파일 시스템이 신뢰할 수 있는 단일 원천(source of truth)입니다.

작동 방식

세 개의 앱과 하나의 서비스 레이어로 구성됩니다. CLI와 API는 동일한 Python 서비스들을 임포트(import)하므로, 커맨드 라인에서의 skillforge plan과 브라우저에서의 POST /api/chat/plan-skill은 정확히 동일한 코드 경로(code path)를 실행합니다.

┌──────────────────────────────────────────────────────────────────┐
│  apps/web   (Next.js + TS + Tailwind)   :3000 / :8000 (bundled)  │
│  ChatPanel → ManifestEditor → SkillPreview → InstallButton       │
...

현재 6개의 제공업체 제품군(provider families)이 지원되며, 설정(Settings) 페이지에서 재시작 없이 실시간으로 모두 교체 가능합니다: Mock (기본값, 오프라인, 결정론적(deterministic)), OpenAI 호환(OpenAI, OpenRouter, Groq, Together, Mistral, DeepSeek, xAI, Fireworks, Z.ai), Ollama, Anthropic, Gemini, 그리고 Cohere입니다. Mock 제공업체 덕분에 프로젝트를 설정 없이 바로 실행할 수 있으며, 테스트 스위트(test suite)가 오프라인에서도 통과될 수 있습니다.

첫 번째 계획(plan):

skillforge plan "I need a backend skill for FastAPI, PostgreSQL, Docker, and Pytest"

CLI 인터페이스는 의도적으로 작게 설계되었습니다: serve, plan, generate, install, list, validate, remove. 생성기(generator)는 실행 측면에서 순수(pure)합니다. subprocess를 절대 호출하지 않습니다. 생성된 scripts/ 디렉토리는 디스크 상의 참조 텍스트일 뿐이며, 사용자가 실행하기로 선택했을 때만 실행됩니다.

실제로 얻게 되는 것

스킬은 다음과 같은 구조로 ~/.skillforge/skills/<name>/에 저장됩니다:

~/.skillforge/skills/backend-fastapi-postgres/
  SKILL.md
  README.md
...

scripts/ 디렉토리는 가장 오랜 시간이 걸린 부분입니다. 각 아티팩트(artifact)는 생성 시점에 ToolArtifactRegistry에 의해 생성된 실제 실행 가능한 파일이며, 단순한 플레이스홀더(placeholder)가 아닙니다. FastAPI 스킬은 작동 가능한 dev_server.py를 제공합니다. 데이터 스킬은 Alembic migrate.sh를 제공합니다. DevOps 스킬은 Helm Chart.yaml을 제공합니다. config.yaml은 설정 덤프(config dump)가 아니라 매니페스트(manifest)입니다:

schema_version: "1.0"
skill:
  name: backend-fastapi-postgres
...

생성된 모든 스킬에는 safety 블록이 포함됩니다. auto_execute_scripts는 항상 false로 설정됩니다. 설치 프로그램은 명시적인 플래그(flag) 없이는 기존 스킬을 덮어쓰지 않습니다.

비유 (The analogy)

SkillForge는 새로운 형태가 아닙니다. 여러분이 이미 알고 있는 네 가지 패키지 매니저(package manager)와 동일한 형태를 가집니다.

SkillForge	Homebrew	npm	VS Code	Helm
`config.yaml`	formula (.rb)	package.json	package.json (contributes)	Chart.yaml
...

Homebrew는 누구나의 formula git 저장소를 연합하여 사용합니다 (https://docs.brew.sh/Formula-Cookbook). npm 스코프 패키지(scoped packages)는 검증된 네임스페이스(namespace)를 위해 인증 토큰(auth tokens)을 사용합니다. Helm OCI 레지스트리(registries)는 서명된 차트(signed charts)를 호스팅합니다. SkillForge 마켓플레이스 브리지(marketplace bridge)도 동일한 모델입니다. 누구나 마켓플레이스를 호스팅할 수 있으며, 로컬 앱은 6자리 코드를 통해 이와 연결됩니다.

마켓플레이스 비전 (The marketplace vision)

마켓플레이스는 웹사이트가 아닙니다. 그것은 HTTP 계약(contract)입니다. 누구나 이를 실행할 수 있습니다. 로컬 앱은 연결된 마켓플레이스가 누구의 것인지 상관하지 않습니다. 현재 저장소에는 오프라인에서 전체 게시, 검색, 다운로드, 설치 흐름을 구현하는 LocalStubAdapter가 포함되어 있어, 클라우드 백엔드 없이도 전체 루프를 테스트해 볼 수 있습니다.

페어링(pairing) 흐름은 VS Code와 GitHub의 방식을 차용했습니다. 로컬 사용자는 10분의 TTL(Time To Live)을 가진 일회용 6자리 코드를 생성합니다:

# 1. 로컬 사용자가 일회용 6자리 코드를 생성합니다
POST /api/marketplace/pair/code
→ {"code": "AB3X9K", "ttl_minutes": 10}
...

토큰의 SHA-256 해시값만 로컬의 chmod 600 파일에 저장됩니다. 비교 작업은 hmac.compare_digest를 통해 상수 시간(constant-time)으로 수행됩니다. 페어링 엔드포인트(Pairing endpoints)는 클라이언트당 분당 10회로 속도 제한(rate-limited)이 걸려 있어, 8억 8,700만 개의 코드 공간을 무차별 대입 공격(brute force)으로 뚫는 것은 증명 가능한 수준으로 불가능합니다.

기본 스코프(Default scopes)는 registry:read, skills:install, skills:publish입니다. 위험한 스코프인 skills:install:unattended는 기본적으로 꺼져 있으며 명시적인 권한 부여가 필요합니다. 마켓플레이스에서 시작된 설치는 승인 대기열(approval queue)에 들어갑니다. 로컬 사용자가 '승인(Approve)'을 클릭해야 합니다. 조용한 설치(silent installs)는 절대 허용되지 않습니다.

전송되는 번들(wire bundle)은 .skillpkg라고 불리는 gzipped tarball입니다:

skill-creator.skillpkg
├── PACKAGING        # JSON: name, version, packaged_at, packaged_by
├── manifest.json    # canonical SkillManifest
...

압축 해제 시 경로 탐색(Path traversal) 공격은 거부됩니다. 매니페스트(manifest)가 신뢰할 수 있는 유일한 원천(source of truth)입니다.

비전은 이렇습니다: 누구나 스킬을 설계하고, 누구나 마켓플레이스를 호스팅하며, 누구나 설치합니다. GPT Store가 프롬프트 래퍼(prompt wrappers)로 가득 찬 이유는 품질 신호(quality signal)가 없었기 때문입니다. SkillForge는 이를 갖추고 출시됩니다.

평가 하네스 (The eval harness)

평가 하네스(eval harness)가 바로 품질 신호입니다. 이는 웹 UI의 /eval 경로에 위치합니다.

스킬을 선택합니다. 프롬프트 제품군(prompt suite)을 선택합니다. 각 프롬프트에 대해, 하네스는 설정된 프로바이더(provider)를 대상으로 스킬의 SKILL.md를 가이드로 삼아 스킬을 실행한 뒤, LLM-as-judge에게 스킬 자체의 output_standards를 기준으로 응답을 0점에서 10점 사이로 점수 매기도록 요청합니다. 결과는 색상으로 구분된 점수와 추론 과정이 포함된 확장 가능한 테이블로 스트리밍됩니다. 실행 결과는 SQLite에 영구 저장되므로 반복(iteration)에 따른 점수 추적이 가능합니다.

POST /api/eval/run
{
  "skill_name": "backend-fastapi-postgres",
...

비교 모드(Compare mode)는 이 하네스(harness)가 제 역할을 다하는 핵심적인 부분입니다. 두 개 이상의 스킬(skill)과 공유된 스위트(suite)를 선택하세요. 그러면 집계된 점수, 승리 횟수, 그리고 승자가 강조된 프롬프트별 사이드 바이 사이드(side-by-side) 카드를 확인할 수 있습니다. 수동 오버라이드(Manual override)도 지원됩니다. 다섯 명의 사용자가 backend-fastapi-postgres 스킬을 게시하면, 동일한 스위트에서 이들을 맞대결시켜 어떤 스킬이 실제로 승리하는지 확인할 수 있습니다. 품질이 측정 가능한 영역이 되는 것입니다.

비용 가드(cost guard)는 실행당 완료 횟수를 SKILLFORGE_EVAL_MAX_CALLS=50으로 제한합니다. 평가(Eval)는 생성된 스크립트를 실행하지 않으며, 오직 채팅 API(chat API)만 호출합니다.

두 가지 솔직한 주의사항이 있습니다. 첫째, 판사(judge)와 생성기(generator)를 이미 서로 다른 제공자(provider)를 사용하도록 설정할 수 있어, 자기 평가 편향(self-grading bias)의 최악의 상황을 방지할 수 있습니다. 다만 기본 설정은 여전히 두 역할 모두에 동일한 제공자를 사용하며, 대부분의 사용자는 이를 변경하지 않을 것입니다. 로드맵 항목인 Tier 2.1은 판사가 생성기와 다른 제공자를 기본값으로 사용하도록 만드는 것입니다. 두 번째 주의사항은 도메인별 출력 표준(output standards)이 아직 일반적이라는 점입니다. 현재 모든 도메인은 하나의 공유된 표준 목록을 기준으로 평가합니다. 로드맵의 Tier 1.2에서 이를 전문화할 예정입니다.

GPT Store가 부분적으로 실패한 이유는 품질 신호(quality signal)가 없었기 때문입니다. SkillForge는 이를 제공합니다. 아직 거칠고 알려진 편향이 존재하지만, 아무것도 없는 것보다는 낫습니다.

안전성 및 솔직한 한계점

안전이 최우선입니다. 로컬 서버는 기본적으로 127.0.0.1에 바인딩됩니다. LocalOriginGuardMiddleware는 Origin 또는 Referer 헤더에 루프백(loopback) 호스트가 아닌 호스트가 명시된 브라우저 요청을 거부하며, 이는 Jupyter와 VS Code가 사용하는 CSRF 및 DNS 리바인딩(DNS-rebinding) 방어 방식입니다. 토큰 비교는 상수 시간(constant-time)에 이루어집니다. 설치는 원자적(atomic)으로 진행됩니다: 스테이징 디렉토리에 작성한 후 os.replace를 수행합니다. SQLite는 busy_timeout=5000 및 synchronous=NORMAL 설정과 함께 WAL 모드로 실행되므로, 동시 평가 및 레지스트리 접근 시 더 이상 "database is locked" 오류가 발생하지 않습니다. 생성된 스크립트는 절대 자동으로 실행되지 않습니다. 도구 실행기(tool executor)는 명시적인 confirm=True, 허용 목록(allowlist) 일치, 그리고 30초의 타임아웃을 요구합니다.

이제 한계점에 대해 말씀드리겠습니다. 이것들은 사용자 참여를 유도하는 요소이므로, 솔직하게 말씀드리겠습니다:

교차 플랫폼 바이너리 릴리스 (Cross-platform binary releases)를 위해서는 CI 작업이 필요합니다. 릴리스 워크플로우 (release workflow)는 저장소 (repo)에 포함되어 있습니다. 하지만 태그 푸시 (tag push) 시 이를 실행하는 자동화는 포함되어 있지 않습니다. 현재는 ./scripts/build-binary.sh를 사용하여 사용자의 플랫폼에서 직접 바이너리를 빌드해야 합니다.
새로운 스킬을 작성할 수 있도록 돕는 메타 스킬 (meta skill)인 skill-creator 스킬은 첫 실행 시 자동으로 부트스트랩 (auto-bootstrapped)됩니다. 작동은 하지만, 아직 거친 상태입니다.
아직 SSE (Server-Sent Events) 스트리밍이 지원되지 않습니다. 계획된 응답 (plan responses)은 단일 JSON 페이로드 (payload)로 반환됩니다. 웹 UI (Web UI)에는 스피너 (spinner)가 표시됩니다.
웹 레이어 (web layer)에 대한 Playwright 커버리지가 없습니다. 생성된 SKILL.md에 대한 스냅샷 테스트 (Snapshot tests)도 존재하지 않습니다.
저장소에는 21개 파일에 걸쳐 247개의 테스트가 통과되고 있습니다. 이 숫자는 반올림된 것이 아닌 실제 수치입니다.

버그를 찾고 싶다면, 위의 항목들을 가장 먼저 살펴보시기 바랍니다.

로드맵 (Roadmap)

거대한 비전은 누구나 스킬을 설계하고, 게시하며, 최종 사용자가 스킬 출력물을 서로 직접 비교할 수 있는 연합 마켓플레이스 (federated marketplace)를 구축하는 것입니다. 최고의 스킬은 떠오르고, 약한 스킬은 포크 (fork)되어 개선됩니다.

로드맵의 구체적인 항목들은 다음과 같습니다:

Server-Sent Events를 통한 계획된 응답 (plan responses) 스트리밍
평가 판사 (eval judge)를 위한 도메인별 출력 표준 (per-domain output standards)
자기 채점 편향 (self-grading bias)을 제거하기 위한 기본적으로 분리된 판사 제공자 (judge provider)
태그 푸시 (tag push) 시 CI를 통한 교차 플랫폼 바이너리 릴리스 (Cross-platform binary releases)
PR 템플릿 및 CI 체크를 포함한 다국어 카탈로그 기여
외부 저장소에서 사용할 수 있는 "스킬 린터 (skill linter)" CI 액션 (action)
읽기 전용 공개 레지스트리 (public registry)를 포함하여 LocalStub을 넘어선 플러그형 마켓플레이스 어댑터 (pluggable marketplace adapters)
여러 판사 샘플 (judge samples)과 유의성 검정 (significance testing)을 활용한 통계적 평가 (statistical eval)

설계상 범위 외 (Out of scope) 항목: 클라우드 동기화 (cloud sync), 다중 사용자 워크스페이스 (multi-user workspaces), 인증 (auth), 팀 권한 (team permissions), 원격 배포 (remote deployment), 생성된 스크립트의 자동 실행 (auto-executing generated scripts). 만약 이러한 기능들이 중요하다면, MIT 라이선스와 깔끔한 서비스 레이어 (service layer) 덕분에 포크 (forking)가 매우 수월할 것입니다.

사용해보기 (Try it)

git clone https://github.com/sulthonzh/skillforge
cd skillforge
cd apps/api && pip install -e ".[dev]"
...

저는 스타 (stars)가 아니라 버그 리포트 (bug reports)와 엣지 케이스 (edge cases)를 원합니다. 어디서 작동이 멈추는지 알려주세요. 제가 피드백을 받고 싶은 구체적인 사항들은 다음과 같습니다:

플래너(planner)가 귀하의 스택에 맞지 않는 잘못된 도구(tools)를 선택했나요?
생성기(generator)가 실행했을 때 작동하지 않는 스크립트를 생성했나요?
평가 판사(eval judge)가 명백히 잘못된 점수를 매겼나요? 그렇다면 어떤 기준에 반하는 것이었나요?
마켓플레이스 페어링(marketplace pairing) 흐름이 귀하의 네트워크 설정에서 실패했나요?
로컬 오리진 가드(local-origin guard)가 귀하가 사용하는 정당한 도구를 거부했나요?

apps/api/skillforge_api/data/tool_catalog.yaml 파일은 훌륭한 첫 번째 PR(Pull Request)입니다. 도메인을 추가하세요. 도구를 추가하세요. 이유를 추가하세요. 카탈로그는 기여자가 늘어날 때마다 더욱 개선되는 부분입니다.

Repo: https://github.com/sulthonzh/skillforge