claude-agent-sdk
Builds Claude Agent SDK agents in Python. Use when creating custom tools, hooks, sub-agents, or MCP integrations with the Agent SDK. Python 에이전트 구축 시 사용.
Best use case
claude-agent-sdk is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Builds Claude Agent SDK agents in Python. Use when creating custom tools, hooks, sub-agents, or MCP integrations with the Agent SDK. Python 에이전트 구축 시 사용.
Teams using claude-agent-sdk should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/claude-agent-sdk/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How claude-agent-sdk Compares
| Feature / Agent | claude-agent-sdk | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Builds Claude Agent SDK agents in Python. Use when creating custom tools, hooks, sub-agents, or MCP integrations with the Agent SDK. Python 에이전트 구축 시 사용.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
SKILL.md Source
# Claude Agent SDK
Python 기반 독립 실행형 AI 에이전트 코드 생성.
**vs agent-creator**:
| 항목 | agent-creator | claude-agent-sdk |
|------|---------------|------------------|
| 결과물 | `.claude/agents/*.md` | `*.py` 파일 |
| 실행 환경 | Claude Code 내부 | 독립 Python 앱 |
| 용도 | 작업 위임 | 프로덕션 자동화 |
## Instructions
### 워크플로우 1: 새 에이전트 프로젝트
1. **용도 파악**
- 무엇을 자동화할 것인가?
- 어떤 도구가 필요한가? (파일, 명령, 웹, 커스텀)
- 서브에이전트 필요 여부
2. **템플릿 선택**
| 용도 | 템플릿 |
|------|--------|
| 최소 시작 | `templates/basic-agent.py` |
| 커스텀 도구 | `templates/tool-agent.py` |
| 훅 (검증/로깅) | `templates/hook-agent.py` |
| 서브에이전트 | `templates/multi-agent.py` |
| 프로덕션 | `templates/production-agent.py` |
3. **프로젝트 구조 생성**
```
{project}/
├── pyproject.toml
├── agent.py # 메인 에이전트
├── tools.py # 커스텀 도구 (선택)
└── hooks.py # 훅 정의 (선택)
```
4. **코드 생성**: 템플릿 기반으로 사용자 요구에 맞게 수정
### 워크플로우 2: 기능 추가
기존 에이전트에 기능 추가 시:
1. **키워드 → 리소스 매칭**
| 키워드 | 리소스 |
|--------|--------|
| 설치, pyproject | `resources/01-setup.md` |
| query, 기본, 옵션 | `resources/02-query-options.md` |
| 도구, @tool | `resources/03-custom-tools.md` |
| 훅, hook, 검증 | `resources/04-hooks.md` |
| 서브에이전트, 위임 | `resources/05-subagents.md` |
| 세션, resume | `resources/06-sessions.md` |
| MCP, playwright | `resources/07-mcp.md` |
2. **리소스 로드 → 패턴 적용**
### 워크플로우 3: 코드 리뷰/개선
기존 에이전트 코드 분석 요청 시:
1. **구조 확인**: 현재 사용 중인 기능 파악
2. **개선점 제안**:
- 에러 핸들링 추가
- 훅으로 검증/로깅
- 서브에이전트로 분리
- 세션 관리 추가
## 핵심 패턴
### 기본 query()
```python
from claude_agent_sdk import query, ClaudeAgentOptions
async for msg in query(
prompt="작업 지시",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Bash"],
cwd="/path/to/project",
permission_mode="acceptEdits"
)
):
if hasattr(msg, "result"):
print(msg.result)
```
### 커스텀 도구
```python
from claude_agent_sdk import tool, create_sdk_mcp_server
@tool("search", "검색 수행", {"query": str})
async def search(args):
return {"content": [{"type": "text", "text": f"결과: {args['query']}"}]}
server = create_sdk_mcp_server("my-tools", "1.0.0", tools=[search])
```
### 훅
```python
async def validate_bash(input_data, tool_use_id, context):
cmd = input_data.get("tool_input", {}).get("command", "")
if "rm -rf" in cmd:
return {"decision": "block", "reason": "위험한 명령어"}
return {}
options = ClaudeAgentOptions(
hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[validate_bash])]}
)
```
## 중요 원칙
1. **allowed_tools 최소화**: 필요한 도구만 허가
2. **permission_mode 신중히**: `bypassPermissions`는 프로덕션 전용
3. **에러 핸들링**: `try/except`로 graceful 처리
4. **세션 활용**: 장기 작업은 session_id 저장 후 resume
## Technical Details
- `REFERENCE.md`: SDK API 전체 개요
- `resources/`: 기능별 상세 패턴
- `templates/`: 완전한 에이전트 코드Related Skills
claude-guide
Guides Claude Code setup, configuration, and operations. Use when setting up CLAUDE.md, creating rules, configuring hooks, creating slash commands, installing external skills, reviewing configuration, organizing prompt architecture, optimizing delegation strategy, managing context window, or improving Claude Code workflows. Do NOT use for creating new skills (use my-skill-creator) or building Agent SDK agents (use claude-agent-sdk).
tree-sitter
AST parsing, S-expression queries, tag extraction via tree-sitter CLI. Use when parsing code into AST, extracting tags, visualizing syntax trees, or performing structural analysis beyond ast-grep.
tidy
Performs small structural code cleanups (tidyings). Use when preparing code changes, removing dead code, reducing nesting, or cleaning up before feature work.
task-naming
CLI command naming convention for Justfile and Makefile. Enforces GAT (group-action-target) word order, grouped listing, mandatory descriptions. Use when creating Justfile recipes, Makefile targets, or reviewing task runner configs for naming consistency. Also use when asking "what should I name this command?" for task runners. Do NOT use for npm scripts, mise tasks, or Claude Code skill naming.
strategic-thinking
체계적 의사결정 프레임워크. First Principles, Trade-off 분석, Cognitive Bias 점검
security
Security expert hub. Code security review (OWASP Top 10, injection, XSS, credentials), vulnerability assessment (KISA 292 items, Unix/Windows server, web pentest, network, DBMS, cloud), ISMS-P certification (101 items, checklist, implementation plan), EFSR financial regulation compliance (전자금융감독규정, 12 articles). 보안 리뷰, 취약점 점검, 인증 준비, 금융규정 준수.
reflect
방향 수정 신호 감지 및 세션 전체 회고. Use when detecting course correction signals ("아니/잠깐/근데"), session retrospective, or reviewing overall progress. /reflect 또는 "회고해줘"로 수동 호출.
refactoring
기존 코드의 안전한 리팩토링. Characterization Test로 동작 보존하며 구조 개선
recall
Load context from Obsidian vault (journals, session pages) and JSONL session history. Vault 위치/구조는 `documentation` skill 참조. Temporal queries scan JSONL by date, topic queries use ir BM25. Use when "recall", "어제 뭐 했지", "what did we work on", "이전 작업", "session history".
qmd
Searches local markdown notes and documents using ir CLI. Use when searching notes, querying documents, managing collections, or retrieving document content.
qa
기능별 QA 체크리스트 생성, 수동 테스트 실행, 결과 기록. Use when QA 테스트, 체크리스트 만들기, 수동 검증, 기능 확인, qa 진행, checklist. Do NOT use for automated test code (use plan-review tdd / code-review instead) or BDD spec (use plan-review bdd instead).
principles
소프트웨어 공학 원칙 바스켓. 원칙 카탈로그 열람, 코드/설계/프로세스/테스트의 원칙 준수도 평가, 위반 식별 및 개선 가이드. Use when 원칙 평가, 원칙 점검, 원칙 검증, principles check, 코드 품질 근본 진단, 설계 원칙 리뷰, 아키텍처 원칙 점검, 프로세스 원칙 점검, 테스트 원칙 점검, 테스트 설계, or when other review skills need a principled foundation. Do NOT use for specific code review (use code-review), security audit (use security), or strategic decisions (use strategic-thinking).