서론

Claude Code의 Skills를 사용하기 시작하면, 처음에는 "PDF를 처리한다", "커밋 메시지를 작성한다"와 같은 단일 기능 Skill을 하나만 작성하는 경우가 많을 것입니다. 이것도 나름대로 잘 작동합니다.

문제는 현실의 워크플로우가 단일 기능만으로는 수용되지 않는다는 점입니다. "리서치하고", "소재를 고르고", "초안을 쓰고", "PR을 내고", "머지한다"——이것들은 별개의 Skill로 나누고 싶지만, 각각 따로 호출한다면 결국 자신이 지휘자가 되어야 합니다.

Anthropic은 Skills를 **"composable resources"**라고 정의하고 있습니다[1]. 즉, Skills는 처음부터 여러 개를 조합하여 사용하는 것을 전제로 한 설계입니다. 본 기사에서는 "여러 Skill을 어떻게 연쇄시키고, 어디에 상태를 두며, 어디를 AI에게 판단하게 할 것인가"라는 오케스트레이션 (orchestration) 설계에 집중하여 정리합니다.

필자 자신도 이 리포지토리에서 /research-topic과 /publish-article이라는 두 개의 Skill을 사용하고 있으며, 본 기사도 이 두 개를 연쇄시켜 작성하고 있습니다. 후반부에서 그 구성 예시도 소개해 드리겠습니다.

공식이 제시하는 판단 기준: "how"는 Skill, "access"는 MCP

오케스트레이션 설계를 시작하기 전에, Skill의 수비 범위를 확정해 둡시다. Anthropic 공식 블로그는 Skills와 MCP 서버의 구분법을 다음과 같이 제시하고 있습니다[2].

If you're explaining how to do something, that's a skill. If you need Claude to access something, that's MCP.

그리고 양자의 관계는 다음과 같이 이어집니다.

This separation keeps the architecture composable. A single skill can orchestrate multiple MCP servers, while a single MCP server can support dozens of different skills.

즉, 다음과 같은 역할 분담이 됩니다.

• MCP: 외부 시스템(GitHub, Notion, 파일 시스템 등)으로의 접속을 제공하는 "손"
• Skill: "어떻게 사용할지", "어떤 순서로 호출할지"를 정의하는 "두뇌"

Skill이 다른 Skill을 호출하는 것도, Skill이 MCP 서버를 묶는 것도, 모두 **"how의 기술"**로 통일됩니다. 이 관점에서 보면, 오케스트레이션은 특별한 기능이 아니라 Skills의 본래 사용법 그 자체라는 것을 알 수 있습니다.

오픈 표준과 Claude Code 확장을 구분하기

오케스트레이션 기능을 이야기하기 전에, Skills에는 두 가지 레이어가 있다는 점을 의식해 두어야 합니다.

오픈 표준 (agentskills.io/specification)

Agent Skills 사양은 Anthropic이 발단이 되어 오픈 소스화된 규격으로, Claude Code 외에도 Cursor, Codex, Gemini CLI, VS Code, Copilot 등 30개 이상의 클라이언트가 채택하고 있습니다. 표준 프런트매터 (frontmatter)는 다음과 같습니다.

사양서에는 Skill 간 연계·의존 관계·상태 공유에 관한 명시적인 규정은 존재하지 않습니다. 연계는 사양의 범위 외이며, 각 클라이언트가 독자적인 확장으로 실현하도록 설계되어 있습니다.

Claude Code 고유의 확장

Claude Code Docs에서 추가된 프런트매터 필드는 다음과 같습니다.

오케스트레이션을 뒷받침하는 것은 주로 context: fork, hooks, allowed-tools, paths, 그리고 본문 중의 동적 컨텍스트 주입(후술)입니다. 이것들은 Claude Code 고유의 기능이므로, 다른 Skills 클라이언트로의 이식성은 없다는 점에 주의해 두시기 바랍니다.

Skill 연계의 4가지 패턴

여러 Skill을 연쇄시키는 구조는 크게 4가지로 분류할 수 있습니다 [3].

패턴 1: Sequential Linear (직렬)

가장 기본적인 파이프라인입니다. 앞 단계의 출력이 다음 단계의 입력이 됩니다.

/research-topic → /draft-article → /create-pr → /merge-pr

구현은 간단하며, orchestrator slash command가 상태 파일을 읽고 현재 스테이지에 따라 다음 Skill을 호출합니다.

---
name: blog-publish
description: 블로그 기사의 리서치, 초안 작성, 공개를 일련의 흐름으로 실행한다.
...

패턴 2: Parallel Fan-Out and Merge (병렬 전개)

하나의 Skill이 작업을 N개로 분해하고, 서브 에이전트 (Sub-agent)에서 병렬 처리하여 병합(Merge)하는 구조입니다. context: fork를 사용하면 각 Skill 실행이 독립된 컨텍스트에서 돌아가므로, 메인 대화 문맥을 오염시키지 않습니다 [4].

---
name: review-all-changed-files
description: 변경된 파일들을 병렬로 리뷰하고, 지적 사항을 집약한다.
...

서브 에이전트 측은 읽기 전용 도구(Read-only tools)만 가지며, 결과만을 호출 측에 반환합니다. 배치 처리 (Batch processing)의 총 실행 시간을 대폭 단축할 수 있습니다.

패턴 3: Conditional Routing (조건 분기)

오케스트레이터가 실행 시점의 상태를 보고, 다음에 어떤 Skill을 호출할지 결정합니다.

---
name: triage-and-fix
description: 실패한 테스트를 분류하고, 적절한 수정 Skill로 라우팅(Routing)한다.
...

이 패턴에서 중요한 것은 각 Skill이 명확한 상태 (카테고리)를 반환하는 것입니다. 문자열로 모호하게 반환하면 분기가 깨지므로, JSON 필드로 반환하도록 설계하십시오.

패턴 4: Iterative Loop (반복)

성공 조건을 만족할 때까지 Skill을 반복합니다. 최대 반복 횟수나 명확한 성공 조건을 반드시 정의해야 합니다 [3:1] —— 이를 잊으면 폭주하게 됩니다.

---
name: fix-until-green
description: 모든 테스트가 통과할 때까지 또는 5회 반복할 때까지, 실패한 테스트의 수정을 반복한다.
...

상태 관리: JSON을 단일 진실 공급원(Single Source of Truth)으로

여러 Skill을 가로지르는 워크플로에서는 상태를 구조화된 JSON 파일 하나로 집약합니다. 텍스트 파일로 분산시키지 않는 이유는 두 가지가 있습니다.

• 파싱 신뢰성 (Parsing reliability): 일반 텍스트는 모호하며, 각 Skill이 "어디서 읽을지"에 따라 흔들릴 수 있습니다.
• 진실 공급원의 유일성 (Uniqueness of Single Source of Truth): 상태를 여러 파일로 나누면, Skill이 오래된 데이터를 읽을 위험이 생깁니다.

구체적인 필드 설계는 워크플로에 따라 다르지만, 최소한 다음은 필요합니다.

{
"stage": "draft",
"topic": "Skill을 오케스트레이션하는 방법",
...

• stage

• stage는 다음에 실행할 Skill을 결정하는 단일 필드입니다.

• history는 감사(Audit)용이며, 각 Skill은 여기에 자신의 실행 결과를 추가합니다. 경로는 절대 경로가 아닌 상대 경로(리포지토리 어디에서나 참조 가능)를 사용합니다.

3층 책임 분리: 결정론적 스크립트 × SKILL.md × AI 판단

오케스트레이션(Orchestration) 구현에서 가장 효과가 큰 것은 「어디에 무엇을 쓸 것인가」의 책임 분리입니다. playpark의 구현 사례[5]를 참고하여 정리하면 다음과 같습니다.

제1층을 스크립트로 밀어내는 이점은 매우 큽니다.

• **토큰 소비 제로 (Zero token consumption)**로 밀리초(millisecond) 단위로 완료됩니다. 몇 번을 실행해도 동일한 결과가 나옵니다 (재현성).
• 디버깅이 용이합니다 (일반적인 쉘 스크립트로서 단독 실행 가능).

구체적인 분할 예시는 다음과 같습니다.

# scripts/init-state.sh (결정론적 층)
#!/usr/bin/env bash
set -euo pipefail
...

SKILL.md 측에서는 이를 **동적 컨텍스트 주입 (Dynamic context injection)**으로 가져옵니다.

---
name: blog-publish
description: 블로그 기사 리서치부터 공개까지 일괄 실행한다.
...

!cmd 구문은 Claude에게 전달되기 전에 쉘에서 명령을 실행하고, 그 출력을 프롬프트에 삽입합니다[4:1]. Claude가 실행하는 것이 아니라, 사전 전개(Pre-expansion)된다는 점이 포인트입니다. 이를 사용하면 제1층의 결과를 제3층의 AI에게 자연스럽게 전달할 수 있습니다.

${CLAUDE_SKILL_DIR}는 Skill이 위치한 디렉토리의 절대 경로로 전개되는 변수이며, 이를 사용하면 Skill이 personal / project / plugin 중 어디에 위치하더라도 동일한 스크립트를 참조할 수 있습니다.

Skill 라이프사이클에 종속된 hooks

Claude Code는 Skill의 프론트매터(Frontmatter) 내에서 hooks를 정의할 수 있습니다[6]. 이는 해당 Skill이 유효한 동안에만 후크(Hook)가 작동한다는 스코프(Scope)가 부여되는 것이 특징입니다.

---
name: secure-operations
description: 보안 체크와 함께 조작을 실행한다.
...

once: true는 Skill 프론트매터 한정 필드로, settings.json이나 agent frontmatter에서는 무시됩니다. 1세션 중 첫 번째 Bash 실행 직전에 딱 한 번만 보안 체크가 실행되고, 이후에는 실행되지 않습니다.

오케스트레이션에서의 활용 사례는 다음과 같습니다.

• 가드 (Guard): 위험한 Skill을 호출하기 전에 PreToolUse로 방어합니다.
• 측정 (Measurement): PostToolUse로 각 Skill의 실행 로그를 집약합니다.
• 상태 동기화 (State synchronization): Stop (서브 에이전트라면 자동으로 SubagentStop으로 변환됨)에서 상태 파일을 영속화(Persistence)합니다.

Agent Teams와의 혼동 주의

Claude Code에는 "Skills의 오케스트레이션"과는 별개로 Agent Teams라는 기능이 있습니다. 이는 여러 Claude Code 인스턴스를 협조시키는 메커니즘으로, 현재(2026년 5월 기준)는 experimental 단계이며 GA(General Availability)에 도달하지 않았습니다. 이용을 위해서는 다음 조건이 필요합니다[7].

• Claude Code v2.1.32 이상
• settings.json 또는 환경 변수로 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 설정

알려진 제한 사항으로 session resumption / task coordination / shutdown behavior에 과제가 있는 단계입니다.

Skills 오케스트레이션과 Agent Teams는 서로 다른 레이어이며, 이를 혼동하면 아키텍처 설계가 잘못될 수 있습니다.

본 기사에서 다루는 것은 전자입니다. 후자는 안정화될 때까지 기다렸다가 다루는 것이 무난할 것입니다.

안티 패턴 (Anti-patterns) 모음

구현 시 빠지기 쉬운 세 가지 함정을 소개합니다.

안티 패턴 1: 모든 처리를 SKILL.md에 작성하기

LLM에게 모든 것을 맡기면, 매번 동작이 미묘하게 달라지고, 토큰(Token) 소모가 방대해지며, 디버깅이 어려워지는 삼중고를 겪게 됩니다. 결정론적(Deterministic)으로 작성할 수 있는 부분(경로 계산, 날짜 계산, JSON 읽기/쓰기, git 조작)은 모두 스크립트로 분리하십시오.

안티 패턴 2: 페이즈(Phase) 간의 의존 관계를 명시하지 않기

/draft-article
→ /create-thumbnail

과 같이 의존성이 있음에도 이를 작성하지 않으면, 전 단계가 실패해도 에러 판정을 하지 않고 다음 단계가 실행되어 버립니다. 상태 파일에 previous_stage_success: true와 같은 명시적인 플래그를 반드시 두십시오.

안티 패턴 3: 상태 관리(State Management)를 소홀히 하기

도중에 중단되었을 때 처음부터 다시 시작하거나, 중복 생성되는 경우가 있습니다. 상태 파일을 반드시 시작 시점에 읽고, 각 Skill의 실행 완료 시점에 다시 기록하십시오.

이 리포지토리에서의 실례

참고로, 본 기사 자체도 /research-topic
→ /publish-article
의 2단계 Skill로 작성되었습니다. 구성은 다음과 같습니다.

.claude/skills/
├── research-topic/
│ └── SKILL.md # 1차 소스 검증·발화점·임팩트 분석의 3층 리서치
...

사용자가 /research-topic 스킬을 오케스트레이션하는 방법을 실행하면, 리서치 리포트(1차 소스 URL, 후크 후보, 미검증 항목)가 생성됩니다. 이어서 /publish-article 스킬을 오케스트레이션하는 방법을 호출하면, 리서치 결과를 이어받아 기사화 단계로 들어갑니다.

현재 구성에서는 상태 파일을 가지고 있지 않으며, Claude가 대화 문맥(Context)을 통해 두 Skill을 연결하고 있지만, 향후 seed/<slug>/state.json을 도입하면 "리서치가 완료된 토픽을 기사화하기", "중단된 지점부터 재개하기"와 같은 운용이 용이해질 예정입니다.

요약

Claude Code의 Skills는 처음부터 여러 개를 조합하여 사용하는 것을 전제로 한 "composable resources"로 설계되어 있습니다. 오케스트레이션을 구현할 때의 설계 지침을 정리하면 다음과 같습니다.

• **"how → Skill / access → MCP"**의 구분을 철저히 한다.
• 오픈 표준 필드와 Claude Code 확장(Extension)을 구분한다 (이식성과 관련됨).
• 4가지 연계 패턴(Sequential / Parallel / Conditional / Iterative) 중 적절한 것을 선택한다.
• 상태는 JSON 파일 하나로 집약한다.
• 3층 책임 분리(결정론적 스크립트 / 조건 분기 SKILL.md / AI 판단)로 레이어를 나눈다.
• context: fork + hooks + 동적 컨텍스트 주입을 조합하여 오케스트레이션을 구현한다.
• Agent Teams와는 별개의 레이어임을 잊지 않는다.

Skill을 단독으로 작성하기 시작하면 곧바로 "여러 Skill을 어떻게 연쇄시킬 것인가"라는 과제에 직면하게 됩니다. 처음부터 상태 파일과 orchestrator slash command를 포함하여 설계해 두면, 나중에 다시 작성하는 수고를 크게 줄일 수 있을 것입니다.

참고 링크

• Agent Skills Specification - agentskills.io

• Equipping agents for the real world with Agent Skills - Anthropic Engineering

• Extending Claude's capabilities with skills and MCP - Claude Blog

• Extend Claude with skills - Claude Code Docs

• Hooks reference - Claude Code Docs

• Orchestrate teams of Claude Code sessions - Claude Code Docs

• anthropics/skills - GitHub

Equipping agents for the real world with Agent Skills - Anthropic Engineering ↩︎

Extending Claude's capabilities with skills and MCP - Claude Blog ↩︎

Claude Code Skill Collaboration: How to Chain Skills Into End-to-End Workflows - MindStudio ↩︎ ↩︎

【Claude Code】Skillオーケストレーション設計 - 複数Skillを連携させる実践パターン - playpark ↩︎

Orchestrate teams of Claude Code sessions - Claude Code Docs ↩︎