# ai4s-agent

Adopt this skill: https://proskills.md/skills/other/ai4s-research-ai4s-skills-skills-ai4s-agent

Page: https://proskills.md/skills/other/ai4s-research-ai4s-skills-skills-ai4s-agent
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/ai4s-agent/SKILL.md
size: 6482
sha: 7ea21360feee06bbe359fd8b44c6e0e9a70f9f1c
upstream: https://github.com/ai4s-research/ai4s-skills/blob/main/skills/ai4s-agent/SKILL.md

````text
---
name: ai4s-agent
description: Use when the user wants an end-to-end AI4S research pipeline — broad direction or specific topic in, full research package out (exploration + literature survey + experiment + paper). Meta-skill that chains the four downstream skills in order. Pure markdown, no Python runtime.
---

# AI4S Agent (meta-skill)

## Overview

Top-level entry point for the AI4S research stack. This skill contains **no work of its own** — its only job is to call four downstream skills in the right order, with the right slug, and reuse intermediate artifacts by path convention.

```
direction → research-explorer → topic
topic     → literature-survey  (60+ real bib, 100+ recommended)
topic     → experiment-suite   (design + code + results + figures)
topic     → paper-writer       (assembles into 200+ cite PDF)
```

Each downstream skill is **already single-stage and self-sufficient**: its agent loads that skill's `SKILL.md` and produces the full final-quality artifact directly. There is no skeleton/enrichment split. This meta-skill only handles ordering, the path convention, and disclosure consistency.

## When to use

- User asks for "a paper on X" or "research package on X" and wants the whole stack run end to end.
- User wants to compare what each skill produces — useful for developing or debugging the pipeline itself.

## When NOT to use

- User wants to run only one stage (e.g. only the literature survey) → invoke that skill directly.
- User wants only topic exploration → invoke `research-explorer` directly.

## The slug contract

Every skill computes the same slug from the same topic string:

```python
import re, hashlib
def slug(t):
    n = re.sub(r'[\s_]+', '-', re.sub(r'[^\w\s-]', '', t.lower().strip())).strip('-')[:40].rstrip('-')
    h = hashlib.sha1(t.encode()).hexdigest()[:8]
    return f"{n}-{h}"
```

Use the **same string** across all four skills. If the user provides a direction (not a topic), `research-explorer` runs against the direction; once a topic is chosen, the topic becomes the slug input for the remaining three.

## Workflow

### Step 1 — Understand the user's starting point

- **Direction** ("transformer time series forecasting") — start at `research-explorer`, pick a topic from its `research_exploration.md`, then proceed.
- **Topic** ("Transformer-based long-horizon forecasting with patch tokenisation") — skip `research-explorer`; go straight to the parallel branch (literature-survey, experiment-suite, paper-writer).
- **Real measured experiment data?** If yes, the user supplies a `results.json` path; experiment-suite loads it instead of writing a simulated one, and the paper's `\thanks` drops the simulated clause.

### Step 2 — Explore (only if input was a direction)

Load the `research-explorer` skill. Follow its 5 steps to produce:

```
output/research-explorer/<dir_slug>/latest/{research_exploration.md, topic_matrix.md, literature_pre_survey.md}
```

Discuss the candidate topics with the user. They pick one specific topic; that string becomes `$TOPIC` for the rest.

### Step 3 — Literature survey

Load the `literature-survey` skill with `$TOPIC`. It produces:

```
output/literature-survey/<topic_slug>/latest/survey_paper/
├── main.pdf                    # the 6–20 page survey
├── main.tex
├── bibliography.bib            # 60+ real entries, 100+ recommended (URL-anchored)
├── sections/, figures/
output/literature-survey/<topic_slug>/latest/literature_table.md
```

The survey bibliography must pass the temporal profile selected by
`literature-survey`; AI4S defaults to at least 60% from the current calendar
year and previous two years.

### Step 4 — Experiment package

Load the `experiment-suite` skill with `$TOPIC`. It produces:

```
output/experiment-suite/<topic_slug>/latest/
├── experiment_design.md
├── experiment/                  # runnable model.py / data.py / train.py / evaluate.py
├── results.json                 # with "simulated" + "provenance"
├── figures/                     # publication-grade + manifest.json (basenames only)
└── experiment_report.md
```

If a real results path was provided in Step 1, the agent loads it here and `results.json` is flagged `"simulated": false`.

### Step 5 — Paper

Load the `paper-writer` skill with `$TOPIC`. Its cross-skill conventions automatically pick up Steps 3 and 4:

- Seeds `bibliography.bib` from `output/literature-survey/<topic_slug>/latest/survey_paper/bibliography.bib`, then expands it to 200+ inside paper-writer if needed.
- Re-runs the paper-writer freshness gate after expansion; adding older
  foundational references must not silently make a fast-moving bibliography
  stale.
- Reads numbers and provenance from `output/experiment-suite/<topic_slug>/latest/results.json`.
- Copies/symlinks the publication-grade figures from `output/experiment-suite/<topic_slug>/latest/figures/`.

It produces:

```
output/paper-writer/<topic_slug>/latest/paper/
├── main.pdf                    # 8–14 pages, 200+ cites
├── main.tex
├── bibliography.bib
├── sections/, figures/
```

### Step 6 — Deliver

Report the four output roots to the user:

1. `output/research-explorer/<dir_slug>/latest/` (if exploration ran)
2. `output/literature-survey/<topic_slug>/latest/`
3. `output/experiment-suite/<topic_slug>/latest/`
4. `output/paper-writer/<topic_slug>/latest/`

Plus the paper-writer stats per its `references/05-quality-gate.md` report format.

## Disclosure consistency

The same `simulated` flag must drive disclosure across all four artifacts:

- `experiment-suite/.../results.json` → `"simulated": true|false` is the source of truth.
- `experiment-suite/.../experiment_report.md` top-of-page disclosure must match.
- `paper-writer/.../main.tex` `\author{AI4S Agent\thanks{…}}` must include the simulated clause iff `results.json` has `"simulated": true`.
- The always-on **human-review clause** is mandatory in every case.

## Rules

- **No LLM SDK in any skill, including this one.** Pure markdown — `SKILL.md` only.
- **One slug per topic, computed identically across skills.** The contract above is non-negotiable.
- **Never collapse the four skills into one agent run.** Each skill's `SKILL.md` is the single source of truth for what counts as "done" for its artifact.
- A non-interactive runner (e.g. `claude --print` headless) lives **outside** the skills. The skills stay pure.
````

## File: README.md
upstream: https://github.com/ai4s-research/ai4s-skills/blob/main/README.md

````text
<div align="center">

[![AI4S Skills — agent skills for AI for Science](assets/banner.webp)](https://github.com/ai4s-research/ai4s-skills)

Seven agent skills for AI-for-Science research — turn a research direction into
literature surveys, runnable experiments, publication-grade papers, and integrity
audits, with every citation, number, and figure traceable to its source.

<p align="center"><b>English</b> · <a href="README.zh.md">中文</a></p>

<p>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
  <a href="https://doi.org/10.5281/zenodo.21297455"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21297455-1682D4" alt="DOI"></a>
  <img src="https://img.shields.io/badge/skills-7-success" alt="7 skills">
  <a href="http://makeapullrequest.com"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
  <a href="https://linux.do"><img src="https://img.shields.io/badge/Join-linux.do-orange" alt="linux.do"></a>
</p>

</div>

---

## Contents

- [🧩 The skills](#the-skills)
- [🔗 How they connect](#how-they-connect)
- [✅ Authenticity](#authenticity)
- [🔬 Example](#example)
- [📦 Install](#install)
- [🚀 Usage](#usage)
- [🗂️ Repository layout](#repository-layout)
- [🛠️ Included tools](#included-tools)
- [🤝 Contributing](#contributing)
- [⚖️ License](#license)
- [🙏 Acknowledgments](#acknowledgments)

## The skills

| Skill | Role | Primary output |
|---|---|---|
| [ai4s-agent](skills/ai4s-agent/SKILL.md) | Runs the four skills below in order | the full package |
| [research-explorer](skills/research-explorer/SKILL.md) | Explore topics from a broad direction | `research_exploration.md`, `topic_matrix.md`, `literature_pre_survey.md` |
| [literature-survey](skills/literature-survey/SKILL.md) | Write a literature survey | 6–20 pp PDF, 60+ real citations, LaTeX source, topic-specific figures |
| [experiment-suite](skills/experiment-suite/SKILL.md) | Build an experiment package | design doc, runnable code, `results.json` with provenance, figures, report |
| [paper-writer](skills/paper-writer/SKILL.md) | Write a research paper | 8–14 pp PDF, 200+ citations, 4–8 figures, tables |
| [mindmap-render](skills/mindmap-render/SKILL.md) | Render a mindmap | image from a `topic_matrix.md` (Python script) |
| [integrity-auditor](skills/integrity-auditor/SKILL.md) | Audit a paper's integrity | image / numerical / logical findings, 4-level evidence grading, `audit_report.md` |

Each skill is a folder with a `SKILL.md` plus its own references, templates, and
tools. MIT-licensed; works with Claude Code, Cursor, Codex, and Aider.

## How they connect

```
direction
   │
   ▼
[1] research-explorer ──▶ pick one $TOPIC
   │
   ├──▶ [2] literature-survey   → survey PDF + bibliography.bib
   ├──▶ [3] experiment-suite    → results.json + figures/
   └──▶ [4] paper-writer        → paper PDF  (reuses [2] and [3])

integrity-auditor ──▶ audits any paper: external PDF / DOI / arXiv, or [4]'s output
```

`ai4s-agent` runs steps 1–4 in order. Skills pass work to each other through a
shared slug and the path `output/<skill>/<slug>/latest/`.

## Authenticity

The focus of the project. Every skill enforces:

| Principle | In practice |
|---|---|
| **Real citations** | Every BibTeX entry links to a URL the agent fetched in the same session; none from memory. |
| **Labelled numbers** | Every number is marked `measured`, `simulated`, or `illustrative`; simulated values are never reported as measured. |
| **Runnable experiments** | `experiment-suite` outputs runnable code and a `results.json` with provenance. Supply real results and they replace the simulated ones; the "simulated" disclosure is then removed. |
| **Resumable runs** | Long tasks save progress after each step and continue from the last checkpoint, so a reported "done" reflects completed work. |
| **Publication layout** | Readable booktabs tables; final-size raster QA; vector-PDF figures with embedded fonts, shared color-safe styling, and no generic diagram-tool output. |
| **Review disclosure** | Every generated document states that domain-expert review is recommended. |
| **Integrity checks** | `integrity-auditor` inspects a paper for image, numerical, and logical problems and grades the evidence. |

## Example

A complete run from `experiment-suite` + `paper-writer`: **"Learning the Burgers
Solution Operator with a Fourier Neural Operator"** — an 8-page paper backed by code
the agent wrote and ran. Full artifact in [`examples/fno-burgers/`](examples/fno-burgers/)
(paper, code, `results.json`, report).

<div align="center">
<table>
<tr>
<td><a href="examples/fno-burgers/paper.pdf"><img src="assets/paper/page-1.webp" width="230" alt="paper page 1"></a></td>
<td><a href="examples/fno-burgers/paper.pdf"><img src="assets/paper/page-2.webp" width="230" alt="paper page 2"></a></td>
<td><a href="examples/fno-burgers/paper.pdf"><img src="assets/paper/page-3.webp" width="230" alt="paper page 3"></a></td>
</tr>
<tr>
<td><a href="examples/fno-burgers/paper.pdf"><img src="assets/paper/page-4.webp" width="230" alt="paper page 4"></a></td>
<td><a href="examples/fno-burgers/paper.pdf"><img src="assets/paper/page-5.webp" width="230" alt="paper page 5"></a></td>
<td><a href="examples/fno-burgers/paper.pdf"><img src="assets/paper/page-6.webp" width="230" alt="paper page 6"></a></td>
</tr>
</table>
<sub><i>The 8-page paper (first 6 pages) — click any page for the full PDF.</i></sub>
</div>

- **Real code, really run** — `model.py` is a 1-D FNO; the full study runs in ~35 min on a laptop CPU.
- **Measured results** — FNO 4.41% rel-L2 vs MLP 21.63% and CNN 67.69% (3 seeds); zero-shot super-resolution holds 4.2–4.7% from grid 128 to 1024.
- **Real citations** — 22 references, each traceable to its source.

Every number is `measured` (provenance in `results.json`); the paper states it was
AI-generated and recommends domain-expert review.

## Install

Run the installer from the project you want the skills in:

```bash
git clone https://github.com/ai4s-research/ai4s-skills

cd /path/to/your-project
/path/to/ai4s-skills/install.sh                              # all skills → ./.claude/skills
/path/to/ai4s-skills/install.sh paper-writer                 # or specific ones
SKILLS_DIR=~/.claude/skills /path/to/ai4s-skills/install.sh  # global instead
```

To install by hand, copy any `skills/<name>/` into `~/.claude/skills/` (global) or
`<project>/.claude/skills/` (project).

## Usage

In Claude Code:

> Use the literature-survey skill to write a survey on \<your topic\>.

With Cursor, Codex, or Aider, point the agent at the skill file:

```
Read skills/literature-survey/SKILL.md and its references/, then produce the survey
for "<your topic>" as specified.
```

Each `SKILL.md` directs the agent to read its `references/` first; those files hold
the procedures for bibliography expansion, figures, layout, and quality checks.

## Repository layout

```
ai4s-skills/
├── skills/
│   ├── ai4s-agent/          SKILL.md + references/
│   ├── research-explorer/   SKILL.md
│   ├── literature-survey/   SKILL.md + references/ + templates/survey/
│   ├── experiment-suite/    SKILL.md + references/ + figure_examples/
│   ├── paper-writer/        SKILL.md + references/ + templates/paper/
│   ├── mindmap-render/      SKILL.md + scripts/ + tests/
│   └── integrity-auditor/   SKILL.md + references/ + forensics_tools/ + templates/ + tests/
├── tools/validate_skills.py   structure / frontmatter validator (run in CI)
├── install.sh
└── .github/workflows/ci.yml
```

Each `SKILL.md` carries YAML frontmatter (`name`, `description`) so an agent can
find and route to it.

## Included tools

Small, single-purpose scripts the skills call. Each directory has its own
`requirements.txt`.

- `skills/integrity-auditor/forensics_tools/` — image duplication / ORB matching, panel splitting, channel checks, magnitude (Benford-style) consistency, decimal matching, spreadsheet aggregate consistency.
- `skills/exp
````
