Agent skill

Research Query Builder

by fivetaku in fivetaku/gptaku-plugins-codex

Interviews you in stages, then turns a vague research idea into a structured JSON query, a readable brief and a checklist for a deep research run.

MITAuto-check passedResearch & Science

Install Research Query Builder

skills CLI
$ npx skills add fivetaku/gptaku-plugins-codex --skill insane-research-query -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install fivetaku/gptaku-plugins-codex insane-research-query --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/fivetaku/gptaku-plugins-codex.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/insane-research-codex/skills/insane-research-query .claude/skills/insane-research-query && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
insane-research-query
GitHub stars
128
Token cost
~1.4k tokens
SKILL.md length
443 words
Files
2 (incl. references)
Skills in repo
25
Repo updated
First seen
Licence
MIT

At a glance

Interviews you in stages, then turns a vague research idea into a structured JSON query, a readable brief and a checklist for a deep research run.

  • Works in 4 steps: Discovery (주제·타입) → Detailed Scoping (범위·소스 품질) → Query Generation (쿼리 생성) → …
  • Turning a vague research idea into a precise, scoped question
  • SKILL.md covers 질문 원칙…, Codex 워크플로우, 품질 검증 규칙 and 안티패턴, plus 4 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Run before a deep research task, this skill builds the query interactively instead of guessing. It starts by running the plugin's setup script silently, then asks multiple-choice questions in two phases: first the core topic, with an option to browse example queries, then detailed scoping. Labels are translated into your language, and trigger phrases exist in English and Korean.

From the answers it produces three things: a structured JSON query that follows the schema in references/query_schema.json, a human-readable research brief in Markdown, and an execution checklist for quality checks. A final question lets you start the research now by passing the JSON to the insane-research-main skill, save the query to a file, or go back and adjust it.

Validation rules apply before the query is finalized: the title should be specific, the objective measurable, the primary question answerable, exclusions present to stop scope creep, and the timeframe, geography and source requirements realistic.

When your agent uses it

  • Turning a vague research idea into a precise, scoped question
  • Preparing a query to hand to the insane-research deep research skill
  • Saving a reusable research query as a JSON file

Example prompts

  • “Help me build a research query about solid-state battery supply chains.”
  • “Use the research query builder to scope a study of remote work and productivity.”
  • “I need a structured query before I start deep research on EU data privacy rules.”

Requirements

  • The insane-research plugin, including its setup script and the insane-research-main skill

Workflow steps

4 steps, taken from the step headings in SKILL.md.

  1. Discovery (주제·타입)
  2. Detailed Scoping (범위·소스 품질)
  3. Query Generation (쿼리 생성)
  4. Confirmation and Handoff

What it can do on your machine

Read from SKILL.md and the folder at commit d3b47fc. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are json and markdown).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Research Query Builder loads about 1.4k tokens when it runs, and up to ~3.4k if it reads all its reference files. Until then it costs about 85 tokens; SKILL.md has 443 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~85
When it runs · the whole SKILL.md, loaded when a task matches
~1.4k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~3.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from fivetaku/gptaku-plugins-codex at commit d3b47fc, republished under its MIT licence (© fivetaku). 443 words, ~1,444 tokens.

Download SKILL.mdSave it as .claude/skills/insane-research-query/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
insane-research-query
description
Structured research-query builder that turns a vague topic into a research brief and machine-readable query before full insane-research starts. Use when the user wants help framing a research request. Korean triggers — "리서치 쿼리 만들어줘", "쿼리 빌더". English triggers — "research query builder", "structured research query".

Insane Research Query Builder for Codex

모호한 리서치 아이디어를 구조화된 실행 가능한 리서치 쿼리로 변환한다.

먼저 읽기:

  • $PLUGIN_ROOT/skills/insane-research-query/references/query_schema.json

이 스킬은 사용자가 모호한 아이디어를 본격 딥리서치 전에 리서치-레디 브리프로 다듬고 싶을 때 사용한다.

질문 원칙 (shared/questioning-policy.md §A·§1·§2c)

Codex CLI에는 객관식 카드 위젯 UI가 없다. shared/questioning-policy.md §A의 채팅 번호 블록으로 대체한다. 추론 가능한 건 묻지 말고(§1), 요청이 이미 구체적이면 과잉질문 없이 바로 브리프를 생성한다(§2c). 사용자 입력 언어에 맞춰 모든 질문/선택지/산출물 언어를 일치시킨다.

Codex 워크플로우

Phase 1: Discovery (주제·타입)

주제가 불명확할 때만 한 번, §A 번호 블록으로 가장 큰 미지수만 묻는다:

text
어떤 유형의 리서치인가요?
1. Exploratory — 무엇이 존재하는지 탐색, 지형 매핑
2. Comparative — 기술/접근/제품 비교
3. Analytical — 원인·효과·메커니즘 심층 분석
4. Predictive — 미래 트렌드·전망·예측
(번호 또는 문장으로 답해도 됩니다)

예시를 보고 싶다는 답이 나오면 다음에서 로드해 제시한다: $PLUGIN_ROOT/skills/insane-research-main/examples/

Phase 2: Detailed Scoping (범위·소스 품질)

핵심 주제를 잡은 뒤, 정말 모호한 제약만 §A 번호 블록으로 확인한다(추론 가능하면 기본값으로 진행):

text
지리적 범위는?
1. Global (추천) — 전 세계 관점
2. US/North America — 미국·북미 중심
3. Asia-Pacific — APAC 중심 (한국 포함)
4. Europe — 유럽 시장 중심
(문장으로 직접 지정해도 됩니다)
text
필요한 소스 품질은?
1. B - High quality (추천) — 학술 + 공식 문서 + 검증된 리포트
2. A - Academic only — 피어리뷰 논문·메타분석만
3. C - Moderate — 전문가 의견·사례 연구 포함
4. D - Broad coverage — 프리프린트·전문가 블로그까지 폭넓게
(모르면 1번으로 진행하겠습니다)
Phase 3: Query Generation (쿼리 생성)

모든 입력을 모은 뒤 생성한다:

  1. 구조화 JSON 쿼리 — 스키마 준수: $PLUGIN_ROOT/skills/insane-research-query/references/query_schema.json
  2. 사람이 읽는 리서치 브리프 — 마크다운
  3. 실행 체크리스트 — 품질 검증용
JSON 쿼리 구조
json
{
  "task": {
    "title": "[5-15 단어 간결한 제목]",
    "objective": "[명확한 리서치 목표 진술]",
    "type": "exploratory|comparative|analytical|predictive|evaluative"
  },
  "context": {
    "background": "[왜 이 리서치가 중요한가]",
    "audience": "technical|executive|academic|general|policy_maker",
    "use_case": "[리서치가 어떻게 쓰일지]",
    "prior_knowledge": ["가정 1", "가정 2"]
  },
  "questions": {
    "primary": "[메인 리서치 질문]",
    "secondary": ["서브 질문 1", "서브 질문 2", "서브 질문 3"],
    "hypotheses": ["검증 가능한 가정 1"],
    "exclusions": ["범위 밖 주제 1"]
  },
  "constraints": {
    "timeframe": {"start": "2024-01-01", "end": "present", "focus_period": "2025-2026"},
    "geography": {"scope": "global", "regions": [], "exclude_regions": []},
    "sources": {"required_types": ["peer_reviewed", "industry_reports"], "min_quality": "B", "language": ["en"]}
  },
  "output": {
    "format": "comprehensive_report",
    "length": {"min_words": 3000, "max_words": 10000},
    "structure": {"include_executive_summary": true, "include_bibliography": true, "generate_website": false},
    "citation_style": "APA",
    "tone": "professional"
  },
  "keywords": ["keyword1", "keyword2"],
  "special_instructions": []
}
사람이 읽는 브리프
markdown
# Research Brief: [Title]

## Objective
[명확한 진술]

## Research Questions
### Primary Question
> [메인 질문]

### Secondary Questions
1. [서브 질문 1]
2. [서브 질문 2]

## Scope & Constraints
| Dimension | Specification |
|-----------|--------------|
| Timeframe | [기간] |
| Geography | [범위] |
| Min Quality | Grade [X] |

## Execution Checklist
- [ ] Primary question fully answered
- [ ] All secondary questions addressed
- [ ] Sources meet quality threshold
- [ ] Citations properly formatted
Phase 4: Confirmation and Handoff

브리프를 보여준 뒤 §A 번호 블록으로 다음 행동을 확인한다:

text
쿼리가 괜찮으면 바로 리서치를 시작할까요?
1. 지금 리서치 시작 (추천) — 이 쿼리로 즉시 딥리서치 실행
2. 쿼리만 저장 — JSON 쿼리를 파일로 저장해 두기
3. 쿼리 수정 — 일부 파라미터를 바꾼 뒤 진행
(번호 또는 문장으로 답해도 됩니다)
  • 1 지금 시작 → JSON 쿼리를 insane-research-main 스킬에 넘긴다
  • 2 저장만 → JSON을 파일로 작성 (RESEARCH/queries/{topic}_{timestamp}.json)
  • 3 수정 → 조정 사항을 모아 루프백

품질 검증 규칙

쿼리 확정 전 검증:

Task
  • 제목이 구체적 (generic한 "AI Research" 금지)
  • 목표가 측정/검증 가능
  • type이 리서치 접근과 일치
Questions
  • primary가 답변 가능 (너무 광범위하지 않음)
  • secondary가 primary를 지지 (탈선 아님)
  • exclusions가 scope creep 방지
Constraints
  • timeframe이 주제에 현실적
  • geography가 주제 관련성과 일치
  • 소스 요건이 달성 가능
Output
  • 길이가 요청 깊이와 일치
  • 포맷이 독자에 적합

안티패턴

생성 금지
  • 과도하게 광범위한 질문 ("What is AI?")
  • 무한 timeframe ("all history")
  • 충돌하는 제약 / generic 키워드 ("technology", "innovation")
  • 측정 불가 목표 ("understand everything about...")
Show full SKILL.md (175 more words)Show less
생성 권장
  • 구체적·답변 가능한 질문 ("미국 병원의 AI 진단도구 현재 도입률은?")
  • 현실적 범위 경계 (빠른 분야는 2~3년 timeframe)
  • 구체적 성공 기준 ("시장 점유율 상위 10개 도구 식별")
  • 실행 가능한 검색어 ("AI radiology FDA approved 2024 2025 adoption rate")
  • 명확한 exclusions ("소비자 헬스 앱·행정 AI 제외")

언어 적응

모든 질문/선택지/산출물은 사용자 감지 언어에 맞춘다.

한국어 입력 처리

사용자가 한국어로 입력하면 (예: "헬스케어 AI 리서치 쿼리 만들어줘"):

  • 모든 질문 한국어
  • geography 옵션에 한국 관련 선택지
  • source 옵션에 한국 리서치 DB
  • 산출물에 한국어 인용 관례
다국어 키워드

최대 커버리지를 위해 사용자 언어와 영어 양쪽으로 검색 키워드 생성:

한국어 입력: "AI 의료 진단"
생성: ["AI 의료 진단 2026", "AI medical diagnostics 2026", "의료 AI 도입 현황", "clinical AI adoption"]

insane-research 연동

생성된 쿼리는 insane-research-main 스킬로 직접 들어간다:

  1. 쿼리 빌더가 구조화 JSON 출력
  2. 사용자가 confirm 또는 조정
  3. "지금 시작" 선택 시 JSON을 insane-research-main에 전달
  4. 요건이 이미 정의됐으므로 Phase 1(Question Scoping) 건너뜀
  5. 리서치는 Phase 2(Retrieval Planning)부터 시작

쿼리 저장 위치: RESEARCH/queries/{topic}_{timestamp}.json

Guardrails

  • 질문은 §A 번호 블록으로 compact하게, 추론 가능한 건 묻지 않는다.
  • 빈칸으로 두지 말고 구체적 기본값을 채운다.
  • query schema를 구조화 출력의 계약으로 취급한다.
  • 위젯형 프롬프트에 의존하지 말고 채팅으로 묻는다.

References

  • Query schema: $PLUGIN_ROOT/skills/insane-research-query/references/query_schema.json
  • Example queries: $PLUGIN_ROOT/skills/insane-research-main/examples/

© fivetaku, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (references) in plugins/insane-research-codex/skills/insane-research-query of fivetaku/gptaku-plugins-codex.

  • SKILL.md
  • references/query_schema.json

Open the folder on GitHubat commit d3b47fc

Compare with similar skills

Research Query Builder next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Research Query Builder compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Research Query Builder this skillfivetaku/gptaku-plugins-codex128—~1.4kAutomated safety check: PassMIT
Deep Researchglebis/claude-skills390—~2.6kAutomated safety check: NotesMIT
Deep Researchopen-octo/octo-agent125—~1.5kAutomated safety check: PassMIT
Product Managerstaruhub/ClaudeSkills727—~2.1kAutomated safety check: PassMIT
GitHub Deep Researchbytedance/deer-flow84k4 repos~1.3kAutomated safety check: PassMIT
Deep Research WorkflowTokenRhythm/opensquilla7.1k—~1.3kAutomated safety check: PassApache-2.0

Similar skills

  • Deep Research

    glebis/claude-skills

    This skill should be used when conducting comprehensive research on any topic using the OpenAI Deep Research API.

    390 GitHub stars~2.6k tokensUpdated yesterday
    Research & ScienceAuto-check: notes
  • Deep Research

    open-octo/octo-agent

    Deep, multi-source, fact-checked research on a topic — fan out searches, read primary sources, adversarially verify each claim, and synthesize a cited report.

    125 GitHub stars~1.5k tokensUpdated today
    Research & ScienceAuto-check passed
  • Product Manager

    staruhub/ClaudeSkills

    资深产品经理助手,提供 PRD/MRD/BRD 创作与评审、产品策略、留存增长、竞品分析、功能优先级,以及 grill-me-to-doc 逐轮访谈。用户要求“逐个问我”“先把需求问清楚”“grill me”“把想法变成产品文档”时进入 grill-me-to-doc:先读仓库证据,每轮只问一个决策,给推荐答案与理由,记录决策和未决项,支持 resume,产出结构化…

    727 GitHub stars~2.1k tokensUpdated 1 mo ago
    Agent WorkflowsAuto-check passed
  • GitHub Deep Research

    bytedance/deer-flow

    Researches a GitHub repository over four rounds using the GitHub API and web search, then writes a structured markdown report with timeline, metrics and Mermaid diagrams.

    84k GitHub starsUsed in 4 repos~1.3k tokens
    Research & ScienceAuto-check passed
  • Deep Research Workflow

    TokenRhythm/opensquilla

    Runs multi-round research in three stages with a persisted state file, evidence tracking and a long-form report with per-claim citations.

    7.1k GitHub stars~1.3k tokensUpdated today
    Research & ScienceAuto-check passed
  • Deep Research

    sanjay3290/ai-skills

    Execute autonomous multi-step research using Google Gemini Deep Research Agent.

    431 GitHub starsUsed in 9 repos~683 tokens
    Research & ScienceAuto-check: notes

More from fivetaku/gptaku-plugins-codex

All 25 skills in this repo
  • Pumasi Image

    fivetaku/gptaku-plugins-codex

    Image-generation companion skill for the pumasi plugin family.

    128 GitHub stars~3.6k tokensUpdated 1 mo ago
    Auto-check passed
  • Insane Research Pipeline

    fivetaku/gptaku-plugins-codex

    Runs a multi-agent deep research workflow in seven phases, from scoping questions to a final report with source triangulation, state tracking and quality ratings.

    128 GitHub stars~7.1k tokensUpdated 1 mo ago
    Auto-check passed
  • Skillers Suda

    fivetaku/gptaku-plugins-codex

    This skill should be used when the user asks to "스킬 만들어줘", "에이전트 만들어줘", "커맨드 만들어줘", "스킬러들의 수다", "수다", "Codex 스킬 만들어줘", "이 스킬 분석해줘", "이 스킬 개선해줘", "skill builder", "make a skill", "create a skill"…

    128 GitHub stars~6k tokensUpdated 1 mo ago
    Auto-check passed
  • Dd

    fivetaku/gptaku-plugins-codex

    A skill your agent uses when the user runs /dd or /ㅇㅇ (Hangul IME alias — typing "dd" in Korean IME produces "ㅇㅇ") to act on the current OS clipboard (text or image) without pasting it into chat.

    128 GitHub stars~2k tokensUpdated 1 mo ago
    Auto-check passed
  • Insane Search

    fivetaku/gptaku-plugins-codex

    Adaptive access for blocked websites — tries every method until one works.

    128 GitHub stars~5.6k tokensUpdated 1 mo ago
    Auto-check passed
  • Docs Guide

    fivetaku/gptaku-plugins-codex

    Fetch and explain official documentation for any library, framework, API, or service using an llms.txt-first strategy — triggers on "How do I…", "What is…", "How does X work", "Best practice for…"…

    128 GitHub stars~3.5k tokensUpdated 1 mo ago
    Auto-check passed

Questions about Research Query Builder

What does Research Query Builder do?

Interviews you in stages, then turns a vague research idea into a structured JSON query, a readable brief and a checklist for a deep research run. Run before a deep research task, this skill builds the query interactively instead of guessing. It starts by running the plugin's setup script silently, then asks multiple-choice questions in two phases: first the core topic, with an option to browse example queries, then detailed scoping.

When should I use Research Query Builder?

Research Query Builder fits situations like: turning a vague research idea into a precise, scoped question; preparing a query to hand to the insane-research deep research skill; saving a reusable research query as a JSON file.

How do I install Research Query Builder in Claude Code?

Run `npx skills add fivetaku/gptaku-plugins-codex --skill insane-research-query -a claude-code`. Or copy the skill folder (plugins/insane-research-codex/skills/insane-research-query in fivetaku/gptaku-plugins-codex) into .claude/skills/insane-research-query in your project. Claude Code loads it when a task matches its description.

How do I install Research Query Builder in Codex?

Run `npx skills add fivetaku/gptaku-plugins-codex --skill insane-research-query -a codex`. Or copy the skill folder (plugins/insane-research-codex/skills/insane-research-query in fivetaku/gptaku-plugins-codex) into .agents/skills/insane-research-query in your project. Codex loads it when a task matches its description.

Can I use Research Query Builder in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add fivetaku/gptaku-plugins-codex --skill insane-research-query -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/insane-research-query, .gemini/skills/insane-research-query, .github/skills/insane-research-query and .opencode/skills/insane-research-query in your project.

What does Research Query Builder need to run?

SKILL.md names no scripts, command-line tools or credentials: Research Query Builder is instructions for the agent only. Our summary lists: The insane-research plugin, including its setup script and the insane-research-main skill.

Does Research Query Builder access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Research Query Builder safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Research Query Builder use?

Research Query Builder is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Research Query Builder use?

About 1.4k tokens (SKILL.md is roughly 5.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 1.9k tokens, read only when the agent opens those files.

What are the alternatives to Research Query Builder?

Skills that share tags, products or a category with Research Query Builder: Deep Research (glebis/claude-skills, 390 stars), Deep Research (open-octo/octo-agent, 125 stars), Product Manager (staruhub/ClaudeSkills, 727 stars) and GitHub Deep Research (bytedance/deer-flow, 84k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Research Query Builder?

fivetaku (a GitHub user) maintains it in fivetaku/gptaku-plugins-codex, which has 128 GitHub stars. The repository holds 25 skills in this directory. The repository was last updated on September 8, 2026.

Source: fivetaku/gptaku-plugins-codex on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.