Communitygithub.com

심층 연구 스킬 (Deep Research Skill)

OpenAI Deep Research API를 활용하여 모든 주제에 대한 포괄적인 연구를 수행합니다. 대화형 질문으로 프롬프트를 개선하고, 연구 매개변수를 저장하며, 웹 검색을 통해 심층 연구를 실행합니다.

심층 연구 스킬 (Deep Research Skill)란 무엇인가요?

이 스킬은 사용자의 연구 요청을 받아 OpenAI의 o4-mini-deep-research 모델을 통해 심층적인 웹 검색 기반 연구를 수행하는 도구입니다. 사용자의 초기 프롬프트가 너무 짧거나 모호할 경우, 스마트하게 2~3개의 명확화 질문을 던져 연구 범위, 깊이, 초점 영역을 구체화합니다. 이러한 질문은 기술적 연구와 일반 연구에 따라 템플릿이 달라지며, 사용자는 번호 선택 또는 직접 입력으로 답변할 수 있습니다. 개선된 프롬프트는 타임스탬프가 포함된 파일에 저장되어 재현성을 보장하고, 이후 'deep_research.py' 스크립트가 동기식으로 실행되어 최종 보고서(마크다운 형식)와 출처 URL을 생성합니다. 연구는 보통 10~20분이 소요되며, Claude는 중간 상태를 폴링하지 않고 종료를 기다린 후 결과를 제시함으로써 토큰 사용을 최소화합니다. 이 스킬은 Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 사용 가능하며, OPENAI_API_KEY 환경 변수가 필요합니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/claude_skills_libraries/landing-page-mastery/skills/deep-research

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

심층 연구 스킬

목적

이 스킬은 OpenAI의 Deep Research API(o4-mini-deep-research 모델)를 사용하여 모든 주제에 대해 인터넷을 활용한 포괄적인 연구를 수행할 수 있게 해줍니다. 대화형 질문을 통해 사용자의 연구 프롬프트를 지능적으로 개선하고, 연구 매개변수를 재현 가능하도록 저장하며, 웹 검색 기능을 갖춘 심층 연구를 실행합니다.

이 스킬을 사용해야 하는 경우

다음과 같은 상황에서 이 스킬을 실행하세요:

  • 사용자가 특정 주제에 대한 연구를 요청할 때
  • 사용자가 분석, 조사 또는 포괄적인 정보 수집을 요청할 때
  • 사용자가 웹 검색과 추론을 사용한 주제 탐색을 원할 때
  • 사용자가 개선될 수 있는 간단한 연구 질문을 제공할 때
  • 사용자가 특정 분야의 현재 상태, 트렌드 또는 비교를 이해하려고 할 때

사용자 요청 예시:

  • "벤치마크 성능이 높은 가장 효과적인 오픈소스 RAG 솔루션을 조사해줘"
  • "2025년 최신 AI 발전 현황은?"
  • "분산 데이터베이스 시스템에 대한 포괄적인 분석이 필요해"
  • "벡터 검색 구현을 위한 모범 사례를 찾아줘"
  • "AI가 소프트웨어 엔지니어링 산업에 미치는 영향을 조사해줘"

워크플로우 개요

사용자 입력
    ↓
평가: 프롬프트가 너무 짧은가?
    ↓
예 → 개선 질문하기 → 답변 수집
    ↓                               ↓
    └───────→ 개선된 프롬프트 구성 ←──┘
                    ↓
            타임스탬프 파일에 저장
                    ↓
            deep_research.py 실행
                    ↓
            보고서 + 출처 출력
                    ↓
            사용자에게 제시

Claude가 이 스킬을 사용하는 방법

토큰 효율성 중요 사항: 심층 연구는 완료하는 데 10~20분이 걸립니다. 이 스킬은 중간 상태 확인 없이 동기식(차단)으로 실행되도록 설계되었습니다. 이 접근 방식은 대기 중 토큰 사용을 최소화합니다. Claude는 다음을 수행해야 합니다:

  1. 연구 시작
  2. 완료 대기(서브프로세스가 자동으로 차단됨)
  3. 완료되면 최종 결과 제공

실행 중에 주기적인 폴링이나 상태 업데이트가 필요하지 않습니다.

1단계: 연구 요청 수락

사용자의 연구 프롬프트를 받습니다. 이는 간단한 것("최신 AI 트렌드")부터 매우 상세한 것("2024-2025년에 초점을 맞춘 개발자 생산성에 대한 언어 모델의 영향")까지 다양할 수 있습니다.

2단계: 오케스트레이션 스크립트 실행

사용자의 연구 프롬프트와 함께 스킬의 메인 오케스트레이션 스크립트를 실행합니다:

python3 scripts/run_deep_research.py "여기에 연구 프롬프트를 입력하세요"

스크립트는 스킬 설치 디렉토리 내의 scripts/run_deep_research.py에 있습니다.

3단계: 스크립트 실행 흐름

스크립트는 자동으로 다음을 수행합니다:

  1. 프롬프트 완전성 평가: 프롬프트가 너무 짧거나 일반적인지 확인합니다(15단어 미만 또는 "무엇인가요", "방법" 등으로 시작).

  2. 필요한 경우 명확화 질문:

    • 연구 유형에 맞는 2-3개의 집중된 질문 제시
    • 키워드 기반으로 연구가 기술적인지 일반적인지 감지
    • 사전 정의된 옵션(1-4) 선택 또는 사용자 정의 텍스트 입력 허용
    • 질문 범위: 범위/기간, 깊이 수준, 초점 영역
  3. 프롬프트 개선: 원본 프롬프트와 사용자 답변을 결합하여 구조화된 연구 매개변수 생성

  4. 프롬프트 파일 저장: 개선된 프롬프트를 research_prompt_YYYYMMDD_HHMMSS.txt에 저장하여 재현성 확보

  5. 심층 연구 실행: 핵심 deep_research.py 스크립트를 다음 설정으로 실행:

    • 모델: o4-mini-deep-research (--model로 설정 가능)
    • 타임아웃: 1800초 / 30분 (--timeout으로 설정 가능)
    • 도구: 웹 검색 기본 활성화

4단계: 결과를 사용자에게 제시

스크립트는 자동으로:

  • 마크다운 파일 저장: 출처가 포함된 연구 보고서가 research_report_YYYYMMDD_HHMMSS.md에 저장됩니다.
  • 터미널에 출력: 마크다운 형식의 완전한 연구 보고서 출력
  • 웹 출처 목록: 연구에서 참조된 번호가 매겨진 URL 목록
  • 완료 확인: 연구 파일이 저장된 경로

토큰 효율성 참고: 심층 연구는 10~20분이 소요됩니다. 스크립트는 중간 폴링 없이 동기식(차단)으로 실행되어 대기 중 토큰 사용을 최소화합니다.

번들 리소스

스크립트

scripts/run_deep_research.py (메인 진입점)

다음을 처리하는 오케스트레이션 스크립트:

  • 프롬프트 품질 평가
  • 대화형 개선 질문(기술 연구와 일반 연구를 스마트하게 구분)
  • 프롬프트 저장 및 타임스탬프
  • 핵심 심층 연구 실행

주요 기능:

  • 스마트 개선: 프롬프트가 짧거나 일반적인 경우에만 질문
  • 템플릿 기반 질문: 기술 연구와 일반 연구에 대해 다른 질문 세트
  • 유연한 입력: 번호 옵션 + 사용자 정의 텍스트 입력
  • 오류 처리: deep_research.py가 없을 경우 도움말 메시지 출력

사용 가능한 옵션:

python3 run_deep_research.py <프롬프트> [옵션]
  --no-enhance              개선 질문 건너뛰기
  --model <모델>            사용할 모델 (기본값: o4-mini-deep-research)
  --timeout <초>            타임아웃 (초) (기본값: 1800)
  --output-dir <경로>       프롬프트 파일을 저장할 위치

assets/deep_research.py

OpenAI Deep Research API와 인터페이스하는 핵심 스크립트. 다음을 처리합니다:

  • OPENAI_API_KEY를 통한 API 인증
  • 요청 생성 및 실행
  • 자동 마크다운 저장: 기본적으로 타임스탬프가 포함된 보고서 파일 저장
  • 출력 형식 지정 (메타데이터가 포함된 보고서 + 출처)
  • 오류 처리 및 재시도

새로운 명령줄 옵션:

--output-file <경로>      사용자 정의 출력 파일 경로
--no-save                 자동 마크다운 저장 비활성화

참조 자료

references/workflow.md

다음을 포함한 상세 워크플로우 문서:

  • 예제가 포함된 완전한 스킬 워크플로우
  • 프롬프트 개선 전략
  • 연구 매개변수 설명
  • Claude를 위한 통합 가이드
  • 명령줄 인터페이스 참조
  • 오류 처리 및 문제 해결
  • 효과적인 연구를 위한 팁

주요 동작

스마트 프롬프트 개선

스킬은 개선이 필요한지 지능적으로 판단합니다:

  • 개선 트리거: 15단어 미만이거나 일반적인 시작으로 시작하는 프롬프트
  • 개선 건너뛰기: 상세하고 구체적인 프롬프트인 경우
  • 사용자 허용: --no-enhance 플래그로 비활성화 가능
  • 템플릿 인식: 기술 연구와 일반 연구에 대해 다른 질문 사용

연구 매개변수

개선된 프롬프트에는 다음이 포함됩니다:

  • 전체 컨텍스트가 포함된 원래 사용자 질의
  • 범위 및 기간 선호도
  • 원하는 깊이 수준 (요약, 기술적, 구현, 비교)
  • 특정 초점 영역 (성능, 비용, 보안 등)

이러한 매개변수는 심층 연구 모델이 보다 타겟팅되고 관련성 높은 결과를 제공하도록 돕습니다.

재현성

모든 연구 실행:

  • 사용된 정확한 프롬프트를 타임스탬프 파일에 저장
  • 연구 결정 추적 가능
  • 동일하거나 수정된 프롬프트를 사용한 후속 연구 허용
  • 연구 매개변수의 감사 추적 유지

예제

개선이 있는 간단한 프롬프트

사용자: "가장 효과적인 오픈소스 RAG 솔루션을 조사해줘"

스크립트 동작:

  1. 간단한 프롬프트(12단어) + 기술 키워드("오픈소스", "RAG") 감지
  2. 기술 연구 질문 제시:
    • 기술 범위: 오픈소스만? (사용자: 예)
    • 주요 지표: 성능/벤치마크? (사용자: 속도와 정확도)
    • 사용 사례: 프로덕션 배포? (사용자: 여러 측면)
  3. 매개변수를 포함한 상세 프롬프트로 개선
  4. 저장 후 심층 연구 실행
  5. 비교 벤치마크와 출처 URL이 포함된 포괄적인 보고서 반환

개선이 없는 상세 프롬프트

사용자: "2024-2025년에 대규모 언어 모델이 소프트웨어 개발자 생산성에 미치는 영향을 분석하되, 코드 생성 도구, 페어 프로그래밍 및 생산성 지표에 초점을 맞춰줘."

스크립트 동작:

  1. 상세한 프롬프트(24단어)와 구체적인 범위/초점 감지
  2. 개선 질문 건너뛰기
  3. 저장 후 즉시 심층 연구 실행
  4. 사용자 사양에 맞춰진 집중 분석 반환

요구 사항

  • Python 3.7+
  • OpenAI API 키 (OPENAI_API_KEY 환경 변수 또는 .env 파일로 설정)
  • 인터넷 연결 (웹 검색용)
  • 연구 완료를 위한 30분 이상 (설정 가능한 타임아웃)

토큰 효율적인 워크플로우

장기 실행 작업 최적화

심층 연구 쿼리는 일반적으로 10~20분이 소요됩니다. 이 스킬은 긴 대기 시간 동안 토큰 사용을 최소화하도록 최적화되었습니다:

작동 방식:

  1. 동기식 실행: 스크립트는 차단 서브프로세스로 실행됩니다 (백그라운드 폴링 없음)
  2. 중간 검사 없음: Claude는 상태 업데이트 없이 조용히 완료를 기다립니다
  3. 단일 출력: 결과는 끝에 한 번만 제공됩니다
  4. 자동 저장: 마크다운 파일이 자동으로 저장되며 수동 개입이 필요하지 않습니다

토큰 절약:

  • 기존 방식: 30초마다 상태 확인 = 약 40회 확인 × 500토큰 = 약 20,000토큰 낭비
  • 이 방식: 단일 대기 = 총 약 1,000토큰

자동 파일 관리

스킬은 자동으로 파일을 생성하고 저장합니다:

생성된 파일:

  • research_prompt_YYYYMMDD_HHMMSS.txt - 매개변수가 포함된 개선된 연구 프롬프트
  • research_report_YYYYMMDD_HHMMSS.md - 다음을 포함한 완전한 마크다운 보고서:
    • 연구 섹션 (역사적, 인지적, 문화적 등)
    • 번호가 매겨진 출처 인용
    • 메타데이터 바닥글 (날짜, 모델)

사용자 정의 옵션:

# 사용자 정의 출력 위치
python3 deep_research.py --prompt-file prompt.txt --output-file my_research.md

# 자동 저장 비활성화 (터미널 출력만)
python3 deep_research.py --prompt-file prompt.txt --no-save

문제 해결

OPENAI_API_KEY 누락

오류: "Missing OPENAI_API_KEY"

해결 방법:

  • 환경 변수 설정: export OPENAI_API_KEY="your-key"
  • 또는 작업 디렉토리에 .env 파일을 만들고 OPENAI_API_KEY=your-key 입력

deep_research.py를 찾을 수 없음

오류: "Could not find deep_research.py"

해결 방법:

  • 스킬이 assets와 함께 올바르게 설치되었는지 확인
  • 스크립트는 다음 위치에서 검색: 스킬 assets 폴더 → 현재 디렉토리 → 상위 디렉토리

연구 타임아웃

오류: 30분 후 요청 시간 초과

해결 방법:

  • 타임아웃 증가: --timeout 5400 (90분)
  • 연구 범위를 줄이기 위해 프롬프트 단순화
  • 잠재적으로 더 빠른 API 응답을 위해 비성수기에 실행

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

Build content-focused websites with Astro — zero JS by default, islands architecture, multi-framework components, and Markdown/MDX support.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

관련 스킬