TypeScript로 안전하고 에이전트 기반 워크플로우 구축하기

Node가 실행되는 모든 곳에서 실행 가능한 TypeScript 기반의 워크플로우를 안전하게 만드세요.**

skelm은 결정론적 코드, LLM 추론(inference), 그리고 완전한 에이전트 루프를 안전하고 기본적으로 거부하는(default-deny) 실행 모델 뒤에 혼합하여 오케스트레이션하는 타입 기반의 워크플로우를 작성하고 실행하기 위한 TypeScript 프레임워크입니다.

주요 기능:

• TypeScript 네이티브: DSL이나 JSON 설정 없이 실제 .mts 모듈을 사용합니다.
• 기본 거부 보안(Default-deny security): 모든 권한은 명시적으로 선언되어야 합니다.
• 다중 백엔드 에이전트: Anthropic, OpenAI를 포함하여 첫 번째 파티 에이전트, Pi, Opencode (네이티브 또는 ACP), Codex, Vercel AI, ACP (Copilot, Claude Code) 등 다양한 모델을 지원합니다.
• 멀티모달 프롬프트: infer()와 agent() 모두 이미지 콘텐츠 부분을 수용할 수 있습니다. 비전(vision)은 비전 기능을 갖춘 백엔드를 통해 라우팅되며, 나머지 단계에서는 시작 시 거부됩니다. ctx.artifacts와 결합하여 실행 기록에 스크린샷 및 기타 바이너리 증거를 영구 저장할 수 있습니다.
• MCP 네이티브: Model Context Protocol 서버의 라이프사이클을 게이트웨이가 관리합니다.
• 스킬 지원(Skill support): 재사용 가능한 SKILL.md 기능 묶음(capability bundles)은 에이전트 시스템 프롬프트에 주입되며, 게이트웨이 레지스트리에서 allowedSkills를 통해 권한 제한됩니다 (게이트웨이가 skills/**/SKILL.md로부터 자동 발견).
• 트리거가 풍부한 런타임: @skelm/scheduler를 통해 Cron, 간격(intervals), 웹훅을 지원합니다. 또한 게이트웨이의 TriggerCoordinator를 통해 폴링(poll), 큐(queue), 파일 감시(file-watch), 이벤트 소스 트리거를 사용할 수 있습니다.
• 세션 간 메모리: 선택적 에이전트 메모리 통합 (@skelm/agentmemory)을 통해 에이전트는 관찰 내용을 포착하고 실행 전반에 걸쳐 이전 컨텍스트를 기억할 수 있습니다. 이는 기본 거부 agentmemory 권한에 의해 제한되며, 사용자가 옵트인해야 활성화됩니다.

상태: 초기 개발 단계입니다. v1까지 API는 불안정합니다. 피드백과 기여를 환영합니다.

# CLI 설치
npm install -g skelm
# 프로젝트 스캐폴딩
...

skelm run (및 다른 워크플로우/상태 명령)은 로컬 게이트웨이(gateway) 프로세스로 전송됩니다. 만약 게이트웨이가 실행되고 있지 않다면, CLI가 자동으로 백그라운드에서 하나를 시작합니다. 재부팅 후에도 유지되는 감독 서비스로 설치하려면 다음을 사용하세요:

skelm gateway install --systemd # linux
skelm gateway install --launchd # macOS

skelm init

표준 .mts 스캐폴드(scaffolds)를 생성합니다.

모듈 (skelm.config.mts 및 workflows/*.mts)은 package.json의 "type" 설정과 관계없이 Node.js의 네이티브 로더(native loader)가 처리합니다.

이 단계부터 워크플로우를 편집하거나, 에이전트 단계(agent steps)를 추가하고, 스케줄을 설정하거나, 게이트웨이(gateway)를 실행할 수 있습니다:

skelm schedule add workflows/hello.workflow.mts --cron '0 * * * *' # cron 작업
skelm gateway start # 포그라운드 (개발용)

📖 다음: Quickstart 가이드

skelm은 플러그형 어댑터(pluggable adapters)를 통해 여러 AI 백엔드(backends)를 지원합니다. 사용 사례에 맞는 것을 선택하세요:

백엔드 (Backend)	패키지 (Package)	최적의 용도
First-party	@skelm/agent	OpenAI 호환 LLM, 프로세스 내 권한 강제(in-process permission enforcement), 내장된 도구 인터페이스(built-in tool surface), 외부 런타임 의존성 없음
Pi	@skelm/pi	완전한 권한 강제가 적용된 Pi 코딩 에이전트
Opencode	@skelm/opencode	오픈 소스 코딩 에이전트 백엔드 (네이티브; ACP 전송도 지원)
Codex	@skelm/codex	공식 @openai/codex-sdk를 통한 OpenAI Codex — 샌드박스 인식 (read-only / workspace-write), MCP + 스킬 주입(skills injection), 스트리밍, 스레드 재개(thread resumption)
Vercel AI	@skelm/vercel-ai	스트리밍을 지원하는 Vercel AI SDK
ACP	내장됨 (Built-in)	ACP를 통한 GitHub Copilot, Claude Code (Opencode도 네이티브로 사용 가능 — 위 내용 참조)

설정 가이드는 백엔드(Backend) 문서를 참조하고, OpenAI Codex에 대해서는 Codex 백엔드 문서를 참조하세요. Codex는 호스트 codex CLI (codex login) 또는 CODEX_API_KEY를 통해 인증합니다. skelm은 경계(boundary)에서 권한을 검증하는 반면, Codex는 프로세스 내에서 샌드박스를 강제합니다.

— 결정론적 로직(Deterministic logic), API 호출, 데이터 변환: code()
— 단일 LLM 추론 호출: infer()
— 도구, MCP, 스킬을 사용하는 멀티 턴 에이전트 루프: agent()
— 단계들을 병렬로 실행: parallel
— 컬렉션 반복: forEach
— 조건부 실행: branch
— 종료 조건과 함께 반복: loop
— 나중에 일시 중지 및 재개: wait
— ID로 다른 파이프라인 호출: invoke

기본 거부 권한 (Default-deny permissions)— 도구(Tools), MCP 서버, 네트워크 호스트, 파일 시스템 루트는 반드시 선언되어야 합니다.
네트워크 송신 강제 (Network egress enforcement)— 내장된 CONNECT 프록시가 선언되지 않은 외부 연결을 차단합니다.
에이전트별 워크스페이스 (Per-agent workspaces)— 격리된 파일 시스템 루트를 통해 단계 간 데이터 오염을 방지합니다.
변조 방지 감사 (Tamper-evident audit)— 컴플라이언스를 위해 해시 체인(Hash-chained) 방식의 결정 저널을 제공합니다.

코딩 어시스턴트 (Coding assistants)— 채팅을 통해 접근 가능하며, 지속적인 워크스페이스에서 PR(Pull Request)을 생성합니다.
큐 워커 (Queue workers)— Jira, GitHub 또는 이메일을 모니터링하고 티켓에 따라 동작합니다.
이메일 분류 (Email triage)— 분류, 요약 및 감사를 위한 결정 사항을 저널에 기록합니다.
요약 자동화 (Digest automation)— 작업을 분산(Fan out)하고, LLM으로 내용을 보강하여 Slack에 게시합니다.
HTTP 웹훅 (HTTP webhooks)— 외부 이벤트에 의해 트리거되는 타입이 지정된(Typed) 워크플로우를 제공합니다.
리서치 에이전트 (Research agents)— 소스를 폴링(Poll)하고, 조사 결과를 저장하며, 재시작 후에도 작업을 재개합니다.
컴플라이언스 봇 (Compliance bots)— S3 버킷을 모니터링하고, 점검을 실행하며, 필요 시 에이전트에게 에스컬레이션합니다.
UI 자동화 (UI automation)— Vision LLM과 스크린샷 아티팩트를 사용합니다; 기초 레시피(foundations recipe)를 참조하세요.

📁 실행 가능한 시작 지점은 examples/를 확인하세요.

퀵스타트 (Quickstart)— 60초 만에 시작하기
백엔드 (Backends)— 프로바이더(Provider) 아키텍처 및 설정
가이드 (Guides)— 테스트, 플러그인, 작성 패턴
레시피 (Recipes)— 완성된 워크플로우 예시
참조 (Reference)— CLI, HTTP API, OpenAPI 명세
패키지 (Packages)— 패키지 맵 및 책임 범위
기여하기 (Contributing)— 기여 방법

skelm은 자체 테스트를 거칩니다. skelm-self-test는 외부 테스트 러너 없이 skelm 워크플로우를 실행하여 skelm을 검증하는 라이브 에이전트 기반 하네스(agentic harness)입니다.

# skelm-self-test 리포지토리에서
pnpm install
skelm run workflows/test-runner.workflow.mts
...

설정, 환경 변수 및 전체 테스트 계획은 skelm-self-test를 참조하세요.

• GitHub Discussions — 질문 및 사례 공유
• Issues — 버그 보고 및 기능 요청
• Contributing — PR 환영