주요 콘텐츠로 건너뛰기
AI 튜토리얼

MuseAI-Skills 읽기 튜토리얼: Muse AI 스킬, 권한 및 Agent 워크플로 분석

이 튜토리얼에서는 MuseAI-Skills를 확보하고 안전하게 읽는 방법을 소개합니다. 스킬 정의, 커넥터 권한, 평가 시나리오 및 실행 환경 스크립트를 이해하고, Gmail 등의 스킬을 예로 들어 재사용 가능한 Agent 워크플로 분석 방법을 구축합니다.

약 19분 소요
MuseAI-Skills 읽기 튜토리얼: Muse AI 스킬, 권한 및 Agent 워크플로 분석

프로젝트란 무엇인가

MuseAI-Skills는 muse.ai와 관련된 Muse / Hatch 개인 AI Agent 환경의 스냅샷입니다. 이 저장소에는 제품 설명, 스킬 정의, 커넥터 권한 목록, 행동 평가 시나리오, Linux 실행 스크립트, 일부 번들 프로그램과 종속성이 포함되어 있습니다.

중요한 범위: 완전한 소스 코드 저장소가 아니며, 한 번에 배포할 수 있는 설치 패키지도 아닙니다. 핵심 프로그램은 주로 Linux x86-64 ELF 바이너리로 제공되지만, 빌드 소스, 전체 호스트 설정, rootfs 및 일부 실행 리소스는 포함되어 있지 않습니다.

따라서 이 저장소는 Muse AI 서비스를 직접 설치하기보다는 정적 열람, Agent 워크플로 연구, 권한 모델 분석 및 지침 설계 참고에 가장 적합합니다. 저장소 자료에는 Muse, Hatch, Jarvis 등의 이름이 사용되지만, 이 아카이브 자체가 공식 출시, 승인 또는 출처 인증을 의미하지는 않습니다.

저장소에서 배울 수 있는 내용

스킬 워크플로의 전체 구조

저장소에는 72개의 SKILL.md 경로가 있으며, 독립적인 스킬 파일 68개와 심볼릭 링크 별칭 4개로 구성됩니다. 스킬은 Agent 워크플로, 문서 산출물, 여행 예약, 사무 도구, 소셜 플랫폼, 건강 데이터, 미디어 생성, 기기 제어 및 Muse 제품 작업 등의 영역을 다룹니다.

이러한 스킬 문서는 일반적으로 다음과 같은 질문을 연구하는 데 도움이 됩니다.

  • 어떤 사용자 요청이 스킬을 실행해야 하는가.
  • 작업을 코디네이터, worker 또는 외부 커넥터 중 누가 처리해야 하는가.
  • 실행 전에 어떤 계정 연결, OAuth scope 또는 사용자 승인이 필요한가.
  • 도구 실패, 불완전한 입력 또는 권한 부족 상황에서 어떻게 대체 처리하는가.
  • 출력 형식을 정의하고 최종 결과물을 어떻게 검증하는가.

권한 및 평가 자료

저장소에는 40개의 manifest 경로와 12개의 eval YAML 파일도 있습니다. manifest.yaml은 커넥터 메타데이터, 기본 권한, scope 요구 사항 및 명령 매핑을 이해하는 데 사용할 수 있으며, eval/scenarios.yaml은 행동 평가 시나리오, 사용자 목표 및 기대 동작을 기록합니다.

주의: manifest가 존재한다고 해서 계정이 연결된 것은 아니며, 평가 시나리오가 존재한다고 해서 평가가 실행되었거나 통과했다는 의미도 아닙니다.

실행 환경의 정적 단서

opt/hatch/runtime-cell/의 스크립트는 rootfs 경로 확인, 시작 전 준비, 커널 모듈 검사, systemd-nspawn 컨테이너 시작 및 스킬과 바이너리 overlay 조립 등 실행 환경 수명 주기의 일부를 보여 줍니다. 그러나 전체 호스트 unit, nspawn 설정 및 실제 rootfs는 저장소에 포함되어 있지 않습니다.

디렉터리 구조 한눈에 보기

  • README.md: 중국어 입문 문서, 스킬 디렉터리 및 범위 설명.
  • README.en.md: 영어 입문 문서.
  • PROJECT_ANALYSIS.md: 아키텍처 판단, 누락된 구성 요소, 위험 및 근거 색인.
  • SHA256SUMS: 일반 파일의 콘텐츠 체크섬 목록이지만 출처 서명은 아님.
  • home/hatch/docs/: 제품, 커넥터, 개인정보 보호, 스케줄링, 파일, 기기 및 미디어 관련 설명.
  • home/hatch/config/: Agent 및 스킬 상태 관련 설정.
  • opt/hatch/skills/: 스킬 진입점, 권한 manifest, 평가 시나리오 및 참고 자료.
  • opt/hatch/runtime-cell/: 실행 환경 수명 주기 스크립트 및 설정 템플릿.
  • opt/hatch/bin/: Hatch 관련 프로그램.
  • opt/hatch-image/: 이미지 측 도구, npm, Bun 및 기타 번들 구성 요소.

저장소 루트 디렉터리는 아카이브의 루트일 뿐, 현재 실행 중인 Linux 루트 디렉터리가 아닙니다. 아카이브의 home/hatch/는 원래 환경의 /home/hatch에 해당하며, 문서의 /run, /var/lib 및 /etc는 일반적으로 누락된 런타임 파일 시스템을 가리킵니다.

저장소 가져오기 및 준비

방법 1: 스킬과 문서만 연구하기

Markdown, YAML 및 Shell 스크립트를 분석하는 것이 목적이라면 용량이 큰 Git LFS 바이너리를 건너뛸 수 있습니다. 이는 가장 권장되는 열람 방식이기도 합니다.

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/win4r/MuseAI-Skills.git
cd MuseAI-Skills

이 방식에서는 번들 프로그램을 실행할 필요가 없습니다. 저장소에 들어간 후 먼저 PROJECT_ANALYSIS.md와 opt/hatch/skills/를 여십시오.

방법 2: 전체 아카이브 객체 확인하기

LFS에 저장된 ELF 프로그램이나 기타 대용량 파일을 실제로 검사해야 할 때만 Git LFS를 설치하고 관련 객체를 가져와야 합니다. 바이너리를 다운로드해도 누락된 소스, rootfs, 자격 증명 또는 호스트 설정이 보완되지는 않으며, 저장소가 배포 가능한 시스템으로 바뀌지도 않습니다.

git clone https://github.com/win4r/MuseAI-Skills.git
cd MuseAI-Skills
git lfs pull

출처가 독립적으로 인증되지 않은 바이너리는 먼저 오프라인 정적 검사를 수행해야 하며, 운영 머신이나 민감한 자격 증명이 포함된 환경에서 직접 실행해서는 안 됩니다.

일반 파일 검증

관련 파일을 모두 가져온 후 저장소에서 제공하는 SHA256SUMS를 사용하여 콘텐츠 무결성을 확인할 수 있습니다.

sha256sum -c SHA256SUMS

체크섬 목록 자체와 심볼릭 링크는 검증 대상에 포함되지 않으며, 게시자의 신원이나 출처의 진위를 증명하는 암호학적 서명도 아닙니다. 이 목록은 로컬 일반 파일이 목록에 기록된 요약값과 일치하는지 판단하는 데만 도움을 줍니다.

기본 사용법: 스킬 열람 절차 수립

1단계: 스킬 진입점 선택

처음에는 다음 스킬부터 살펴볼 수 있습니다.

  • wide-research: 연구 코디네이터, worker, 통합 출력 계약 및 실패 처리 범위.
  • skill-creator: 스킬 트리거 설명, 디렉터리 분할 및 필요할 때 로드하는 참고 자료.
  • artifacts/testing: “생성 성공”과 “사용 가능한 결과물”의 구분.
  • goals: 최초 목표 설정과 후속 조치의 구분.
  • forget: 복사본, 파생 상태 및 다시 기록될 수 있는 데이터 처리.
  • travel-planning: 일정 연구, 실시간 조회 및 거래 실행의 분리.
  • gmail: 스킬 본문, 메서드 수준 권한 및 평가 시나리오를 함께 활용한 커넥터 분석.

예를 들어 Gmail 스킬의 진입점을 확인합니다.

sed -n '1,240p' opt/hatch/skills/gmail/SKILL.md

2단계: 트리거 조건과 경계 추출

SKILL.md를 읽을 때는 “무엇을 할 수 있는가”만 기록하지 말고 다음 질문에 차례로 답해야 합니다.

  1. 어떤 요청이 이 스킬을 실행해야 하는가?
  2. 어떤 유사 요청은 실행해서는 안 되는가?
  3. 읽기 전용 작업과 쓰기 작업을 어떻게 구분하는가?
  4. 전송, 삭제, 구매 또는 예약과 같은 영향이 큰 작업에 확인이 필요한가?
  5. 권한 부족, 대상 모호성 또는 도구 실패 상황에서 어떻게 처리해야 하는가?
  6. 최종 결과에 어떤 필드나 근거를 반환해야 하는가?

이 내용을 “트리거, 입력, 승인, 실행, 실패, 검수”의 여섯 부분으로 정리하면 자체 Agent 설계로 옮기기 쉽습니다.

3단계: 권한 manifest와 대조

커넥터 스킬의 경우 같은 디렉터리에 있는 manifest.yaml도 계속 읽어야 합니다.

sed -n '1,260p' opt/hatch/skills/gmail/manifest.yaml

스킬 본문에서 주장하는 작업과 manifest에 선언된 메서드 권한, 그룹 기본값, scope 및 명령 매핑을 중점적으로 비교합니다. 메서드 수준 설정이 그룹 기본값을 덮어쓸 수 있으므로 최상위 권한 설명만 확인해서는 안 됩니다.

SKILL.md를 다른 Agent 환경에 복사한다고 해서 Gmail, Google Drive, Notion 또는 다른 서비스에 대한 접근 권한이 자동으로 부여되지는 않습니다. 실제 실행에는 해당 CLI 또는 MCP, 계정 연결, OAuth scope 및 런타임 승인이 여전히 필요합니다.

4단계: 평가 시나리오 읽기

스킬에 eval/scenarios.yaml이 있다면 규칙을 테스트 가능한 동작으로 변환하는 방식을 계속 확인할 수 있습니다.

sed -n '1,260p' opt/hatch/skills/gmail/eval/scenarios.yaml

평가 시나리오는 다음 동작을 확인하는 데 적합합니다.

  • Agent가 올바른 스킬을 선택했는가.
  • 읽기, 초안 작성, 전송 및 삭제와 같은 위험 수준이 다른 작업을 구분하는가.
  • 정보가 부족할 때 수신자나 작업 대상을 추측하지 않고 먼저 명확히 하는가.
  • 필요할 때 승인이나 확인을 요청하는가.
  • 실패 후 완료되지 않은 항목을 정직하게 보고하는가.

시나리오 파일을 테스트 통과 보고서로 간주해서는 안 됩니다. 과거 문제를 판단하려면 opt/hatch/skills/flightaware/eval/findings.md와 같은 발견 기록을 함께 확인할 수 있으며, 해당 기록의 버전과 테스트 환경에도 주의해야 합니다.

5단계: 관련 참고 자료 확인

일부 스킬은 세부 규칙을 references/, guide/, creation/ 또는 guides/로 분리합니다. 이러한 구조는 중요한 설계 원칙을 보여 줍니다. 즉, 기본 스킬 파일은 간결하게 유지하고 작업에 필요할 때만 더 구체적인 참고 자료를 로드하는 것입니다.

예를 들어 스킬 작성 방법은 다음 파일부터 살펴볼 수 있습니다.

sed -n '1,260p' opt/hatch/skills/skill-creator/references/authoring_guide.md

실전 예시: Gmail 스킬 분석

실제로 메일 계정에 연결하거나 조작하지 않고도 다음 템플릿을 사용해 Gmail 스킬의 설계를 기록할 수 있습니다.

스킬 진입점: opt/hatch/skills/gmail/SKILL.md
권한 정의: opt/hatch/skills/gmail/manifest.yaml
평가 시나리오: opt/hatch/skills/gmail/eval/scenarios.yaml

분석 항목:
1. 메일 검색 및 읽기의 트리거 조건
2. 초안 작성, 전송 및 답장의 작업 경계
3. 라벨 및 구독 취소 절차
4. 메서드 수준 권한과 OAuth scope
5. 수신자, 메일 스레드 또는 작업 의도가 불분명할 때의 처리
6. 도구 실패 후 보고 방식
7. 사용자가 최종적으로 받아야 할 결과와 검증 정보

완료 후 결과를 자체 Agent 사양으로 변환할 수 있습니다.

  • 트리거 규칙: 어떤 언어 패턴이 메일 스킬로 들어가는지 명확히 정의합니다.
  • 읽기 전용 우선: 검색 및 읽기 작업을 전송, 삭제와 같은 변경 작업과 분리하여 처리합니다.
  • 승인 기준: 대상 실행 환경에 맞게 확인 및 OAuth 규칙을 다시 정의합니다.
  • 출력 계약: 성공, 부분 성공 및 실패 시 각각 무엇을 반환할지 규정합니다.
  • 검수 시나리오: 정상 요청, 모호한 요청, 권한 부족 및 커넥터 장애 테스트를 추가합니다.

제품 및 시스템 아키텍처 읽기

제품 계약 빠르게 이해하기

다음 순서로 읽는 것을 권장합니다.

  1. home/hatch/docs/muse.md: 제품 개요.
  2. home/hatch/docs/goals.md: 목표, 진행 상황 및 백그라운드 작업의 범위.
  3. home/hatch/docs/scheduling-and-watching.md: 폴링, 예약, 실행 기록 및 알림.
  4. home/hatch/docs/self_improvement.md: 백그라운드 메모리, 연구, 회고 및 근거 추적.
  5. home/hatch/docs/connectors.md: 연결 상태, OAuth, 메서드 권한 및 실패 처리.
  6. home/hatch/docs/privacy-and-credentials.md: 자격 증명 참조, Vault, 내보내기 및 삭제 규칙.

이 파일들은 스냅샷에 포함된 제품 계약을 설명합니다. 계정별 기능과 과거의 사용 가능성에 대한 설명을 현재 모든 Muse 계정에 적용되는 사실로 간주해서는 안 됩니다.

연구 런타임 시작 체인

Linux 격리 환경에 관심이 있다면 다음 스크립트를 통해 호출 관계를 파악할 수 있습니다.

opt/hatch/runtime-cell/pre-start.sh
opt/hatch/runtime-cell/ensure-rootfs.sh
opt/hatch/runtime-cell/resolve-rootfs-path.sh
opt/hatch/runtime-cell/require-modules.sh
opt/hatch/runtime-cell/launch-daemon.sh
opt/hatch/runtime-cell/post-start.sh

resolve-rootfs-path.sh가 반환하는 /var/lib/hatch-runtime/rootfs는 원래 실행 환경에 있는 경로이며, 저장소에 포함된 디렉터리가 아닙니다. launch-daemon.sh는 systemd-nspawn 컨테이너를 시작하고 overlay를 구성합니다. 따라서 누락된 호스트 설정과 rootfs 없이는 독립적인 시작 안내서로 사용할 수 없습니다.

고급 분석 기법

스킬, 별칭 및 리소스 디렉터리 구분

저장소에는 4개의 심볼릭 링크 별칭이 있습니다. facebook은 facebook-cli를 가리키고, meta-threads는 threads를 가리키며, podcast는 generate_podcast를 가리키고, voice-calls는 voice-selector를 가리킵니다.

링크의 실제 대상을 확인하면 중복 집계를 피할 수 있습니다.

find opt/hatch/skills -type l -name SKILL.md -print -exec readlink {} \;

특히 voice-calls라는 이름만으로 Agent가 대신 전화를 걸 수 있다고 추론해서는 안 됩니다. 이 진입점은 실제로 정적 음성 디렉터리를 가리킵니다. spaces에는 런타임 문서와 템플릿이 포함되어 있지만 최상위 SKILL.md는 없으므로 별도의 스킬로 추가 집계해서는 안 됩니다.

선언, 권한 및 실행 가능한 종속성 동시 검증

스킬을 분석할 때는 다음의 3단계 대조 방법을 사용할 수 있습니다.

  1. 동작 계층: SKILL.md에 선언된 트리거, 범위 및 출력을 확인합니다.
  2. 권한 계층: manifest의 메서드, scope 및 기본 권한을 확인합니다.
  3. 실행 계층: 필요한 CLI, MCP, 보조 프로그램, 계정 연결 및 런타임 리소스가 존재하는지 확인합니다.

저장소에는 Artifacts 검증 스크립트, skill-creator의 커넥터 스캐폴딩, Magic Moment의 mm 실행 파일, 그리고 Spaces에 필요한 일부 SDK 및 빌드 리소스 등 주요 종속성 일부가 명확히 누락되어 있습니다. 따라서 “문서를 읽을 수 있다”는 것이 “실행 체인이 완전하다”는 뜻은 아닙니다.

산출물 생성과 산출물 검수 분리

artifacts/testing은 범용 Agent 패턴을 연구하기에 유용합니다. 이 방식은 파일을 생성한 뒤 산출물 유형에 따라 검사하고, 다시 렌더링하며, 육안으로 검수하고, 플레이스홀더를 검색해야 한다고 강조합니다. 이를 자체 시스템으로 이전할 때는 다음과 같이 프로세스를 나눌 수 있습니다.

  1. 문서, 표, PDF 또는 프레젠테이션을 생성합니다.
  2. 생성 결과를 다시 열거나 렌더링합니다.
  3. 구조, 레이아웃, 수식, 링크 및 누락된 리소스를 확인합니다.
  4. 치환되지 않은 플레이스홀더와 임시 텍스트를 검색합니다.
  5. 검수를 통과한 후에만 파일을 납품 가능 상태로 표시합니다.

다중 Agent 협업 연구

wide-research는 다중 입력 병렬 연구에서 중요한 제약을 보여 줍니다. 조정자와 worker의 책임을 제한하고, 출력 필드를 통일하며, 커버리지를 보고하고, 실패 항목을 보존해야 합니다. 이전할 때는 자체 오케스트레이션 프레임워크에 맞게 도구 이름과 작업 공간 경로를 바꾸되, 통일된 출력 계약과 실패 가시성은 유지해야 합니다.

데이터베이스를 찾기보다 데이터베이스 설명 확인

opt/hatch/skills/muse_db/references/schema.md는 제한된 SQL 규칙, 식별자 및 여러 schema 간의 관계를 설명하며, 데이터 모델과 테이블 간 추적 방식을 이해하는 데 사용할 수 있습니다. 이는 실제 데이터베이스도, 마이그레이션 소스 코드도 아니므로 완전한 서비스를 복원하는 근거로 사용할 수 없습니다.

출처, 라이선스 및 증거의 경계 유지

워크플로를 다른 프로젝트로 이전할 때는 출처 표기를 유지하고 적용 가능한 라이선스를 확인해야 합니다. 내부 분석 기록에서는 다음을 구분하는 것이 좋습니다.

  • 저장소 파일에 직접 서술된 사실.
  • 디렉터리, 스크립트 또는 manifest를 바탕으로 한 기술적 추론.
  • 아직 검증되지 않은 제품 주장.
  • 실행 환경이 누락되어 확인할 수 없는 동작.

“아카이브에서 확인 가능하다”는 것이 “공식 출처가 인증되었다”, “독립적으로 실행할 수 있다” 또는 “임의로 재라이선스할 수 있다”는 뜻은 아닙니다.

권장 학습 경로

  1. 저장소를 복제할 때 LFS를 건너뛰어 불필요한 바이너리 다운로드를 피합니다.
  2. PROJECT_ANALYSIS.md를 읽고 아키텍처 판단과 누락 항목을 파악합니다.
  3. skill-creator 또는 wide-research를 선택해 워크플로 구조를 학습합니다.
  4. gmail을 선택해 스킬 본문, manifest 및 eval을 함께 분석합니다.
  5. artifacts/testing을 읽고 납품물 검수 관점을 익힙니다.
  6. 제품 문서를 읽고 스킬 규칙과 제품 계약을 구분합니다.
  7. 마지막으로 runtime-cell 스크립트를 확인해 런타임 단서와 누락된 종속성을 이해합니다.

맺음말

MuseAI-Skills의 주요 가치는 직접 배포하는 데 있지 않고, 개인 AI Agent가 스킬 트리거, 작업 분배, 커넥터 권한, 실패 처리 및 결과 검수를 어떻게 구성할 수 있는지 보여 주는 데 있습니다. SKILL.md, manifest.yaml, 평가 시나리오 및 실행 종속성을 함께 읽으면 자체 Agent 시스템에 적용할 수 있는 설계 패턴을 도출하는 동시에, 스냅샷을 완전한 소스 코드나 실행 가능한 제품으로 오인하는 일을 피할 수 있습니다.