YAO는 "Yielding AI Outcomes(AI 성과를 내놓는다)"의 약자로, 프롬프트 글자만 늘리는 게 아니라 재사용 가능한 자산과 실제 결과물을 만드는 걸 목표로 한다. 1.0이 "워크플로 → 설치 가능한 스킬 패키지"였다면, 저장소가 'Skill OS 2.0'이라 부르는 라인은 거기에 중간표현(IR)·다중 타깃 컴파일·평가 증거·릴리스 게이트·운영 리포트를 둘러 "스킬 운영체제"로 키운다. (저장소: yaojingang/yao-meta-skill · 형식 Agent Skill · 구현 Python 스크립트 153개 + Makefile · 버전 1.1.0 · 성숙도 governed(거버넌스) · 라이선스 MIT · 제작 Yao Team · 다국어 문서)한 문장으로 이 프로젝트가 뭘 하는지부터.
Yao Meta Skill = "스킬을 만드는 스킬 + 그 스킬을 검수·인증·관리하는 공장." 먼저 스킬(skill)이 뭔지부터. 요즘 AI 에이전트(클로드·ChatGPT 등)에는 "특정 작업을 잘하도록 미리 적어 둔 설명서"를 끼워 넣을 수 있는데, 이걸 스킬이라 한다(보통 SKILL.md 파일). 문제는 사람들이 이걸 손으로 그때그때 대충 쓴다는 것 — 트리거(언제 발동?)가 모호하고, 품질이 들쭉날쭉하고, 플랫폼마다 다시 써야 한다. Yao Meta Skill은 이 "스킬 만들기"를 표준화된 생산 라인으로 바꾼다: 내 반복 작업을 입력하면, 잘 트리거되고·군더더기 없고·여러 플랫폼에 맞고·증거로 검증된 스킬 패키지로 뽑아 준다.
혼자 쓰는 레시피(손으로 쓴 스킬)는 "대충 적당히"여도 된다. 하지만 그걸 남들과 나누거나 매일 팔려면, 재료 표준·조리 순서·위생 검사·유통기한·리콜 절차가 필요해진다.
Yao Meta Skill은 레시피 한 장을 설계도(IR) → 생산(컴파일) → 시식 테스트(평가) → 위생 검사(트러스트·게이트) → 출하 승인(릴리스) → 사후 모니터링(텔레메트리)까지 도는 공장으로 바꿔 준다. 게다가 "맛있다(=세계최고다)"고 함부로 라벨 붙이지 못하게, 증거가 없으면 그 주장을 막는 감사관까지 둔다. 즉 단순 "스킬 작성 도우미"가 아니라 스킬의 전 생애주기를 통제하는 운영체제다.
SKILL.md로, 맨 위 frontmatter(이름·설명·트리거)와 본문 지침으로 구성된다. 에이전트는 사용자 요청이 그 description과 맞으면 스킬을 "발동(트리거)"해 본문 지침을 따른다. yao-meta-skill 자체도 하나의 스킬인데, 그 일이 "다른 스킬을 만드는 것"이라 '메타 스킬'이라 부른다.정리하면 Yao Meta Skill의 핵심 약속은 세 가지다. ① 반복 작업을 잘 트리거되는 재사용 스킬로 만든다(설명을 먼저 쓰고 트리거 품질을 테스트). ② 한 번 설계(IR)하면 여러 플랫폼(OpenAI·Claude·VS Code 등)용으로 컴파일한다. ③ 평가·검토·릴리스·운영을 게이트와 증거로 통제한다. SKILL.md의 원칙 그대로 — "가장 가벼우면서도 믿을 수 있는 절차를 쓰라(use the lightest reliable process)."
"스킬 폭발기"에 등장한, 스킬을 진지하게 다루는 거의 유일한 거버넌스 도구.
2025~2026년은 'AI 에이전트 스킬'이 폭발한 시기다(Anthropic의 Agent Skills, OpenAI의 도구·앱 등). 누구나 스킬을 만들지만, 대부분은 손으로 쓴 일회성이라 트리거가 어긋나거나 팀에서 재사용이 안 된다. yao-meta-skill이 주목받는 건, 이 혼란기에 "스킬 제작을 공학(engineering)으로" 끌어올리려는 보기 드문 시도이기 때문이다. 다섯 가지로 본다.
대부분의 스킬은 특정 작업 하나를 한다. yao는 스킬 제작 자체를 자동화·표준화한다 — 메타 레이어다. 게다가 자기 자신이 그 방법론으로 만들어진 governed 스킬이라(manifest.json maturity_tier=governed), "이론을 스스로 시연"하는 부트스트랩 구조다.
스킬을 OpenAI·Claude·VS Code에 각각 다시 쓰는 건 고역이다. yao는 플랫폼 중립 중간표현(Skill IR)으로 한 번 모델링하고, 타깃별로 컴파일한다(interface.yaml의 adapter_targets: openai·claude·generic·vscode). 프로그래밍 언어의 컴파일러 발상을 스킬에 가져왔다.
"잘 트리거되나? 출력이 기준을 만족하나?"를 감으로 두지 않는다. Output Eval Lab이 트리거 검사·출력 단언(assertion)·실행/시간/토큰 증거·블라인드 A/B 리뷰팩·정답키·판정 리포트를 만든다(evals/, run_output_eval.py 등). "테스트 주도 스킬 개발"이라 부를 만하다.
가장 독특한 점. yao는 "세계최고(world-class)"라는 주장을 증거로 잠근다 — 제공자 검증·사람 블라인드 리뷰·실사용 텔레메트리가 모일 때까지 그런 주장을 "증거 없음"으로 막는 claim guard가 있다(render_world_class_claim_guard.py). AI 도구가 흔히 빠지는 과장을, 도구 스스로 단속한다.
스킬은 만들고 끝이 아니다. yao는 메타데이터만으로 채택·드리프트(점점 안 맞아짐)를 추적하고, 일/주간 큐레이터 리포트로 "다음에 뭘 고칠지"를 제안한다(render_daily_skillops_report.py·render_weekly_curator_report.py). "DevOps의 스킬 버전"이라는 야심.
| 접근 | 스킬을 만드는 방식 | yao와의 차이 |
|---|---|---|
| 손으로 SKILL.md 작성 | 직접 글을 적음 | 빠르지만 품질·트리거 들쭉날쭉. yao는 설계→평가→게이트로 표준화. |
| 대화형 스킬 생성기 | AI와 대화로 한 편 생성 | 한 플랫폼·일회성. yao는 IR로 다중 타깃 컴파일 + 증거. |
| 사내 위키/템플릿 | 문서 규칙으로 통일 | 강제·검증 없음. yao는 게이트·증거 원장으로 강제. |
| yao-meta-skill | IR → 컴파일 → 평가 → 리뷰 → 릴리스 → 운영 | 스킬의 전 생애주기를 거버넌스. 과대주장까지 차단. |
스킬 제작을 감과 손에서 설계(IR)·평가(eval)·통제(게이트)의 공학으로 옮겼다. 다중 플랫폼 컴파일로 이식성을, 증거 원장과 claim guard로 정직함을 강제한다. 풍부한 doctrine 문서(references/ 30+편)는 그 자체로 "스킬 엔지니어링 교재"다.
강점이 곧 약점이다. 스크립트 153개·게이트 40+개·doctrine 30+편은 초보자에게 진입장벽이 매우 높다. README는 추상 용어(IR·ledger·intake·claim guard·drift…)로 빽빽해, "그래서 뭘 어떻게 시작하지?"가 한눈에 안 온다. 정작 SKILL.md 본문은 "일회성·재사용 안 될 일이면 스킬을 만들지 말라"고 못 박는다 — 이 도구의 무게는 팀·릴리스급 스킬에서야 값을 한다. 또 저장소 스스로 "강한 공개 주장은 아직 증거로 잠겨 있고 베타"라고 인정한다 — 즉 거버넌스 틀은 갖췄지만, 외부 검증·실사용 증거는 진행 중이다. 작은 개인 스킬엔 명백히 과한 도구다.
SKILL.md · agents/interface.yaml · manifest.json · Makefile · scripts/ 에서 확인한 구성.
마음의 준비부터. yao-meta-skill은 "웹앱 스택"이 아니라 "문서(doctrine) + 파이썬 도구 + 계약(스키마)"의 묶음이다. 화려한 프레임워크가 없는 대신, 순수 Python 스크립트와 JSON 스키마, 마크다운 교본으로 "스킬 공장"을 구성한다. 계층별로 본다.
| 구성요소 | 무엇 | 역할 |
|---|---|---|
| SKILL.md | 스킬 진입점 | frontmatter(이름·description) + 라우터 규칙·모드·압축 워크플로. 의도적으로 짧게(lean) 유지. |
| agents/interface.yaml | 인터페이스 계약 | 표시명·기본 프롬프트·adapter_targets(openai·claude·generic·vscode)·trust·degradation 정의. |
| manifest.json | 패키지 메타 | 버전·owner·maturity_tier(governed)·review_cadence·대상 플랫폼·factory_components. |
| 구성요소 | 무엇 | 역할 |
|---|---|---|
| Makefile | 명령 허브 | make eval·skill-ir-check·review-studio-check 등 40+ 검사 타깃의 진입점. |
| scripts/ (153개) | 파이썬 도구 모음 | init·compile·eval·render·governance 등 모든 기능의 실체. 예: init_skill.py·compile_skill.py. |
| yao.py (CLI) | 런 캡처 CLI | 실행을 기록(메타데이터만)해 텔레메트리/드리프트 신호로 사용. |
| requirements-ci.txt | CI 의존성 | GitHub Actions(.github/)에서 검사 묶음을 자동 실행. |
도구가 들쭉날쭉하지 않게 묶어 주는 세 가지. 계약(스키마) — skill-ir/schema.json(스킬 중간표현)과 schemas/*.schema.json(적응 제안·해석·기회)이 데이터 형식을 못 박는다. 교본(doctrine) — references/의 30+편 마크다운(스킬 엔지니어링 방법·게이트 선택·거버넌스·시스템 사고…)이 "왜·어떻게"를 설명한다. 리포트 — render_*.py 다수가 html_rendering.py를 통해 사람이 볼 HTML 리포트(Skill Overview·Review Studio·증거 원장)를 만든다. 즉 "코드(scripts) + 규칙(schemas) + 설명(references) + 결과물(reports)"의 4박자다.
먼저 전체 생산 라인을 한 장으로 본 뒤, "노트 한 장이 검증된 스킬 패키지가 되기까지"를 끝까지 따라간다.
yao의 일은 "거친 입력(워크플로·프롬프트·노트) → 검증된 재사용 스킬 패키지" 라는 변환이다. 핵심은 이게 일직선 파이프라인이라는 것 — 의도 파악 → 설계(IR) → 컴파일 → 평가 → 검토 → 릴리스 → 운영. 단계마다 "게이트(검사)"가 있어, 통과 못 하면 다음으로 못 간다. 부품(스크립트) 이름보다 이 라인의 큰 흐름을 먼저 보자.
skill-ir/schema.json). 프로그래밍 컴파일러가 소스코드를 IR로 바꾼 뒤 여러 CPU용 기계어로 내보내듯, yao는 스킬을 IR로 모델링한 뒤 OpenAI·Claude·VS Code용으로 각각 컴파일한다. "한 번 설계, 여러 곳 배포"의 핵심 장치.반복 작업 노트를 주고 "스킬로 만들어 줘"라고 했을 때, 라인이 도는 순서를 풀면(SKILL.md의 Compact Workflow + scripts 매핑):
// 입력: "매주 고객 피드백을 분류·요약하는 내 작업 절차" 노트
1. 의도 확인 진짜 할 일/출력/제외/기준을 캐물음 → 재사용+출력계약 있나? (없으면 중단)
2. 참조 스캔 github_benchmark_scan : 비슷한 공개 스킬 훑어 충돌/공백만 보고
3. 설계(IR) export_skill_ir : 의도·트리거·입출력을 schema.json 형식으로 고정
4. 컴파일 compile_skill_targets : IR → claude/openai/vscode 어댑터 생성
5. 평가 run_output_eval + judge_blind_eval : 트리거·출력 품질을 증거로 채점
6. 검토 render_review_studio : 모든 신호를 1장 HTML 게이트로 모아 사람이 판단
7. 릴리스 package_verify + simulate_install + claim_guard : 증거 충족 시에만 출하
8. 운영 telemetry/drift → 다음에 고칠 후보를 제안(승인형)핵심 관례 둘. 첫째, description(설명)을 일찍 쓴다. 스킬이 "언제 발동하나"는 frontmatter의 description이 결정하므로, 이걸 먼저 적고 라우팅 품질을 테스트한다(route-scorecard·route-confusion-check). 둘째, "가장 가벼운 적합 절차" 원칙 — 모든 게이트를 항상 돌리지 않는다. Scaffold(개인 탐색)는 가볍게, Governed(릴리스급)만 풀 게이트를 건다(references/operating-modes.md).
yao의 가장 독특한 설계는 증거 원장(evidence ledger)과 claim guard다. 리포트가 "이 스킬은 검증됐다/세계최고다"라고 적으려 하면, claim guard가 원장에 해당 증거(제공자 검증·사람 블라인드 리뷰·실사용 텔레메트리)가 쌓였는지 확인한다. 없으면 그 주장을 막고 "증거 없음(missing evidence)"으로 표시하게 한다. 또 evidence consistency 게이트는 여러 리포트(벤치마크·개요·원장·커버리지·Review Studio)가 서로 다른 말을 하지 않는지 교차 검사해 "조용한 드리프트"를 막는다. AI 산출물이 흔히 빠지는 과장·자기모순을, 파이프라인이 구조적으로 차단한다.
새 도구가 생기면 모든 걸 스킬로 만들고 싶어진다. 하지만 SKILL.md 첫 규칙이 "일회성이거나 재사용 가능한 출력 계약이 없으면 스킬을 만들지 말라"이다. 반복 사용 + 재사용 가능한 출력이라는 조건이 안 서면, 의도 게이트에서 걸러진다. "스킬화 자체가 비용"임을 아는 게 이 도구를 제대로 쓰는 첫걸음이다.
폴더가 많지만, "스킬 본체 / 도구 / 계약 / 교본 / 증거" 다섯 묶음으로 보면 길이 보인다.
루트에 폴더가 20개 넘게 펼쳐져 압도되기 쉽다. 하지만 각 폴더는 생산 라인의 한 공정에 대응한다 — 본체(SKILL.md·agents)·도구(scripts)·계약(skill-ir·schemas)·교본(references)·증거/결과(evals·evidence·reports)로 묶으면 된다.
| 위치 | 한 줄 역할 |
|---|---|
| SKILL.md | 가장 먼저 읽을 한 장. 라우터 규칙·모드·압축 워크플로·출력 계약. 일부러 짧다. |
| Makefile | 모든 검사의 버튼판. 어떤 게이트가 있는지 타깃 목록만 봐도 전체 그림이 보인다. |
| scripts/ | 기능의 실체 153개. init_skill·compile_skill·run_output_eval·render_review_studio가 핵심. |
| skill-ir/schema.json | 스킬 설계도(IR)의 형식 계약. "한 번 설계, 여러 곳 컴파일"의 기준. |
| references/ | 30+편 doctrine. 이 레포의 "왜"가 다 여기 있다 — 그 자체로 스킬 공학 교재. |
| evals/ | 트리거·출력을 채점하는 평가 세트. baseline·confusion·blind holdout 등. |
| evidence/ · reports/ | 증거 원장과 생성된 HTML 리포트. "증거로 통제"의 실물. |
코드 기술보다 "AI 자산을 공학적으로 다루는 사고법"을 배우는 레포다.
yao는 특정 프레임워크가 아니라 방법론을 배우는 곳이다. "스킬·프롬프트·AI 산출물을 어떻게 신뢰할 수 있게 만들 것인가"라는, 앞으로 점점 중요해질 주제의 살아 있는 교본이다. 무엇을 건질지 짚는다.
컴파일러의 IR(중간표현) 발상을 스킬 제작에 가져온 사례다. skill-ir/schema.json과 compile_skill_targets.py를 읽으면, 플랫폼 종속을 어떻게 분리하는지(어댑터 패턴) 배운다. 이식성 설계의 모범.
실습: skill-ir/examples/yao-meta-skill.json을 열어 IR이 어떤 필드로 스킬을 표현하는지 분석.
트리거 검사·출력 단언·블라인드 A/B 리뷰·판정 리포트(evals/, judge_blind_eval.py)는 소프트웨어 테스트를 AI 산출물에 적용한 것이다. "프롬프트/스킬을 어떻게 테스트하나"의 실전 패턴을 익힌다.
실습: evals/confusion/을 보고, 트리거가 "헷갈리는 요청"에서 오발동/미발동하는지 어떻게 측정하는지 파악.
증거 원장·claim guard·evidence consistency(render_world_class_*.py)는 "근거 없으면 주장 금지"를 코드로 강제한다. AI 시대의 정직성·감사가능성을 어떻게 시스템으로 보장하는지 배우는 드문 사례.
실습: references/governance.md를 읽고, 어떤 라벨(missing evidence 등)을 "있는 그대로 보존"하라고 요구하는지 정리.
40+개의 make *-check 타깃은 "복잡한 파이프라인을 어떻게 일관된 인터페이스로 묶나"의 교과서다. 각 타깃이 어떤 스크립트를 부르는지 따라가면, 큰 시스템의 진입점 설계를 배운다.
실습: Makefile에서 review-studio-check 타깃이 부르는 스크립트 체인을 추적.
skill-engineering-method·intent-dialogue·systems-thinking-doctrine·prompt-engineering-doctrine 등은 그 자체로 읽을 가치가 있는 글이다. 코드를 안 돌려도, "좋은 스킬/프롬프트란 무엇인가"를 체계적으로 배울 수 있다.
실습: references/non-skill-decision-tree.md를 읽고 "언제 스킬을 만들지 말아야 하는가" 기준을 내 일에 대입.
GPU 불필요. "Python + make + bash"와, 스킬을 실제로 쓸 "에이전트 호스트".
yao는 추론 모델이 아니라 스킬 제작·검사 도구라 고사양·GPU가 필요 없다. 검사·리포트는 평범한 PC의 Python으로 돌고, 만들어진 스킬은 Claude·ChatGPT 같은 에이전트 호스트 안에서 실제로 발동된다. 즉 "만드는 환경(Python)"과 "쓰는 환경(에이전트)"이 분리돼 있다.
| 항목 | 요구사항 |
|---|---|
| Python | 스크립트·검사 실행용(표준 라이브러리 중심). requirements-ci.txt 참고, python-compat-check 게이트로 호환성 점검. |
| make | 검사·리포트 진입점. make eval·make review-studio-check 등. |
| bash 셸 | interface.yaml의 execution.shell: bash — 인라인 실행 컨텍스트. |
| 에이전트 호스트 | 만든 스킬을 실제로 쓰려면 Agent Skills 지원 호스트(Claude·OpenAI·VS Code 계열) 필요. |
| Git + GitHub | CI(GitHub Actions)로 검사 묶음 자동 실행. 배포는 registry 호환 기록. |
| trust 정책 | remote_inline_execution: forbid — 원격 인라인 실행 금지, 메타데이터만 허용. |
| GPU | 불필요. |
가장 현실적인 출발점은 코드를 돌리기 전에 SKILL.md → references/skill-engineering-method.md → Makefile 타깃 목록 순으로 읽는 것이다. 이 셋만 봐도 "이 공장이 무엇을, 어떤 게이트로 통제하는가"의 전모가 잡힌다. 그다음 관심 가는 게이트 하나(make skill-ir-check 등)를 돌려 보며 깊이 들어가면 된다.
"읽기·이해"가 절반이다. 문서 → 게이트 1개 → 스킬 1개 순으로.
SKILL.md와 references/non-skill-decision-tree.md를 읽고, "내가 자주 하는 반복 작업 3개" 중 무엇이 스킬화할 가치가 있는지(반복+재사용 출력) 판정해 본다.
Makefile의 *-check 타깃 40여 개를 훑어, 생산 라인(설계→컴파일→평가→검토→릴리스→운영)의 어느 공정에 속하는지 분류해 표로 정리한다.
skill-ir/schema.json과 skill-ir/examples/yao-meta-skill.json을 나란히 놓고, IR이 스킬을 어떤 필드(의도·트리거·입출력·경계·산출물)로 표현하는지 매핑한다. 내 스킬 아이디어를 그 형식으로 한 장 써 본다.
evals/confusion/과 라우팅 점수 개념(route-scorecard)을 보고, 간단한 스킬 하나의 description을 두 버전으로 써서 "헷갈리는 요청"에 어느 쪽이 더 정확히 트리거되는지 비교한다.
레포를 클론해 Python 환경을 준비하고, make skill-ir-check나 make html-rendering-check 같은 가벼운 게이트를 실행해 본다. 무엇을 입력으로 받고 어떤 통과/실패를 내는지 로그로 관찰.
references/governance.md의 라벨 규칙(missing evidence·output contract 등)을 빌려, 내가 만든 작은 스킬에 "검증된 것 / 아직 증거 없는 것"을 정직하게 표시한 README를 써 본다.
yao를 100% 소화하기 위한 6주 코스(주당 5~7시간 가정). 코드보다 사고법 위주.
| 주차 | 주제 | 학습 자료 / 할 일 |
|---|---|---|
| 1주차 | 스킬·메타스킬 기초 | Agent Skill·SKILL.md 개념. SKILL.md + 비스킬 의사결정 트리 정독. 실습 1·2. |
| 2주차 | 스킬 엔지니어링 방법론 | references/skill-engineering-method.md·operating-modes.md·resource-boundaries.md 읽기. |
| 3주차 | Skill IR · 다중 타깃 컴파일 | skill-ir/ + compile_skill_targets.py. IR 예제 해부, 내 스킬을 IR로. 실습 3. |
| 4주차 | 평가 주도 개발 | output-eval-method.md·evals/. 트리거/출력 평가 개념, description 테스트. 실습 4. |
| 5주차 | 거버넌스 · 증거 | governance.md·증거 원장·claim guard. 게이트 1개 실행. 실습 5·6. |
| 6주차 | SkillOps · 운영 | skillops-decision-policy.md·telemetry-drift-method.md. 채택/드리프트·큐레이터 리포트 이해. |
이 문서와 레포에 등장한 용어를 한자리에.
| 용어 | 의미 |
|---|---|
| Agent Skill | AI 에이전트에 끼우는 재사용 설명서(보통 SKILL.md). 요청이 맞으면 발동(트리거). |
| Meta Skill(메타 스킬) | "스킬을 만드는 스킬". yao-meta-skill의 정체성. |
| YAO | Yielding AI Outcomes. "프롬프트 글자"가 아니라 "재사용 자산·실제 성과"를 낸다는 목표. |
| SKILL.md | 스킬 진입점 파일. frontmatter(이름·description·트리거) + 본문 지침. |
| frontmatter | SKILL.md 맨 위 메타데이터 블록. description이 트리거(발동 조건)를 좌우. |
| Skill IR | 플랫폼 중립 중간표현(설계도). 한 번 설계 → 여러 타깃으로 컴파일. |
| 컴파일러/어댑터 | IR을 OpenAI·Claude·generic·VS Code용 표면으로 변환하는 장치. |
| Output Eval Lab | 트리거·출력을 증거로 채점하는 평가 체계(단언·블라인드 A/B·판정). |
| Review Studio | 모든 신호를 모은 단일 HTML "게이트 페이지". 사람이 출시 여부를 판단. |
| 게이트(Gate) | "통과해야 다음으로" 가는 검사 관문(패키지검증·권한·트리거 등 40+개). |
| 증거(Evidence) 원장 | "정말 통과했다"는 근거 기록부. 외부·사람 증거의 수용/대기 상태를 관리. |
| claim guard | 증거가 없으면 "완료/세계최고" 같은 주장을 막는 감시 장치. |
| missing evidence | "아직 증거 없음" 라벨. 없는 걸 있다고 적지 않게 강제하는 정직성 장치. |
| SkillOps | 출시 후 운영: 채택·드리프트 추적, 적응 제안, 큐레이터 리포트("스킬의 DevOps"). |
| 드리프트(drift) | 스킬이 시간이 지나며 실제 사용과 점점 안 맞아지는 현상. 메타데이터로 감지. |
| 모드(Scaffold/Production/Library/Governed) | 스킬 성숙도 단계. 개인탐색→팀재사용→공유인프라→고신뢰. 모드에 따라 게이트 강도 조절. |
| maturity_tier: governed | 이 레포 자신의 등급(manifest). 가장 엄격한 통제가 적용되는 단계. |
| trust report | 스킬의 신뢰성(권한·출처·실행 정책)을 정리한 보고. governed 패키지 필수. |
원문·문서·관련 기술 더 파기.