# shidi ยท ๅธˆๅผŸ โ€” Your Junior Lab Mate in an Agent Skill ๐Ÿง‘โ€๐Ÿ”ฌ *Research workflow skill for AI coding agents: literature review ยท experiment design ยท scientific figures ยท paper reading ยท data organization* ### *You bring the ideas, shidi does the legwork.* [![License](https://img.shields.io/badge/license-MIT-2ea44f)](LICENSE) [![Version](https://img.shields.io/badge/version-0.4.1-blue)](https://github.com/IcyCreamDAS/shidi-skill/releases) [![GitHub stars](https://img.shields.io/github/stars/IcyCreamDAS/shidi-skill.svg?style=social)](https://github.com/IcyCreamDAS/shidi-skill/stargazers) [![Agent](https://img.shields.io/badge/agent-Claude%20Code%20%7C%20Codex%20%7C%20OpenClaw-111827)](README.md) [![Zero-Dep](https://img.shields.io/badge/dependencies-zero-ff69b4)](README.md) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/IcyCreamDAS/shidi-skill/pulls) [ไธญๆ–‡](./README.md) | English **Start with an interest, identify gaps in cross-field evidence, and form a testable research question.** Shidi organizes search, source retrieval, candidate comparison and validation plans into reusable files. > shidi (*"junior lab mate"* in Chinese) is a complete research workflow that lives inside your AI IDE โ€” not a prompt template. Hand it an idea (literature research / experiment design / figures / paper reading / data chores), and it returns **real deliverable files**. Deliverables are saved in your working directory. No platform or model lock-in. > > It's not fire-and-forget, either โ€” shidi is meant to be bossed around while you do something else. Say "shidi, help me with โ€ฆ", and it asks when it must, runs the rest, and hands you the files. > **Built for AI for Science workflows, grad students and researchers using agentic AI** โ€” literature review, experiment design, figures and paper reading become deliverable, cross-verifiable files instead of chat answers.

What's New ยท Deliverables ยท Why shidi ยท Quick Start ยท Demo ยท Guardrails ยท AI4S

--- ## ๐Ÿ‘€ Demo > Screenshots below are **illustrative** (content redacted) โ€” real runs produce fresh files for your own topic.

Final report structure Cross-verification brief structure

--- ## โœจ What's New - **2026-10-28: v0.4.1 file delivery fixes** โ€” preserve the previous PDF until a fresh export succeeds, reject duplicate paper IDs, and keep separate PDF input paths with hash-checked caches. Pro/Flash helpers are updated together; historical competition snapshots stay frozen. - **2026-10-27: Pro / Flash modes** โ€” One installation includes both workflows. Pro is the default; request โ€œquick researchโ€ or โ€œflash modeโ€ for Flash. Released to the default `main` branch through a pull request. - **2026-10** โ€” ๐Ÿ›ก **Release self-check loop**: GitHub Actions CI + `validate.py` (version, links, script compilation, required files) + offline `tests/` ยท published `verify_refs.py` (DOI resolution, retraction detection, style lint) ยท fixed the `render_report.py` timeout bug and added cross-platform browser discovery ยท `fetch_pdfs.py` no longer hardcodes an email and now backs off on 429/5xx - **2026-10** โ€” ๐Ÿ”ฌ **Deterministic scoring + data schema + AI4S demo upgrade**: `score_papers.py` seven-dim scoring (caps, veto and ranking computed by script; v2 lowers journal/network weight) ยท literature โ†’ formulation/property extraction schema (test standard, conditions, n, error, three claim labels) ยท demo upgrade (mass closure, ARD length scales, ECI acquisition, 1-2 benchmark-run calibration, Pareto front, literature-prior bounds) - **2026-08** โ€” ๐Ÿ“ฅ Batch PDF download (OpenAlex/Unpaywall OA lookup; failures classified and reported, never silently skipped) - **2026-08** โ€” ๐Ÿ“„ Multi-format reports (Markdown โ†’ HTML โ†’ PDF via headless Edge printing, zero deps) - **2026-08** โ€” ๐Ÿ” PDF extraction layer (text-based โ†’ Markdown to save context; scans auto-tagged `needs_vision` for the vision route) - **2026-08** โ€” ๐Ÿ—‚ Per-angle intermediate reports (parallel multi-agent research: one file per angle, merge by reading files only โ€” main context never overflows) ## ๐Ÿ“ค Deliverables Every job ends in **real files** โ€” not chat text.
๐Ÿ“„ Final Report๏ผˆ`~/shidi-output/`๏ผ‰
Markdown / Word ยท full report or experiment plan 
shidi_<topic>_v3_20260814.md
โ”œโ”€โ”€ 1. Background & chosen approach
โ”œโ”€โ”€ 2. Principle (literature-anchored)
โ”œโ”€โ”€ 3. Steps & details
โ”œโ”€โ”€ 4. Precautions
โ”œโ”€โ”€ 5. Flaw list (unvarnished)
โ”œโ”€โ”€ 6. Literature summary (by angle)
โ”œโ”€โ”€ 7. References (reading depth โœ…/โš /โŒ)
โ””โ”€โ”€ 8. Changelog (v1โ†’v2โ†’v3)
 โœ… Cross-Verification Brief๏ผˆ`~/shidi-verify/`๏ผ‰
A task sheet for another LLM โ€” also your self-check list 
shidi-verify_<topic>_v3_20260814.md
โ”œโ”€โ”€ 1. Task description
โ”œโ”€โ”€ 2. Original question (verbatim)
โ”œโ”€โ”€ 3. Full output (with reading depth)
โ”œโ”€โ”€ 4. Verification checklist
โ””โ”€โ”€ 5. Required output format
> Every delivery looks like this. Take the brief to **another LLM** for independent verification โ€” every comment gets an adopt/reject + reason, loop until you're satisfied. ## โœจ Why shidi | Chatting with a raw model | shidi | |:--|:--| | Answers live in the chat log | Delivers **files**: reports, briefs, figures, CSVs โ€” archivable, citable, shareable | | You nudge it step by step | Built-in workflow (search โ†’ score โ†’ read โ†’ report โ†’ verify); answer 3 parameters and it runs | | Hallucinations on your conscience | Seven-dim scoring (computed by script), DOI/retraction verification, DOI triple-dedup, no-fabrication rule, honest reading-depth labels, mandatory verification brief | | Behavior changes with the model | Pure SKILL.md + Markdown โ€” works in Claude Code / Codex / OpenClaw / any SKILL.md agent | ## ๐Ÿš€ Capabilities | Capability | Description | |:--|:--| | ๐Ÿ“š **Literature research** | 3 parameters up front โ†’ 3ร—3=9 angles โ†’ top-journal targeted search + fallback chain โ†’ seven-dim scoring (v2, script-checked) โ†’ graded reading โ†’ batch PDF download โ†’ file report | | ๐Ÿงช **Experiment design** | Free-form approach brainstorm โ†’ literature-backed โ†’ principle / steps / precautions / **unvarnished flaw list** | | ๐Ÿ“ˆ **Figures** | CSV/TXT/Excel โ†’ clean โ†’ compute (numpy/scipy/sympy) โ†’ publication-grade rendering, with Origin-ready data export | | ๐Ÿ”ฌ **Paper reading** | source-map six-step deep read โ†’ 16-section paper cards โ†’ glossary | | ๐Ÿ”„ **Cross-verification (the soul)** | Always emits a verification brief โ†’ another LLM checks independently โ†’ iterate in loops | | ๐Ÿ“‹ **Lab notes** | Standardized experiment/batch IDs, YAML frontmatter archiving | ## ๐Ÿงช AI4S Evidence [`examples/materials_small_data/`](examples/materials_small_data/) is a **synthetic-only**, small-data formulation โ†’ property demo that shows the claim discipline shidi uses for AI4S data work: - **Grouped validation** (leave-one-project-out) โ€” sibling samples from the same project never leak into training, so scores stay honest - **GP predictions with uncertainty** โ€” empirical coverage of ยฑ1ฯƒ / ยฑ2ฯƒ on held-out projects, compared with the 68% / 95% targets - **Batch calibration test** โ€” zero-shot vs adding 1โ€“2 benchmark runs from the new project; coverage barely moves, and the negative result is reported instead of hidden - **ARD feature relevance** โ€” per-feature GP length scales (smaller = more influential; at the upper bound = the data cannot identify a dependence) - **Constrained search with ECI** โ€” `ECI = EI ร— P(MFR โ‰ฅ 28)` instead of a hard feasibility cutoff, plus a feasibility-only shortlist - **Multi-objective Pareto front** โ€” tensile strength vs MFR posterior means - **Mass-fraction closure** โ€” filler + additive_a + additive_b + matrix = 100 wt%; candidates keep `matrix โ‰ฅ 40 wt%` - **Literature-prior interface** โ€” `priors_template.csv` feeds survey bounds into the search space (bounds only, no prior mean) - **Separated evidence labels** โ€” `measured` / `predicted` / `exploratory`; only `measured` may be reported as a result - **Hard rule: an exploration screening range is NOT a statistical confidence interval** ```bash cd examples/materials_small_data pip install -r requirements.txt && python run_demo.py python run_demo.py --priors priors_template.csv # constrain the search space with survey bounds ``` **What it does not claim:** the data is synthetic, so it predicts no property of any real material; the GP scores do not transfer to any real formulation dataset; the shortlist is not proven better than an experienced engineer's DOE intuition; independent single-output GPs ignore output correlation (tensile โ†” flexural โ‰ˆ 0.9); 1โ€“2 benchmark runs do not calibrate a batch offset (that needs a mixed-effects GP). Real industrial formulations stay under NDA โ€” what is published here is the **method**, not data. ## ๐Ÿงญ Flow ```mermaid flowchart TD A["Decide topics"] --> B["Research"] B --> C["3 parameters
{count, domain, requirements}"] C --> D["Search (T1โ†’T2โ†’T3)"] D --> H["Merge & score"] H --> E["Read (โœ…/โš /โŒ)"] E -->|out| F["Lit summary โ‘ "] E -->|out| G["References โ‘กโ‘ข
PDF or DOI+GB/T 7714"] F --> I{"More full-texts?"} G --> I I -->|yes| J["User uploads PDF"] J -->|supplement| H I -->|no| K["Final report"] I -->|no| L["Verify brief (always)"] K --> M{"Cross-verify?"} L --> M M -->|yes| N["Another LLM checks"] N -->|revise| D M -->|no| O["Done โœ“"] ``` ## ๐Ÿš€ Quick Start ```bash git clone https://github.com/IcyCreamDAS/shidi-skill.git mkdir -p ~/.claude/skills cp -r shidi-skill/skills/shidi ~/.claude/skills/ ``` Then just say: ```text ๅธˆๅผŸ๏ผŒๅธฎๆˆ‘่ฏฆ็ป†่ฐƒ็ ”ไธ€ไธ‹ XXX # Pro ๅธˆๅผŸ๏ผŒ่ฏทไฝ ็”จ pro ๆจกๅผ็ป™ๆˆ‘่ฐƒ็ ”ไธ€ไธ‹ XXX # Pro ๅธˆๅผŸ๏ผŒๅธฎๆˆ‘ๅฟซ้€Ÿ่ฐƒ็ ”ไธ€ไธ‹ XXX # Flash ๅธˆๅผŸ๏ผŒ่ฏทไฝ ็”จ flash ๆจกๅผ็ป™ๆˆ‘่ฐƒ็ ”ไธ€ไธ‹ XXX # Flash ``` **One download includes the complete Pro and Flash modes.** If the request does not specify โ€œ่ฏฆ็ป†โ€, โ€œๅฟซ้€Ÿโ€, โ€œproโ€, or โ€œflashโ€, it defaults to **Pro**: structured searching, interactive clarification, and deep deliverables. Flash minimizes confirmation and starts quickly. Modes change the workflow and use the models supported by the host. Other examples: ```text shidi, design an experiment for XX shidi, plot this data shidi, read this paper in depth for me ``` Just "shidi" works too โ€” it confirms the task type before starting. Compatible with any agent that follows the SKILL.md spec (Claude Code / Codex / OpenClaw / OpenCodeโ€ฆ). > [!IMPORTANT] > ### An executor, not a genie > `harness + model = agent` โ€” shidi owns the workflow, the model sets the ceiling. Pro returns angle selection and parameter confirmation to you; Flash proposes defaults and reduces formal confirmation. It takes the grunt work; the ideas and judgment stay yours. ## ๐Ÿค– Persona - Calls you "senior" (or "senior sister" if you say so) - A humble, slightly cheeky junior: *"here's what I made, what do you think?"* - Praises you when corrected ("good catch, senior"), never bends on science - Persona activates only on the trigger word โ€” other conversations unaffected *Yes, it asks a lot of questions โ€” that's how you know it's really shidi.* ## โš™๏ธ Dependencies - **Zero core deps**: pure SKILL.md + Markdown, nothing to install - Report rendering: `markdown` (HTML/PDF), plus a local Edge / Chrome / Chromium for PDF (auto-discovered cross-platform; override with `SHIDI_BROWSER`) - Optional: numpy/scipy/matplotlib/pandas/sympy (figures; pyvista for 3D), pdf-inspector (PDF extraction layer) - Scoring / citation scripts (`score_papers.py`, `verify_refs.py`): stdlib only - Search fallback chain: WebSearch โ†’ open scholarly APIs (OpenAlex/Crossref/arXiv, no keys needed); the Unpaywall fallback in PDF download needs `UNPAYWALL_EMAIL` ## ๐Ÿ›ก Guardrails 1. Capped seven-dim scoring; totals and ranking computed by `score_papers.py`, never by the model 2. Topic-match <10 โ†’ veto 3. DOI / arXiv ID / URL triple dedup 4. **No fabrication** โ€” unverifiable claims are labeled "unverified"; every report passes `verify_refs.py` (DOI resolution / retractions / style) before rendering 5. Honest reading-depth labels: full text โœ… / abstract โš  / unavailable โŒ 6. Every verification comment gets adopt/reject + reason โ€” never blind agreement ## ๐Ÿ“œ Credits Design ideas borrowed from [nature-skills](https://github.com/Yuan1z0825/nature-skills) (Yuan1z0825 team): routing, scoring dimensions (v1 six-dim โ†’ v2 seven-dim), search fallback chain, paper cards. ## ๐Ÿ“„ License [MIT License](LICENSE) โ€” free to use; just buy shidi a bubble tea ๐Ÿง‹ [ๅ…ฌๅผ€่ต„ๆบไธŽๅŽ†ๅฒ่Œƒๅ›ด / Public resources and historical scope](PRIVACY.md)