# Research Workflow

> A Claude skill from GEUConn/research-idea-workflow-skill.

- **Type:** Skill
- **Install:** `agentstack add skill-geuconn-research-idea-workflow-skill-research-workflow`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [GEUConn](https://agentstack.voostack.com/s/geuconn)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [GEUConn](https://github.com/GEUConn)
- **Source:** https://github.com/GEUConn/research-idea-workflow-skill/tree/main/research-workflow

## Install

```sh
agentstack add skill-geuconn-research-idea-workflow-skill-research-workflow
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Research Idea Workflow Skill | 科研思路工作流技能

> **Claude Code Skill** · Materials Engineering Focus · Bilingual (EN/ZH)

---

## Overview | 概述

This skill guides materials engineering researchers through four structured stages — from a raw idea to a fully planned experiment — with human-in-the-loop confirmation at each critical checkpoint.

本技能引导材料工程科研人员完成从模糊想法到完整实验方案的四阶段结构化流程，在每个关键节点提供人工确认机会。

**Trigger / 触发方式:**
- Claude Code: invoke this skill file, then describe your research idea in natural language
- Codex CLI: see `AGENTS.md` in this directory

**Pipeline Overview / 流程概览:**
```
Stage 1: Topic Refinement       → [CHECKPOINT 1] → [TOKEN REPORT 1]
Stage 2: Urgency Assessment     → [CHECKPOINT W?] → [TOKEN REPORT W] → [CHECKPOINT 2] → [TOKEN REPORT 2]
Stage 3: Technical Route Eval   → [CHECKPOINT W?] → [TOKEN REPORT W] → [CHECKPOINT 3] → [TOKEN REPORT 3]
Stage 4: Experiment Planning    → Final outputs → [TOKEN REPORT 4] → [TOTAL SUMMARY]

Citation Verification runs continuously across Stages 2–3
WARN detected → [CHECKPOINT W] Human review of flagged references
```

---

## Token Tracking Protocol | Token 消耗追踪协议

**At every CHECKPOINT and after every stage, Claude MUST run the token tracker.**
**在每个确认节点和每个阶段结束后，Claude 必须运行 token 追踪器。**

### How to Estimate Tokens | 如何估算 Token 数

Claude should estimate tokens from the current stage's conversation:
Claude 应从当前阶段的对话内容估算 token 数：

```
Input tokens  ≈ sum of all USER messages in this stage ÷ 4 (English) or ÷ 2 (Chinese/mixed)
Output tokens ≈ sum of all ASSISTANT messages in this stage ÷ 4 (English) or ÷ 2 (Chinese/mixed)

For a mixed EN/ZH workflow, use ÷ 3 as a practical approximation.
中英混合工作流实践中可统一使用 ÷ 3 作为近似值。
```

### Token Report Command | Token 报告命令

```bash
python research-workflow/scripts/token_tracker.py \
  --log \
  --stage  \
  --input  \
  --output  \
  --model 

# Stage IDs: 0 (setup), 1, 2, 3, 4, W (citation checkpoint)
# Model names: claude-sonnet-4-6 | claude-opus-4-6 | claude-haiku-4-5 | gpt-4o | gpt-4.1
# Run --list-models to see all options and current pricing
```

### Supported Models & Pricing | 支持的模型与定价

```bash
python research-workflow/scripts/token_tracker.py --list-models
```

| Model | Input ($/MTok) | Output ($/MTok) |
|-------|---------------|----------------|
| claude-opus-4-6 | $15.00 | $75.00 |
| claude-sonnet-4-6 | $3.00 | $15.00 |
| claude-haiku-4-5 | $0.80 | $4.00 |
| gpt-4o | $2.50 | $10.00 |
| gpt-4.1 | $2.00 | $8.00 |

---

## Prerequisites & Setup | 前置条件与配置

### Step 0: Materials Project API Setup | Materials Project API 配置

**Before starting the workflow, always execute this setup protocol:**

1. Ask the user: *"Do you have a Materials Project API key? (Y/N)"*
   询问用户：*"你是否已有 Materials Project API key？(Y/N)"*

2. **If YES / 若有:**
   - Ask them to provide the key
   - Set environment variable: `export MP_API_KEY=""`
   - Verify with: `python research-workflow/scripts/search_materials_project.py --test`
   - If verification passes → proceed to Stage 1

3. **If NO / 若无:**
   - Display this registration guide:
     ```
     Materials Project (materialsproject.org) provides free API access.
     Materials Project 提供免费API访问权限。

     Steps / 步骤:
     1. Visit https://materialsproject.org/api
        访问 https://materialsproject.org/api
     2. Register/login with your institution email
        用机构邮箱注册或登录
     3. Go to Dashboard → API Keys → Generate new key
        进入 Dashboard → API Keys → 生成新密钥
     4. Copy your key and return here
        复制密钥后返回

     Your key will look like: "mpapikey_XXXXXXXXXXXXXXXX"
     ```
   - Wait for the user to complete registration
   - If user explicitly refuses / 若用户明确拒绝:
     - Inform: *"Proceeding without Materials Project. Structural property data will be sourced from Semantic Scholar + OpenAlex only. Coverage for computational materials data will be reduced."*
     - 告知: *"将在不使用 Materials Project 的情况下继续。结构性质数据将仅从 Semantic Scholar + OpenAlex 获取，计算材料学数据覆盖会降低。"*
     - Set `MP_ENABLED=false` and proceed

---

## STAGE 1: Topic Refinement | 阶段一：课题精炼

**Goal / 目标:** Transform a rough research idea into a well-scoped, specific research question.
将模糊的研究想法转化为范围明确、具体可操作的研究问题。

**Instructions for Claude / Claude执行指令:**

1. Ask the user to describe their research idea in free form.
   请用户自由描述其研究想法（无格式要求）。

2. Engage in up to 3 rounds of Socratic questioning to refine scope:
   通过最多3轮苏格拉底式追问来细化范围：
   - What material system / class is the focus?
     关注什么材料体系/类别？
   - What property or phenomenon needs to be understood/improved?
     需要理解/改善什么性质或现象？
   - What is the intended application or impact?
     目标应用场景或影响是什么？
   - What scale of study (atomic / mesoscale / macroscale)?
     研究尺度（原子尺度/介观/宏观）？

3. Generate a refined topic summary in the following format:
   生成精炼后的课题摘要，格式如下：

   ```markdown
   ## Refined Research Topic | 精炼课题

   **Title (EN):** [One-line title]
   **标题 (ZH):** [单行中文标题]

   **Core Question (EN):** [The central question this research answers]
   **核心问题 (ZH):** [本研究回答的核心问题]

   **Material System:** [e.g., Li₇La₃Zr₂O₁₂ (LLZO) solid electrolytes]
   **材料体系:** [例：Li₇La₃Zr₂O₁₂ (LLZO) 固态电解质]

   **Target Property / Phenomenon:** [e.g., ionic conductivity enhancement]
   **目标性质/现象:** [例：离子导电率提升]

   **Study Scale:** [Atomic / Mesoscale / Macroscale / Multi-scale]
   **研究尺度:** [原子尺度 / 介观尺度 / 宏观尺度 / 多尺度]

   **Intended Impact:** [Scientific contribution + potential application]
   **预期影响:** [科学贡献 + 潜在应用]
   ```

4. **[CHECKPOINT 1]** Present the refined topic and ask:
   **【确认节点 1】** 展示精炼结果并询问：
   > *"Does this accurately capture your research direction? Reply YES to proceed to urgency assessment, or provide corrections."*
   > *"这是否准确反映了你的研究方向？回复 YES 继续进行紧迫性评估，或提供修改意见。"*

   - If corrections provided → revise and re-present (max 2 iterations)
   - Only proceed to Stage 2 after explicit user confirmation

**Output / 输出:** Refined topic card (displayed in chat, not saved to file yet)
精炼后的课题卡片（在对话中展示，暂不保存文件）

**[TOKEN REPORT 1] — Run immediately after user confirms at Checkpoint 1:**
**【TOKEN 报告 1】— 用户在确认节点1确认后立即运行：**
```bash
python research-workflow/scripts/token_tracker.py \
  --log --stage 1 \
  --input  \
  --output  \
  --model claude-sonnet-4-6
# Replace model name to match the model actually in use
# 请将模型名称替换为实际使用的模型
```

---

## STAGE 2: Urgency & Landscape Assessment | 阶段二：研究紧迫性与领域态势评估

**Goal / 目标:** Quantify how urgent and timely this research direction is, and identify the research gap.
量化本研究方向的紧迫程度与时效性，识别研究空白。

**Instructions for Claude / Claude执行指令:**

### 2.1 Literature Search | 文献检索

Execute searches across all available APIs:

```python
# Run the following scripts in parallel:
python research-workflow/scripts/search_semantic_scholar.py --query "" --years 5
python research-workflow/scripts/search_openAlex.py --query "" --years 5
python research-workflow/scripts/search_materials_project.py --material ""  # if MP_ENABLED
```

Collect at minimum 30 papers from the past 5 years.
至少收集过去5年的30篇相关论文。

### 2.2 Citation Verification | 文献核查

For every paper collected, run the three-index triangulation:
对每篇论文，运行三重索引交叉核查：

```python
python research-workflow/scripts/citation_triangulation.py --papers papers_list.json
```

**Verification Rules / 核查规则:**

| Status | Condition | Action |
|--------|-----------|--------|
| ✅ VERIFIED | Found in ≥2 of: S2 / OpenAlex / Crossref, DOI resolves | Proceed normally |
| ⚠️ WARN | Found in only 1 index, DOI ambiguous, or abstract mismatch | Flag for human review → **[CHECKPOINT W]** |
| ❌ REJECT | Not found in any index, DOI does not resolve, title/author fabricated | Remove from list, do NOT use in report |

**[CHECKPOINT W] — Citation WARN Handler:**
**【确认节点 W】— 可疑文献处理：**
When ≥1 WARN citation detected, PAUSE and display:
当检测到≥1条 WARN 文献时，暂停并展示：

```
⚠️ Citation Review Required | 文献审查

The following references could not be fully verified:
以下参考文献无法完全核实：

[List each flagged paper with: Title | Source found in | Issue]

Options / 选项:
  A) Remove all flagged citations / 删除所有标记文献
  B) Keep with [UNVERIFIED] marker / 保留并标注 [未核实]
  C) Review each individually / 逐条审查

Please select A, B, or C:
```

**[TOKEN REPORT W] — Run after user responds at Checkpoint W:**
**【TOKEN 报告 W】— 用户在确认节点W回复后运行：**
```bash
python research-workflow/scripts/token_tracker.py \
  --log --stage W \
  --input  \
  --output  \
  --model claude-sonnet-4-6
```

### 2.3 Urgency Indicators | 紧迫性指标分析

Analyze and report on all four urgency dimensions:
分析并报告全部四个紧迫性维度：

**① Publication Trend (5-year) / 发文量趋势（5年）**
- Count papers per year for the topic
- Calculate year-over-year growth rate
- Classify: 🔥 Hot (>20% YoY growth) / 📈 Growing / 📊 Stable / 📉 Declining

**② Top Journal Acceptance Rate / 顶刊接收率**
- Check for recent publications in: Nature Materials, Nature Energy, Advanced Materials, ACS Nano, JACS, Acta Materialia, npj Computational Materials
- Flag if >3 papers in top journals in past 2 years → high field attention

**③ Research Gap Identification / 研究空白识别**
- Extract "future work", "open questions", "limitations" sections from top-cited papers
- Synthesize into a gap map
- Assess whether the refined topic directly addresses an identified gap

**④ Industry Adoption Signals / 工业界采用信号**
- Search for related patents (via OpenAlex patent filter)
- Note if major companies / national labs have published in this area
- Assess commercialization pressure

### 2.4 Stage 2 Report Generation | 生成阶段二报告

Generate from template `templates/stage2_urgency_report_template.md`:
- Chinese version: `output/stage2_urgency_report_zh.md`
- English version: `output/stage2_urgency_report_en.md`

**[CHECKPOINT 2]** Present summary and ask:
**【确认节点 2】** 展示摘要并询问：
> *"Based on the urgency assessment, do you wish to proceed to technical route evaluation? (YES/NO)"*
> *"根据紧迫性评估结果，你是否希望继续进行技术路线评估？(YES/NO)"*

- If NO → generate Stage 2 report only and exit gracefully
- If YES → proceed to Stage 3

**[TOKEN REPORT 2] — Run after user responds at Checkpoint 2:**
**【TOKEN 报告 2】— 用户在确认节点2回复后运行：**
```bash
python research-workflow/scripts/token_tracker.py \
  --log --stage 2 \
  --input  \
  --output  \
  --model claude-sonnet-4-6
```

---

## STAGE 3: Technical Route Evaluation | 阶段三：技术路线评估

**Goal / 目标:** Survey existing methods for solving the research problem, identify state-of-the-art, and recommend the most promising route.
调研现有解决方案，识别前沿方法，推荐最具潜力的技术路线。

**Instructions for Claude / Claude执行指令:**

### 3.1 Method Taxonomy for Materials Engineering | 材料工程方法分类框架

Evaluate the research problem against the following method categories:
针对以下方法类别评估研究问题：

**Category A — Computational Simulation | 计算模拟**
- First-principles DFT (VASP, Quantum ESPRESSO, CP2K)
- Classical / reactive MD (LAMMPS, GROMACS)
- ML interatomic potentials (MACE, CHGNet, M3GNet, NequIP)
- Phase-field modeling
- Assessment criteria: system size limits, accuracy vs. cost, availability of pseudopotentials for material system

**Category B — Experimental Synthesis & Characterization | 实验合成与表征**
- Synthesis routes (solid-state, sol-gel, hydrothermal, CVD, ALD, etc.)
- Structural characterization (XRD, ND, EXAFS)
- Microstructural analysis (SEM, TEM, STEM-EELS, APT)
- Property measurement (impedance spectroscopy, nanoindentation, XPS, etc.)
- Assessment criteria: required equipment, sample preparation complexity, throughput

**Category C — ML / Data-Driven Discovery | 机器学习/数据驱动材料发现**
- High-throughput screening (Materials Project + pymatgen workflows)
- Graph neural networks for property prediction (MEGNet, CGCNN, DimeNet++)
- Active learning / Bayesian optimization for composition design
- Large language models for literature mining
- Assessment criteria: training data availability, interpretability, generalizability

**Category D — Multi-scale Modeling | 多尺度建模**
- DFT → force field parameterization → MD → FEM
- CALPHAD thermodynamics integration
- Concurrent / hierarchical coupling strategies
- Assessment criteria: coupling fidelity, computational cost, software ecosystem

### 3.2 Comparative Analysis | 比较分析

For each applicable method category, assess:
对每个适用的方法类别评估：

| Criterion | Weight |
|-----------|--------|
| Alignment with research question | 30% |
| State-of-the-art performance in similar problems | 25% |
| Feasibility (resources, expertise, timeline) | 20% |
| Novelty / differentiation from existing work | 15% |
| Reproducibility / open-source availability | 10% |

### 3.3 Citation Verification (Stage 3) | 文献核查（阶段三）

Apply the same three-index triangulation to all method-supporting references.
对所有方法支撑性参考文献应用相同的三重索引交叉核查。
Trigger **[CHECKPOINT W]** for any WARN-flagged citations.

**[TOKEN REPORT W2] — If Checkpoint W fires during Stage 3, run after user response:**
**【TOKEN 报告 W2】— 若确认节点W在阶段三触发，用户回复后运行：**
```bash
python research-workflow/scripts/token_tracker.py \
  --log --stage W2 \
  --input  \
  --output  \
  --model claude-sonnet-4-6
```

### 3.4 Route Recommendation | 路线推荐

Synthesize into a ranked recommendation with rationale.
Minimum: rank top 2 routes with pros/cons and risk assessment.

Generate from template `templates/stage3_route_report_template.md`:
- `output/stage3_route_report_zh.md`
- `output/stage3_route_report_en.md`

**[CHECKPOINT 3]** Present recommendations and ask:
**【确认节点 3】** 展示推荐结果并询问：
> *"Based on the technical route evaluation, which route do you select? Please indicate your choice (e.g., 'Route A: ML potentials + MD' or specify modifications). This selection will be used to generate the experiment plan."*
> *"根据技术路线评估，你选择哪条路线？请说明选择（如'路线A：ML势函数+MD'或指定调整内容）。该选择将用于生成实验方案。"*

**[TOKEN REPORT 3] — Run after user selects route at Checkpoint 3:**
**【TOKEN 报告 3】— 用户在确认节点3选择路线后运行：**
```bash
python research-workflow/scripts/token_tracker.py \
  --log --stage 3 \
  --input  \
  --output  \
  --model claude-sonnet-4-6
```

---

## STAGE 4: Experiment Planning | 阶段四：实验方案规划

**Goal / 目标:** Generate a complete, actionable experiment plan based on the confirmed technical route.
基于已确认的技术路线，生成完整、可操作的实验方案。

**Instructions for Claude / Claude执行指令:**

### 4.1 Experiment Design Components | 实验设计要素

Generate a comprehensive plan covering all four dimensions:
生成涵盖全部四个维度的综合方案：

**① Gantt Chart Timeline | 甘特图时间线**
- Break work into phases: Literature review → Setup → Core experiments → Analysis → Writing
- Assign duration in weeks
- Mark dependencies between tasks
- Output as structured table for Excel rendering

**② Experimental Steps & Parameters | 实验步骤与参数**
For each core experiment:
- Detailed protocol (step-by-step)
- Key parameters and their ranges
- Required materials/software/equipment
- Safety considerations (if wet-lab)

**③ Control Groups & Variable Design | 对照组与变量设计**
- Independent variables (what you change)
- Dependent variables (what you measure)
- Control conditions (what you hold constant)
- Rationale for each experimental group

**④ Expected Results & Evaluation Metrics | 预期结果与评估指标**
- Quantitative success criteria for each experiment
- Benchmarks from literature (with verified citations)
- Contingency plans if results deviate from expectations

### 4.2 Output Generation | 输出生成

Generate all final outputs:

**Markdown Reports (× 2):**
```
output/
├── stage4_experiment_plan_zh.md   # Chinese
└── stage4_experiment_plan_en.md   # English
```

**Excel Experiment Plan (× 1):**
```
output/
└── experiment_plan.xlsx
    ├── Sheet 1: Gantt Chart (color-coded by phase)
    ├── Sheet 2: Experimental Steps & Parameters
    ├── Sheet 3: Variable Design & Control Groups
    └── Sheet 4: Expected Results & Metrics
```

**Final

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [GEUConn](https://github.com/GEUConn)
- **Source:** [GEUConn/research-idea-workflow-skill](https://github.com/GEUConn/research-idea-workflow-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-geuconn-research-idea-workflow-skill-research-workflow
- Seller: https://agentstack.voostack.com/s/geuconn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.