codebuff-agent 2.1.74__py3-none-any.whl

jupyter_ext/agent/skill_middleware.py

@@ -0,0 +1,257 @@
+"""
+SkillMiddleware
+
+Middleware that provides progressive skill loading for code generation agents.
+Based on LangChain Skills pattern for token-efficient context injection.
+
+Key features:
+- Injects skill metadata into system prompt (~250 tokens)
+- Provides load_skill tool for on-demand full content loading
+- Reads skill definitions from markdown files
+"""
+
+import logging
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+from langchain_core.tools import tool
+from pydantic import BaseModel, Field
+
+from . import custom_skills
+
+logger = logging.getLogger(__name__)
+
+# Skills directory path
+SKILLS_DIR = Path(__file__).parent / "skills"
+
+
+def _parse_skill_metadata(file_path: Path) -> Optional[Dict[str, str]]:
+    """Parse skill metadata from markdown file's YAML frontmatter.
+
+    Expected format:
+    ---
+    name: skill-name
+    description: Skill description
+    ---
+    """
+    try:
+        content = file_path.read_text(encoding="utf-8")
+
+        if not content.startswith("---"):
+            logger.warning(f"Skill file missing YAML frontmatter: {file_path}")
+            return None
+
+        parts = content.split("---", 2)
+        if len(parts) < 3:
+            logger.warning(f"Invalid YAML frontmatter format: {file_path}")
+            return None
+
+        frontmatter = yaml.safe_load(parts[1])
+        if not frontmatter or "name" not in frontmatter:
+            logger.warning(f"Missing 'name' in frontmatter: {file_path}")
+            return None
+
+        return {
+            "name": frontmatter.get("name"),
+            "description": frontmatter.get("description", "No description"),
+            "path": str(file_path),
+        }
+    except Exception as e:
+        logger.error(f"Failed to parse skill file {file_path}: {e}")
+        return None
+
+
+def _load_all_skills() -> Dict[str, Dict[str, str]]:
+    """Load all skill metadata from the skills directory."""
+    skills = {}
+
+    if not SKILLS_DIR.exists():
+        logger.warning(f"Skills directory not found: {SKILLS_DIR}")
+        return skills
+
+    for file_path in SKILLS_DIR.glob("*.md"):
+        metadata = _parse_skill_metadata(file_path)
+        if metadata:
+            skills[metadata["name"]] = metadata
+            logger.debug(f"Loaded skill: {metadata['name']}")
+
+    logger.info(f"Loaded {len(skills)} skills from {SKILLS_DIR}")
+    return skills
+
+
+def _get_skill_content(skill_name: str, skills: Dict[str, Dict[str, str]]) -> str:
+    """Load full content of a skill file (excluding YAML frontmatter)."""
+    if skill_name not in skills:
+        # `_`/`-`·대소문자를 가리지 않는다 — 재정의 판정·codex 와 같은 `skill_key` (이슈 #220)
+        key = custom_skills.skill_key(skill_name)
+        for registered_name in skills:
+            if custom_skills.skill_key(registered_name) == key:
+                skill_name = registered_name
+                break
+    if skill_name not in skills:
+        available = ", ".join(skills.keys())
+        return f"Error: Unknown skill '{skill_name}'. Available skills: {available}"
+
+    try:
+        file_path = Path(skills[skill_name]["path"])
+        if skills[skill_name].get("custom"):
+            return custom_skills.read_body(file_path)
+        content = file_path.read_text(encoding="utf-8")
+
+        # Remove YAML frontmatter
+        if content.startswith("---"):
+            parts = content.split("---", 2)
+            if len(parts) >= 3:
+                content = parts[2].strip()
+
+        return content
+    except Exception as e:
+        return f"Error loading skill '{skill_name}': {str(e)}"
+
+
+def _build_skills_prompt_section(skills: Dict[str, Dict[str, str]]) -> str:
+    """Build the Available Skills section for system prompt injection (~250 tokens)."""
+    if not skills:
+        return ""
+
+    lines = ["## Available Skills"]
+    lines.append("")
+    lines.append("### Context 리소스 정보")
+    lines.append(
+        "Main Agent가 task 호출 시 제공하는 Context에는 다음 정보가 포함됩니다:"
+    )
+    lines.append("- **파일 크기**: `file_size: 200MB`, `total_size: 1.5GB` 등")
+    lines.append("- **시스템 메모리**: `available_memory: 16GB`, `gpu_memory: 8GB` 등")
+    lines.append("- **데이터 행 수**: `row_count: 10000000` 등")
+    lines.append("")
+    lines.append("### 스킬 로드 규칙 (MANDATORY)")
+    lines.append(
+        "**분야 작업이면 설명이 맞는 스킬을 먼저 읽는다** — Athena·Airflow·EMR·Lambda·"
+        "Spring·BigQuery·EDA 같은 작업은 아래 목록에서 설명이 맞는 스킬을 "
+        "load_skill_tool로 읽고 그 규칙을 따른다."
+    )
+    # 로드 기준(파일 크기·행 수·GPU 등)은 각 스킬의 description 에 있다 — codex 도 같은
+    # 목록을 받으므로 여기에 따로 적지 않는다 (이슈 #228)
+    lines.append(
+        "**설명에 적힌 조건(파일 크기·행 수·GPU 등)에 해당하면 코드를 쓰기 전에"
+        " load_skill_tool tool을 먼저 사용하세요"
+        " (tool call로 호출, Python 코드로 작성하지 마세요).**"
+    )
+    lines.append(
+        "조건에 못 미치면(작은 파일·적은 행 수·단순 출력) 또는 Context 에 리소스 정보가"
+        " 없으면 최적화 스킬은 읽지 않는다."
+    )
+    lines.append("")
+
+    for name, metadata in sorted(skills.items()):
+        lines.append(f"- **{name}**: {metadata['description']}")
+
+    return "\n".join(lines)
+
+
+def _create_load_skill_tool(skills: Dict[str, Dict[str, str]]):
+    """Create the load_skill_tool for on-demand skill loading."""
+    available_skills = ", ".join(sorted(skills.keys()))
+
+    class LoadSkillInput(BaseModel):
+        """Input schema for load_skill_tool"""
+
+        skill_name: str = Field(
+            description=f"Name of the skill to load. Available: {available_skills}"
+        )
+
+    @tool(args_schema=LoadSkillInput)
+    def load_skill_tool(skill_name: str) -> str:
+        """
+        Load the full guide of a skill listed in the Available Skills section.
+
+        Use this tool when the task matches a skill's description in that list.
+
+        Args:
+            skill_name: Name of the skill to load
+
+        Returns:
+            Full optimization guide with code patterns and best practices
+        """
+        logger.info(f"Loading skill: {skill_name}")
+        content = _get_skill_content(skill_name, skills)
+
+        if not content.startswith("Error"):
+            logger.info(f"Skill '{skill_name}' loaded: {len(content)} chars")
+
+        return content
+
+    return load_skill_tool
+
+
+class SkillMiddleware:
+    """Middleware that adds skill loading capability to code generation agents.
+
+    This middleware:
+    1. Injects Available Skills section into system prompt (~250 tokens)
+    2. Adds the `load_skill` tool for on-demand content loading
+    3. Enables token-efficient progressive disclosure of optimization guides
+
+    워크스페이스를 주면 커스텀 스킬(`custom_skills`)을 합친다 — 이름이 겹치면 커스텀이
+    이긴다 (이슈 #134). 없으면 내장 스킬만이라 프롬프트가 전과 같다.
+
+    Usage:
+        skill_mw = get_skill_middleware(workspace_root)
+        skills_section = skill_mw.get_prompt_section()
+        tools = skill_mw.get_tools()
+    """
+
+    def __init__(self, workspace_root: Optional[str] = None):
+        custom = custom_skills.discover(workspace_root) if workspace_root else []
+        # 철자만 다른 이름(`athena-sql`)도 같은 스킬이다 — codex 와 같은 판정 (이슈 #220)
+        custom_keys = {custom_skills.skill_key(s.name) for s in custom}
+        builtin = {
+            name: meta
+            for name, meta in _builtin_skills().items()
+            if custom_skills.skill_key(name) not in custom_keys
+        }
+        self.skills = dict(builtin)
+        for s in custom:
+            self.skills[s.name] = {
+                "name": s.name,
+                "description": s.description,
+                "path": str(s.path),
+                "custom": "1",
+            }
+        self.prompt_section = _build_skills_prompt_section(builtin)
+        custom_section = custom_skills.prompt_section(custom, "load_skill_tool")
+        if custom_section:
+            self.prompt_section += "\n\n" + custom_section
+        self.load_skill_tool = _create_load_skill_tool(self.skills)
+
+        logger.info(
+            f"SkillMiddleware initialized with {len(self.skills)} skills: "
+            f"{list(self.skills.keys())}"
+        )
+
+    def get_prompt_section(self) -> str:
+        """Get the Available Skills section for system prompt."""
+        return self.prompt_section
+
+    def get_tools(self) -> List[Any]:
+        """Get the tools provided by this middleware."""
+        return [self.load_skill_tool]
+
+
+@lru_cache(maxsize=1)
+def _builtin_skills() -> Dict[str, Dict[str, str]]:
+    """패키지 옆 내장 스킬은 코드와 함께 움직이므로 프로세스당 한 번 읽는다."""
+    return _load_all_skills()
+
+
+def get_skill_middleware(workspace_root: Optional[str] = None) -> SkillMiddleware:
+    """에이전트를 만들 때마다 새로 만든다.
+
+    커스텀 스킬은 워크스페이스마다 달라서 프로세스 싱글턴으로 둘 수 없다 (이슈 #134).
+    내장 스킬 파싱은 `_builtin_skills` 가 캐시하므로 커스텀 스킬 디렉터리만 다시 훑는다.
+    HTTP 스트림은 에이전트 그래프를 캐시하지만 캐시 키에 스킬 목록이 들어가므로
+    (`http_handlers._skills_cache_key`), 기동 뒤 더한 스킬도 다음 요청부터 목록에 뜬다.
+    """
+    return SkillMiddleware(workspace_root)

jupyter_ext/agent/skills/airflow_dag_development.md

@@ -0,0 +1,36 @@
+---
+name: airflow_dag_development
+description: 'Airflow Development & Operations Workflow. 이런 요청에 쓴다: airflow, dag, operator, taskflow, 에어플로우, mwaa, composer, cloud composer, 워크플로우 오케스트레이션, airflow 튜닝, airflow 에러, airflow 로그, task concurrency, parallelism, pool slot'
+---
+## Airflow Development & Operations Workflow
+1. **Structure**: default_args, DAG context, task dependencies
+2. **Tune**: parallelism, concurrency, pool slots, scheduler tuning
+3. **Debug**: task logs, scheduler logs, error tracing
+4. **Validate**: python -c "from airflow.models import DagBag; ..."
+5. **Deploy**: MWAA S3 sync / Composer GCS bucket upload
+
+## Guidelines
+- DAG ID는 snake_case, 설명적 이름 사용
+- default_args에 owner, retries, retry_delay 포함
+- catchup=False를 기본으로 설정
+
+## 분석 작성 가이드
+- DAG 구조 시각화: Mermaid graph로 task dependency 표현
+- 병목 지점 식별: 성능 이슈 원인 분석
+- 플랫폼별 차이: MWAA vs Composer 구분 명시
+- 에러 패턴: 에러 메시지 → 원인 → 영향도 분석
+- 로그 해석: 핵심 로그 라인 인용 및 의미 설명
+
+## Mermaid 다이어그램 컬러 코딩
+- 정상/성공: `fill:#4CAF50,color:white` (green)
+- 경고/주의: `fill:#FF9800,color:white` (orange)
+- 에러/병목: `fill:#F44336,color:white` (red)
+- 정보/중립: `fill:#2196F3,color:white` (blue)
+- 대기/미실행: `fill:#9E9E9E,color:white` (gray)
+
+## 권고 작성 가이드
+- 구체적 설정값 제시 (airflow.cfg 파라미터)
+- MWAA와 Composer 각각의 설정 방법 명시
+- 단계별 적용 가이드 (순서 중요한 경우)
+- 검증 방법 포함
+- 모든 설정 권고에 MWAA/Composer 플랫폼별 적용 방법 포함

jupyter_ext/agent/skills/anomaly_detection.md

@@ -0,0 +1,12 @@
+---
+name: anomaly_detection
+description: 'Anomaly Detection Template. 이런 요청에 쓴다: anomaly detection, isolation forest, outlier detection, 이상탐지, 이상치 탐지'
+---
+## Anomaly Detection Template
+1. **EDA**: Distribution plots, box plots to visually identify outliers
+2. **Statistical Methods**: Z-score (|z| > 3), IQR (< Q1-1.5*IQR or > Q3+1.5*IQR)
+3. **Isolation Forest**: `IsolationForest(contamination=0.05).fit_predict(X)`
+4. **Local Outlier Factor**: `LocalOutlierFactor(n_neighbors=20)`
+5. **Evaluation**: If labels available — precision, recall; otherwise visual inspection
+6. **Visualization**: Scatter plot highlighting anomalies, time-series anomaly overlay
+7. **Action**: Remove, cap, or flag anomalies based on domain context

jupyter_ext/agent/skills/athena_sql.md

@@ -0,0 +1,156 @@
+---
+name: athena_sql
+description: Athena(Trino) SQL 작성·튜닝. BDP 테이블 조회 쿼리 작성, 파티션 프루닝으로 스캔 비용 절감, EXPLAIN 오류 수정, Iceberg DML 제약 확인.
+---
+
+# Athena SQL 가이드
+BDP의 테이블은 Athena 쿼리로만 수행이 가능. 
+Athena는 Trino(Presto) 기반 서버리스 SQL 엔진. S3 데이터를 직접 쿼리. 과금: 스캔 데이터 $5/TB.
+
+## 엔진 특성
+
+- DML: SELECT, INSERT INTO, UPDATE, DELETE, MERGE INTO (Iceberg 테이블만)
+- DDL: CREATE TABLE, CREATE VIEW, ALTER TABLE, DROP TABLE, CTAS
+- DDL은 HiveQL 기반 (백틱 `\`` 사용), DML은 Trino 기반 (큰따옴표 `"` 사용)
+
+## BDP에서 Athena 쿼리 수행 시 주의할 점
+- 반드시 테이블 명 앞에 DB명을 명시하여 SQL을 생성 (예시: wdp_bdp_dlk_l1_msk_view.card_pchs)
+- 숫자 컬럼 집계 시 NULL 처리 필수: SUM(COALESCE(col, 0)), AVG(COALESCE(col, 0))
+- SELECT에 있는 비집계 컬럼은 GROUP BY에 빠짐없이 포함
+- **Athena는 영문 컬럼 alias만 지원합니다.** `AS 한글명` 문법을 사용하지 마세요. 컬럼명을 한글화하지 마세요.
+- 주요 로직(조인 조건, 필터, 집계 등)에 한글 주석을 간결하게 추가 (-- 형식)
+
+## 데이터 타입
+
+| 타입 | 설명 | 예시 |
+|------|------|------|
+| `STRING` / `VARCHAR` | 문자열 | `'hello'` |
+| `INT` / `BIGINT` | 정수 | `42` |
+| `DOUBLE` | 실수 | `3.14` |
+| `DECIMAL(p,s)` | 고정 소수점 | `DECIMAL(18,2)` |
+| `DATE` | 날짜 | `DATE '2024-01-15'` |
+| `TIMESTAMP` | 일시 | `TIMESTAMP '2024-01-15 10:30:00'` (공백 필수, T 사용 불가) |
+| `BOOLEAN` | 불리언 | `TRUE` / `FALSE` |
+| `ARRAY<T>` | 배열 | `ARRAY[1, 2, 3]` |
+| `MAP<K,V>` | 맵 | `MAP(ARRAY['a'], ARRAY[1])` |
+| `STRUCT` | 구조체 | `ROW(name VARCHAR, age INT)` |
+
+### 타입 주의사항
+- TIMESTAMP 형식: `YYYY-MM-DD HH:MM:SS.SSS` (T 구분자 사용 불가)
+- 파티션 키는 `STRING` 권장 (DATE 타입은 성능 저하)
+- Long → Timestamp 암묵적 변환 불가 → `from_unixtime()` 사용
+- `CONCAT()`은 최소 2개 인자 필요
+
+## 날짜/시간 함수
+
+| 함수 | 설명 | 예시 |
+|------|------|------|
+| `current_date` | 오늘 날짜 | `WHERE dt = current_date` |
+| `current_timestamp` | 현재 시각 | |
+| `date_add('day', n, date)` | 날짜 더하기 | `date_add('day', -7, current_date)` |
+| `date_diff('day', d1, d2)` | 날짜 차이 | `date_diff('day', start_dt, end_dt)` |
+| `date_trunc('month', dt)` | 절삭 | `date_trunc('month', txn_date)` |
+| `format_datetime(ts, fmt)` | 포맷 | `format_datetime(ts, 'yyyy-MM-dd')` |
+| `date_parse(str, fmt)` | 파싱 | `date_parse('2024-01-15', '%Y-%m-%d')` |
+| `from_unixtime(epoch)` | 에포크→타임스탬프 | `from_unixtime(1705276800)` |
+| `to_unixtime(ts)` | 타임스탬프→에포크 | `to_unixtime(current_timestamp)` |
+| `year(dt)` / `month(dt)` / `day(dt)` | 추출 | `year(txn_date) = 2024` |
+
+**주의**: `date_format()` 대신 `format_datetime()` 권장 (동작이 더 직관적).
+
+## 문자열 함수
+
+| 함수 | 설명 |
+|------|------|
+| `LOWER(s)` / `UPPER(s)` | 대소문자 |
+| `TRIM(s)` / `LTRIM(s)` / `RTRIM(s)` | 공백 제거 |
+| `LENGTH(s)` | 길이 |
+| `SUBSTR(s, start, len)` | 부분 문자열 |
+| `REPLACE(s, from, to)` | 치환 |
+| `SPLIT(s, delim)` | 분할 → 배열 |
+| `REGEXP_EXTRACT(s, pattern, group)` | 정규식 추출 |
+| `REGEXP_LIKE(s, pattern)` | 정규식 매칭 |
+| `CONCAT(s1, s2, ...)` | 연결 (최소 2개 인자) |
+| `COALESCE(a, b, ...)` | NULL 대체 |
+| `CAST(x AS type)` | 타입 변환 |
+
+## 윈도우 함수
+
+```sql
+-- ROW_NUMBER: 순위
+SELECT *, ROW_NUMBER() OVER (PARTITION BY user_id ORDER BY txn_date DESC) rn
+FROM db.txn;
+
+-- LAG / LEAD: 이전/다음 행
+SELECT txn_date, amount,
+       LAG(amount) OVER (ORDER BY txn_date) prev_amount,
+       LEAD(amount) OVER (ORDER BY txn_date) next_amount
+FROM db.txn;
+
+-- 누적합
+SELECT txn_date, amount,
+       SUM(amount) OVER (ORDER BY txn_date ROWS UNBOUNDED PRECEDING) running_total
+FROM db.txn;
+
+-- FIRST_VALUE / LAST_VALUE
+SELECT *, FIRST_VALUE(amount) OVER (PARTITION BY category ORDER BY txn_date) first_amt
+FROM db.txn;
+```
+
+**주의**: `IGNORE NULLS`는 `first_value`, `last_value`, `nth_value`, `lag`, `lead`에서만 사용 가능.
+
+## JOIN
+**JOIN 최적화**: 작은 테이블을 오른쪽(또는 JOIN의 두 번째)에 배치.
+
+## CTAS (Create Table As Select)
+
+```sql
+-- Parquet + Snappy 압축으로 결과 저장
+CREATE TABLE db.result
+WITH (format = 'PARQUET', write_compression = 'SNAPPY', external_location = 's3://bucket/result/')
+AS SELECT * FROM db.source WHERE condition;
+
+-- 파티셔닝 포함
+CREATE TABLE db.result
+WITH (format = 'PARQUET', partitioned_by = ARRAY['dt'])
+AS SELECT col1, col2, dt FROM db.source;
+```
+
+## 성능 최적화
+
+- Optimize for performance:
+  - Use appropriate aggregations
+
+### 1. 파티션 프루닝 (가장 중요)
+- 반드시 테이블의 파티션키를 먼저 파악하고 해당 컬럼을 최대한 활용한다.
+```sql
+-- 좋음: 파티션 키(dt)로 필터
+SELECT * FROM db.txn WHERE dt = DATE '2024-01-15';
+
+-- 나쁨: 파티션 키 없이 전체 스캔
+SELECT * FROM db.txn WHERE amount > 1000;
+```
+
+### 2. 컬럼 프루닝
+```sql
+-- 좋음: 필요한 컬럼만
+SELECT id, name, amount FROM db.txn;
+
+-- 나쁨: 전체 컬럼
+SELECT * FROM db.txn;
+```
+
+### 4. LIMIT 활용
+```sql
+-- 탐색적 쿼리에 LIMIT 필수
+SELECT * FROM db.large_table LIMIT 100;
+```
+
+### 5. APPROX 함수 (대용량)
+```sql
+-- 정확한 COUNT DISTINCT 대신
+SELECT APPROX_DISTINCT(user_id) FROM db.txn;
+
+-- 백분위수
+SELECT APPROX_PERCENTILE(amount, 0.95) FROM db.txn;
+```

jupyter_ext/agent/skills/bdp_table_search.md

@@ -0,0 +1,33 @@
+---
+name: bdp_table_search
+description: 쿼리 도우미의 BDP 테이블 메타데이터 검색(rag_search·get_table_columns) 규칙. 두 도구가 있을 때만 쓴다 — SQL을 쓰기 전에 실제 테이블명·컬럼명·DB명을 검색 결과로 확인할 때.
+---
+# BDP 테이블 검색
+
+**[기존 SQL]이 존재할 때 반드시 정확한 테이블 정보 확인을 위해 rag_search를 호출한 후 응답을 생성하세요**
+
+## RAG 검색 도구
+
+rag_search로 BDP 테이블 메타데이터를 검색할 수 있습니다.
+[기존 SQL]이 제공된 경우에도, SQL에 사용된 테이블명을 match_text에 지정하여 반드시 rag_search를 호출하세요.
+**절대로 검색 결과 없이 테이블명이나 컬럼명을 만들어내지 마세요.**
+
+### 컬렉션
+- **bdp_tables**: BDP 테이블 메타데이터 (테이블명, 컬럼명, 타입, 스키마)
+
+### 도구 호출 규칙
+1. **`rag_search`**: queries 배열에 쿼리를 담아 **1회만 호출**. bdp_tables 컬렉션 사용.
+   - **query 작성법**: 반드시 `"필드명:값"` 형식을 사용하거나 자연어 키워드로 작성하세요.
+     예: `"테이블명:card_pchs"`, `"테이블한글명:카드매출"`, `"컬럼명:brno"`, `"원천DB명:ADW"`
+     모르는 정보만 있을 땐 자연어 키워드도 가능: `"카드매출 관련 테이블"`
+   - **match_text**: 정확한 테이블 영문명을 알 때 추가. 예: `"match_text": ["card_pchs"]`
+2. **`get_table_columns`**: 테이블의 전체 컬럼 목록을 조회. rag_search 결과에서 컬럼이 축약된 경우 사용.
+   - 예: `get_table_columns(table_name="card_pchs", collection="bdp_tables")`
+3. 결과가 0건일 때만 쿼리를 변경하여 1회 재시도를 허용합니다.
+
+### 검색 결과 사용 시 주의사항
+- 테이블명, 컬럼명 등 고유명사는 **RAG 검색 결과에 있는 값을 그대로** 사용하세요.
+- 검색 결과에 "[토큰 제한으로 컬럼 정보가 축약되었습니다]" 안내가 있으면 get_table_columns로 전체 컬럼을 조회하세요.
+
+### 도구 호출 시 주의사항
+- 도구 호출(tool call)이 필요하면, content에는 "검색 중입니다"처럼 **한 줄 상태 메시지만** 넣으세요.

jupyter_ext/agent/skills/bigquery.md

@@ -0,0 +1,65 @@
+---
+name: bigquery
+description: BigQuery 요청(쿼리 설명·오류 수정·성능 튜닝·비용 분석·Oracle→BQ 변환)이면 먼저 읽는 라우터. 요청 유형별 응답 구조와 Mermaid 시각화 규칙을 담고, 세부 가이드는 bigquery_tuning, bigquery_oracle 참조.
+---
+
+# BigQuery Expert Guide
+
+BQ agent의 3대 역할별 세부 가이드:
+
+| 요청 유형 | 로드할 스킬 | 설명 |
+|-----------|------------|------|
+| 성능 튜닝 / 비용 최적화 / anti-pattern | `bigquery_tuning` | 900-slot 최적화, anti-pattern 10종, 비용 공식, INFORMATION_SCHEMA |
+| Oracle → BQ 변환 | `bigquery_oracle` | 구문 매핑, 실행 모델 비교, Hint 대체, anti-pattern 체크 |
+| 쿼리 오류 수정 | `bigquery_tuning` | anti-pattern 탐지 + 비용/성능 분석으로 오류 원인 진단 |
+
+## 사용법
+1. 요청 유형 판단
+2. `bigquery_tuning` 또는 `bigquery_oracle` 스킬 본문을 읽는다
+3. 두 가지 모두 필요하면 둘 다 읽는다
+
+## 응답 구조 가이드
+
+### Oracle→BQ 변환 시:
+- **변환 개요**: 변환 배경, 핵심 변경사항 3~5줄 요약, Oracle 전용 구문 개수
+- **SQL**: ```sql 블록에 변환된 SQL (인라인 주석으로 변경 포인트 설명)
+- **구문 매핑 상세**: 각 Oracle→BQ 구문 변환의 동작 차이, 주의사항, 엣지 케이스를 매핑 테이블 + 서술로 설명
+- **실행 흐름 비교**: Oracle vs BQ 실행 방식을 **Mermaid 다이어그램**으로 시각화 + 비교 테이블 (인덱스 vs 컬럼나, 비용 모델 등)
+- **데이터 타입 주의사항**: 암묵적 형변환, 정밀도 차이, NULL 처리 차이
+- **BQ 최적화 권고**: 파티셔닝, 클러스터링, 매터리얼라이즈드 뷰 등 구체적 제안
+
+### 성능 튜닝 시:
+- **쿼리 분석 요약**: 쿼리 목적, 현재 성능 특성
+- **SQL**: ```sql 블록에 최적화된 SQL
+- **Anti-pattern 탐지**: 발견된 anti-pattern과 개선 방안 (코드 스니펫 포함)
+- **실행 계획 분석**: 예상 슬롯 사용량, 병렬화 전략을 **Mermaid 다이어그램**으로 시각화
+- **비용 분석**: 바이트 처리량, 비용 절감 방안
+- **파티셔닝/클러스터링 권고**: 구체적 DDL 예시 포함
+
+### 오류 수정 시:
+- **에러 원인 분석**: 에러 메시지 해석, 근본 원인
+- **SQL**: ```sql 블록에 수정된 SQL
+- **오류 흐름 시각화**: 에러 발생 흐름 → 수정 후 정상 흐름을 **Mermaid 다이어그램**으로 표현
+- **수정 내용 상세**: 각 수정 포인트의 이유와 영향
+- **유사 오류 방지 가이드**: 같은 실수를 피하는 패턴
+
+### 쿼리 설명 시:
+- **쿼리 목적**: 비즈니스 로직과 데이터 흐름
+- **SQL**: ```sql 블록에 원본 SQL (주석으로 각 절의 역할 설명)
+- **실행 흐름 단계별 분석**: FROM → WHERE → GROUP BY → SELECT 순서로 데이터 흐름을 **Mermaid 다이어그램**으로 시각화 + 설명
+- **성능 특성**: 예상 비용, 병목 구간
+- **개선 포인트**: 성능/가독성 개선 제안
+
+### 복합 요청 시:
+해당하는 모든 섹션을 논리적 순서로 구성하세요.
+
+## 작성 원칙
+- 각 섹션은 충분히 상세하게 서술하세요 (chat 모드 수준의 풍부함)
+- 코드 스니펫은 마크다운 코드 블록으로 제시
+- 매핑 테이블과 서술을 병행하여 이해도를 높이세요
+
+## ⚠️ 필수: Mermaid 시각화
+
+**모든 BQ 응답에는 반드시 ```mermaid 다이어그램을 포함하세요.** 시각화 없는 응답은 불완전합니다.
+- 쿼리 설명: 데이터 흐름을 단계별 Mermaid 다이어그램으로 시각화
+- 튜닝·오류 수정·변환은 세부 스킬의 필수 출력 규칙을 따른다