에이전트 스킬 아키텍처 가이드은(는) 무엇을 하나요?
Claude Code, KiloCode, OpenClaw, OpenAI Codex에서 AI 에이전트 스킬을 구축하고 구성하기 위한 종합 참고 자료입니다. SKILL.md 명세, 폴더 구조, 모드 범위 스킬, 에이전트 오케스트레이션, 그리고 자체 호스팅 모델 구성을 다룹니다.
소개
이 가이드는 여러 주요 AI 코딩 에이전트 플랫폼에서 재사용 가능하고 유지보수 가능한 스킬을 설계하기 위한 표준화된 접근 방식을 제공합니다. 스킬은 에이전트가 특정 작업을 수행하도록 지시하는 문서화된 명령, 구성 또는 파일 집합입니다.
SKILL.md 명세
각 스킬은 자신의 목적, 사용법, 의존성을 설명하는 최상위 SKILL.md 파일을 가져야 합니다. 필드:
name: 스킬의 고유 이름description: 스킬의 기능에 대한 간략한 개요platforms: 지원되는 에이전트 플랫폼 목록 (예: claude-code, kilocode, openclaw, codex)version: 시맨틱 버전 관리 문자열modes: (선택 사항) 스킬이 적용되는 모드 또는 컨텍스트configuration: 설정 변수, 환경 변수, 또는 플랫폼별 설정
폴더 구조
권장 스킬 레이아웃:
my-skill/
├── SKILL.md
├── instructions/
│ ├── setup.md
│ └── usage.md
├── configs/
│ ├── claude-code.yaml
│ ├── kilocode.json
│ └── openclaw.toml
├── scripts/
│ └── init.sh
└── examples/
└── basic-usage.md
instructions/: 작업 가이드, 설정 단계configs/: 플랫폼별 설정 파일scripts/: 초기화 또는 배포 스크립트examples/: 사용 시나리오 예시
모드 범위 스킬
모드 범위 스킬은 특정 에이전트 모드(예: 수정, 읽기, 디버깅) 동안만 활성화됩니다. 지원되는 모드:
agent: 자율 작업 실행edit: 코드 수정 제안read: 읽기 전용 분석debug: 문제 해결 및 로깅review: 코드 리뷰 작업
모드 범위 스킬은 SKILL.md의 modes 필드에 해당 모드를 나열하여 정의합니다.
에이전트 오케스트레이션
에이전트 오케스트레이션은 여러 스킬을 조정하여 복잡한 워크플로우를 완료하는 것을 의미합니다.
순차적 오케스트레이션
스킬이 단계별로 실행됩니다:
setup스킬이 환경을 준비합니다.build스킬이 코드를 컴파일합니다.test스킬이 단위 테스트를 실행합니다.
병렬 오케스트레이션
스킬이 동시에 실행됩니다:
linter와formatter가 동시에 실행됩니다.docs와test가 동시에 업데이트됩니다.
조건부 오케스트레이션
스킬이 조건에 따라 실행됩니다:
deploy스킬은test스킬이 성공한 경우에만 실행됩니다.rollback스킬은 배포가 실패한 경우에만 실행됩니다.
자체 호스팅 모델 구성
자체 호스팅 모델을 사용하려면 SKILL.md의 configuration 섹션에서 엔드포인트 URL과 모델 매개변수를 설정합니다.
configuration:
model_endpoint: "http://localhost:8080/v1"
model_name: "my-custom-model"
max_tokens: 4096
temperature: 0.7
지원되는 공급자: ollama, vllm, text-generation-inference, llama.cpp.
예시
Claude Code용 예시 스킬:
# SKILL.md for build-agent skill
name: build-agent
version: 1.0.0
platforms: [claude-code, kilocode]
modes: [agent]
description: Automates build and test pipelines for Node.js projects.
configuration:
node_version: "18"
test_command: "npm run test"
build_command: "npm run build"
참고 자료
기여: 이슈를 열거나 풀 리퀘스트를 제출하여 개선 사항을 제안해 주세요.