실험적인 위험한 워크플로(dangerous-workflow) 공개: 이 스킬은 사용자가 설정한 여러 개의 자율 CLI 에이전트(agents), git 브랜치(branches), git 워크트리(worktrees), 머지 작업(merge operations), 테스트 명령(test commands), 백업 명령(backup commands), 그리고 인프라 명령(infrastructure commands)을 조정할 수 있습니다. 이는 Apache-2.0 라이선스 하에 보증 없이 있는 그대로(as-is) 제공됩니다. 수정 권한이 있는 저장소 및 환경에서만 사용하고, 검증된 백업을 유지하며, 생성된 모든 명령과 차이(diff)를 검토하십시오. 또한 이를 사용하거나 수정함으로써 발생하는 데이터 손실, 다운타임, 자격 증명 노출, 비용 또는 원치 않는 변경에 대한 책임은 사용자에게 있습니다.

CLI를 갖춘 모든 에이전트 하네스(agent harness)에서 병렬 에이전트 작업(parallel agentic tasks)을 오케스트레이션하기 위한 범용 에이전트 스킬(Generic Agent Skill)입니다. 워커(Workers)는 리뷰 게이트가 있는 통합(review-gated integration), 변경 로그 요구 사항(changelog requirements), 결정론적 Python/Bash 루프 생성(deterministic Python/Bash loop generation), 그리고 백업 인지 유지 관리 지원(backup-aware maintenance support)을 갖춘 격리된 git 워크트리(git worktrees)에서 실행됩니다. 이 패키지는 범용적입니다. 포함된 JSON 예제는 하나의 구체적인 매핑 하네스로서 Kimi CLI만을 사용합니다. 다른 하네스들은 사용 전에 현재 로컬 도움말 출력과 문서를 바탕으로 매핑되어야 합니다.

이 스크린샷은 워크플로 철학을 포착합니다: 계획(plan), 팬 아웃(fan out), 검증(verify), 통합(integrate); 변경 로그를 먼저 작성하고 머지는 마지막에 수행합니다; 조종(steering)이 필요할 때는 대화형 워커(interactive workers)를 사용하고, 백업, 조건 및 로그의 반복 가능한 실행이 필요할 때는 결정론적 루프(deterministic loops)를 사용합니다.

저장소를 클론(Clone)하고 스킬을 에이전트 하네스에서 사용하는 스킬 디렉토리로 복사하십시오. 프로젝트 로컬 설치의 경우:

git clone https://github.com/TheAhmadOsman/parallel-agent-worktree-skill.git
mkdir -p .agents/skills
cp -R parallel-agent-worktree-skill .agents/skills/parallel-agent-worktree-skill

사용자 레벨 설치의 경우, 로컬 스킬 루트로 복사하십시오. 예시는 다음과 같습니다:

mkdir -p ~/.codex/skills
cp -R parallel-agent-worktree-skill ~/.codex/skills/parallel-agent-worktree-skill
mkdir -p ~/.claude/skills
...

그런 다음 이 프롬프트를 로컬 에이전트에게 전달하십시오:

이 저장소의 parallel-agent-worktree-skill을 설치하고 사용하십시오.
먼저, SKILL.md와 README.md를 읽으십시오. 워크플로우를 실험적인 것으로 취급하고, 명시적인 검토 없이 파괴적인 명령(destructive commands)을 실행하지 마십시오. git, tmux, uv가 설치되어 있는지 확인하십시오.

이 스킬은 CLI 에이전트 하네스(agent harnesses)를 사용하여 대규모 요청을 제한된 병렬 에이전트 작업(parallel agent tasks)으로 전환하는 일반적인 워크플로우를 캡처합니다. 헬퍼 스크립트(helper scripts)는 범용적이며, 프로세스는 의도적으로 하네스에 구애받지 않도록(harness-agnostic) 설계되었습니다. 포함된 예제는 기본 샘플 하네스로 Kimi CLI를, 샘플 변환 대상으로 Codex를 다룹니다.

• 대화형 워커 모드 (Interactive worker mode): tmux 내에서 각 작업당 하나의 CLI 에이전트 워커를 생성하며, 각 워커는 고유한 git 워크트리(git worktree) 내에서 실행됩니다. 이후 후속 프롬프트를 통해 워커를 제어합니다. --agent-cli 및 --agent-args를 사용하여 하네스를 구성하십시오.
• 결정론적 루프 모드 (Deterministic loop mode): JSON으로부터 Bash 또는 Python 스크립트를 생성하고, 사전 점검(preflight) 및 백업 게이트(backup gates)를 실행하며, 비대화형(non-interactive) CLI 에이전트 워커를 실행하고, 모든 아티팩트(artifact)를 로그로 남기며, 통합(integration)은 검토 단계로 남겨둡니다. JSON의 agent 블록을 통해 비대화형 실행을 구성하십시오.

이 스킬은 의도적으로 보수적입니다. 디프(diffs)와 테스트가 검토될 때까지 에이전트의 출력을 신뢰할 수 없는 것으로 취급합니다.

또한 릴리스 노트(release notes)를 작업의 일부로 취급합니다. 모든 병렬 워커는 저장소 표준 변경 로그(changelog)를 업데이트하거나 워커별 변경 로그 조각을 생성해야 하며, 코디네이터(coordinator)는 최종 병합(merge) 전에 해당 항목들을 조정(reconcile)해야 합니다. 승인된 작업은 실행 시작 시 체크아웃된 브랜치에 병합되어 완료되어야 합니다. 만약 병합이 차단될 경우, 코디네이터는 브랜치 이름, 차단 원인, 현재 상태, 검증 상태 및 정확한 다음 명령어를 포함한 명확한 보고서를 남겨야 합니다.

parallel-agent-worktree-skill/
├── SKILL.md
├── README.md
...

uv: 이 저장소의 헬퍼 스크립트, 테스트 및 검증을 위해 권장되는 러너(runner)입니다. 독립형 패키지에는 uv.lock이 포함되어 있어, 의도적으로 새로고침하지 않는 한 검증 시 재현 가능한 개발 툴체인(dev toolchain)을 사용합니다.

• Python 3.12+: 헬퍼 스크립트 실행에 필요합니다.
  git

: 브랜치(branches), 커밋(commits), 디프(diffs), 그리고 git worktree를 위해 필요합니다.

.tmux

: 대화형 워커 모드(interactive worker mode)를 위해 필요합니다.

• 에이전트 하네스 CLI (Agent harness CLI): 현재 워크트리(worktree)에서 실행 가능한 인증된 모든 CLI.
  번들로 제공되는 샘플 플랜은 Kimi Code CLI가 필요합니다:
  kimi

또는 kimi-cli.
Codex CLI, Claude Code, OpenCode, Droid Factory, Pi 또는 기타 로컬 하네스의 경우, 먼저 부모 에이전트에게 해당 하네스의 현재 --help 출력과 로컬 문서를 검사하여 이 스킬을 변환하도록 요청하십시오.
bash
: 생성된 Bash 루프(loops) 및 쉘 기반의 사전 점검(preflight)/백업 단계를 위해 필요합니다.

• git worktree add에 적합한 브랜치를 가진 git 저장소.
• 플랜에 의해 사용될 때의 선택적 인프라 도구: Docker, Docker Compose, LXC, virsh, ssh, 데이터베이스 덤프 클라이언트, ZFS/Btrfs/LVM/restic/borg 도구, 클라우드 CLI 또는 기타 백업 및 배포 유틸리티.
• 선택적 timeout: 생성된 Bash 루프는 사용 가능한 경우 이를 사용하며, 생성된 Python 루프는 내부적으로 워커별 타임아웃을 강제합니다.

이 저장소에서는 uv run python으로 헬퍼 스크립트를 실행하십시오.

프로젝트 레벨 설치:

mkdir -p .agents/skills
cp -R parallel-agent-worktree-skill .agents/skills/parallel-agent-worktree-skill

사용자 레벨 설치:

mkdir -p ~/.codex/skills
cp -R parallel-agent-worktree-skill ~/.codex/skills/parallel-agent-worktree-skill
mkdir -p ~/.claude/skills
...

Codex, Claude Code 및 유사한 하네스들은 ~/.codex/skills 또는 ~/.claude/skills와 같은 사용자 레벨 스킬 디렉토리에서 스킬을 로드할 수 있습니다. Kimi Code CLI는 번들된 샘플 플랜에 의해 사용되며, 커스텀 스킬 루트를 지정할 수도 있습니다:

kimi --skills-dir /path/to/skills

Claude Code는 수동 전용(manual-only) 스킬을 위한 disable-model-invocation과 같은 추가적인 프론트매터(frontmatter)를 지원합니다. 이 패키지는 Claude 전용 키를 포함하고 있지 않은데, 이는 여기서 사용되는 로컬 교차 하네스 검증기(cross-harness validator)가 개방형 스킬 키만 허용하기 때문입니다. 만약 Claude Code가 명시적인 /parallel-agent-worktree-skill 호출을 요구하도록 만들고 싶다면, 검증 후에 로컬 복사본에 해당 키를 추가하십시오.

직접 호출하기:

/skill:parallel-agent-worktree-skill implement this feature by splitting safe work across parallel agents

또는 작업이 병렬 CLI-agent 워커 (CLI-agent workers), git worktrees, harness conversion, 결정론적 워커 루프 (deterministic worker loops), 백업 게이트 (backup gates), 변경 로그 조각 (changelog fragments), 또는 리뷰 게이트 통합 (review-gated integration)을 포함할 때 에이전트가 이를 스스로 발견하도록 하십시오.

계획에 조종 (steering)이 필요할 때 이를 사용하십시오.

uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py spawn api-tests \--base main \--prompt-file /tmp/api-tests.prompt \...

유용한 명령어:

uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py status
uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py capture api-tests --lines 120
uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py send api-tests \...

워커 브랜치 (Worker branches)와 워크트리 (worktrees)는 기본적으로 작업 이름으로 설정됩니다. Tmux 세션은 --session-prefix가 설정되지 않는 한 agent-worker- 접두사를 사용합니다.

각 워커 프롬프트 (worker prompt)에는 해당 작업에 대한 변경 로그 경로 또는 조각 컨벤션 (fragment convention)이 포함되어야 합니다. 만약 단일 CHANGELOG.md 파일이 모든 워커로 하여금 동일한 라인을 수정하도록 강제한다면, 워커들이 .worker-runs/changelog/<task>.md 또는 리포지토리의 표준 조각 디렉토리에 고유한 조각을 작성하게 한 뒤, 통합 (integration) 과정에서 이를 정식 변경 로그 (canonical changelog)로 병합하십시오.

조건, 인벤토리 (inventory), 또는 백업 상태에 따라 워커가 생성되어야 할 때 이를 사용하십시오. 이는 셀프 호스팅 서비스 업그레이드, LXC/Docker/VM 유지보수, 데이터베이스 변경, 플릿 편집 (fleet edits), 그리고 백업 실패 시 모든 워커를 중단시켜야 하는 기타 실행 작업에 더 적합한 경로입니다.

Python 렌더링:

uv run python .agents/skills/parallel-agent-worktree-skill/scripts/render_worker_loop.py \--config .agents/skills/parallel-agent-worktree-skill/examples/self-hosted-upgrade.json \--language python \...

Bash 렌더링:

uv run python .agents/skills/parallel-agent-worktree-skill/scripts/render_worker_loop.py \
--config .agents/skills/parallel-agent-worktree-skill/examples/self-hosted-upgrade.json \
--language bash \
...

Dry run:

DRY_RUN=1 /tmp/run-agent-workers.py
DRY_RUN=1 /tmp/run-agent-workers.sh

Run with stable paths:

RUN_ID=upgrade-2026-04-11 LOG_ROOT=/tmp/parallel-agent-worktree-skill-logs /tmp/run-agent-workers.py

생성된 루프는 기본적으로 .worker-runs/<run-id>/ 아래에 프롬프트, 에이전트 로그, 검증 로그, 매니페스트 및 롤백 노트를 작성합니다. 이 예시에서 태스크 에이전트 로그는 agent.log라는 이름입니다.

run_name: run id에 사용되는 이름.
repo: 저장소 루트 또는 그 내부의 경로.
base: 새로운 worker 브랜치용 기본 참조(ref).
worktree_root: 선택적 worktree 부모 디렉터리. 비어 있으면 <repo>.worktrees를 의미합니다.
.max_parallel: worker 동시성(concurrency).
agent.cli: 선택된 harness의 실행 파일 이름.
agent.work_dir_arg: worktree 경로 앞에 삽입되는 선택적 worktree 플래그. 현재 작업 디렉터리에만 의존하는 harness의 경우 빈 문자열을 사용합니다.
agent.args: 비대화형(non-interactive) harness 인수들.
agent.prompt_mode: 생성된 루프에 대한 프롬프트 전달 모드: stdin, argument, 또는 file.
.agent.prompt_arg: agent.prompt_mode가 argument 또는 file일 때, 프롬프트 텍스트나 프롬프트 파일 경로 앞에 삽입되는 선택적 플래그.
.agent.log_name: 태스크별 에이전트 출력 파일 이름. 기본값은 agent.log입니다.
.agent.timeout_seconds: 생성된 Python에서 worker당 타임아웃 시간.
.preflight: 백업 및 태스크가 실행되기 전에 통과해야 하는 명령어들.
.backups: 조건이 참일 때 태스크 이전에 통과해야 하는 명령어들.
.tasks: worker 정의. 각 태스크는 prompt 또는 prompt_file 중 정확히 하나를 필요로 합니다.
.verify: 해당 태스크의 worktree에서 실행되는 태스크별 명령어들.
.postflight: 모든 태스크가 성공적으로 완료된 후 실행되는 명령어들.
.rollback: 태스크에 실패할 경우 rollback.sh 파일에 기록되는 명령어들.

백업 패턴, 조건 예시, 동시성 규칙 및 예외 케이스(edge cases)에 대해서는 references/deterministic-loops.md를 참조하세요.

SKILL.md

: 에이전트(agents)를 위한 컴팩트한 런타임 워크플로우(runtime workflow). 언제 팬아웃(fan out)할지, 워커(workers)에게 어떻게 프롬프트(prompt)를 줄지, 어떻게 검증(verify)할지, 어떻게 병합(merge)할지, 그리고 어떻게 정리(clean up)할지에 집중합니다.

scripts/agent_workers.py

: 대화형 tmux 워크트리(worktree) 워커 매니저. 범용적이며 --agent-cli, --agent-args, --session-prefix를 인자로 받습니다.

scripts/render_worker_loop.py

: 결정론적(deterministic) Python/Bash 루프 렌더러. JSON agent 블록을 읽어 사전 점검(preflight), 백업(backup), 동시성(concurrency), 로그(log), 롤백(rollback) 및 검증(verification) 동작을 포함하는 감사 가능한 러너(auditable runners)를 생성합니다.

scripts/convert_harness.py

: 대상 하네스(harness)를 위한 1차 패키지 특수화(specializer) 도구. 헬퍼 파일의 이름을 변경하고, 기본값(defaults)을 다시 작성하며, docs/tests/examples를 복사하고, 필수적인 인간 또는 에이전트의 검토를 위한 변환 보고서(conversion report)를 작성합니다.

scripts/self_test.py

: 다운로드한 스킬(skill)을 확인하기 전에 pytest를 설치하고 싶지 않은 사용자를 위한 의존성이 낮은(dependency-light) 패키지 셀프 테스트 도구입니다.

tests/

: 독립형 리포지토리(standalone repo)를 위한 주요 휴대용 테스트 스위트(portable test suite). 이 테스트들은 호스트 프로젝트로부터의 임포트(imports)를 피합니다.

• 호스트 리포지토리 어댑터 테스트: 호스트 스킬 파서(parser)가 이 패키지가 다른 리포지토리 내에 임베드(embedded)되어 있는 동안 이 패키지를 발견하는지만 확인합니다.

이 패키지는 모든 에이전트 CLI가 Kimi와 호환되는 구문(syntax)을 가진다고 주장하지 않습니다. 기본 예제들은 원래 작동하던 설정이었던 Kimi CLI를 위해 만들어졌습니다. 다른 모든 하네스의 경우, 상위 에이전트는 스킬을 사용하기 전에 런타임(runtime)에서 대상 명령 인터페이스(command surface)를 해결해야 합니다:

• 대상 실행 파일(executable)의 현재 도움말(help) 및 버전(version) 명령을 실행합니다.
• 로컬 대상 하네스(target-harness)의 문서, 설정(config), 인증 상태(auth state), 권한(permissions) 및 샌드박스 정책(sandbox policy)을 조사합니다.
• 하네스가 대화형 tmux 사용, 비대화형(non-interactive) 사용, 또는 둘 다를 지원하는지 결정합니다.
• 프롬프트 전달 방식을 명시적으로 매핑합니다: 표준 입력(stdin), 프롬프트 인자(prompt argument), 프롬프트 파일(prompt file), 또는 지원되지 않음.
• 워크트리(worktree) 실행 방식을 명시적으로 매핑합니다: 작업 디렉토리(work-dir) 플래그 사용 또는 워크트리의 현재 작업 디렉토리(cwd)에서 실행.
• 승인(approval), 샌드박스(sandbox), 네트워크(network), 모델(model), 재개/세션(resume/session), 로깅(logging), 종료 코드(exit-code) 및 정리(cleanup) 동작을 매핑합니다.
• 하네스 매핑 JSON을 채우고, scripts/convert_harness.py를 실행한 다음, 게시하거나 사용하기 전에 변환된 출력을 패치하고 테스트합니다.

만약 대상 하네스를 병렬로 안전하게 실행할 수 없거나, 결정론적(deterministically)으로 프롬프트를 수신할 수 없거나, 단일 가변 세션 잠금(mutable session lock)을 공유하거나, 승인 우회(approval bypass) 의미론이 불분명한 경우, 결정론적 병렬 루프(deterministic parallel loops)를 사용하지 마십시오. 수동 승인이 포함된 대화형 워커(interactive workers)를 사용하거나, max_parallel을 1로 줄이거나, 인터페이스를 정규화(normalize)하는 래퍼 스크립트(wrapper script)를 작성하거나, 중단 후 차단 요인을 보고하십시오.

전체 런타임 매핑 체크리스트는 references/harness-portability.md를 참조하십시오.

• Kimi는 오직 examples/self-hosted-upgrade.json 때문에 나타납니다.