Research Guardrail

Research Guardrail Skill

Research Guardrail is a skill for AI-assisted research coding. It helps researchers use coding agents without losing the parts of the work that create understanding, judgment, and ownership — and without letting plausible-looking code silently poison a scientific result.

It applies across research and data/scientific coding — machine learning, data analysis, simulations, statistics, computational science, and beyond.

中文说明

At a Glance

How the skill routes each piece of work — from a one-off transform to a full paper reproduction — toward the right level of human ownership and the verification it needs:

flowchart TD
    T([Research / data-science<br/>coding task]) --> SIZE{How big<br/>is the task?}

    SIZE -->|"Quick & mechanical<br/>(one transform · a plot · a fix)"| Q[Just do it]
    Q --> Z{Touches a<br/>silent-bug zone?}
    Z -->|no| SHIP([Ship])
    Z -->|yes| GATE

    SIZE -->|"Substantial<br/>(reproduce · new method ·<br/>pipeline · teaching)"| SPLIT[Split into modules]
    SPLIT --> GRID{{"Place each module on two axes:<br/>learning value × correctness risk"}}

    GRID --> C1["High learning · Low risk<br/>MANUAL CORE<br/>own it to understand"]
    GRID --> C2["High learning · High risk<br/>MANUAL CORE + verify"]
    GRID --> C3["Low learning · Low risk<br/>AGENT-OWNED<br/>automate freely"]
    GRID --> C4["Low learning · High risk<br/>AGENT-DRAFTED<br/>never trust blind"]

    C1 --> SHIP
    C3 --> SHIP
    C2 --> GATE
    C4 --> GATE

    GATE[["🔒 VERIFICATION GATE<br/>a concrete, runnable check<br/>that catches the silent error"]] --> SHIP

    classDef manual fill:#e6f0ff,stroke:#3b82f6,color:#1e3a8a;
    classDef agent fill:#e8f7ee,stroke:#22c55e,color:#14532d;
    classDef gate fill:#ffe3e3,stroke:#ef4444,color:#7f1d1d;
    classDef plain fill:#f3f4f6,stroke:#6b7280,color:#111827;
    class C1,C2 manual;
    class C3,C4 agent;
    class GATE gate;
    class T,SHIP plain;

Reading the colors: 🟦 manual core preserves your understanding — you own the part worth owning; 🟥 the verification gate protects the result — a runnable check on silently-wrong code, non-negotiable; 🟩 agent-owned is safe to automate freely.

Install

Claude Code

As a plugin (recommended) — the repo ships a plugin marketplace, so you can install it with /plugin:

/plugin marketplace add carryons6/research-guardrail-skill
/plugin install research-guardrail@research-guardrail-skill

As a personal skill — clone into your skills directory:

git clone https://github.com/carryons6/research-guardrail-skill.git ~/.claude/skills/research-guardrail

Or use it as a project skill by placing it under .claude/skills/research-guardrail/ in your repository. Claude Code discovers the skill automatically from the SKILL.md frontmatter.

Codex

Quick install (recommended) — one line; installs into ~/.codex/skills/research-guardrail. Re-run it later to update.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/carryons6/research-guardrail-skill/main/install.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/carryons6/research-guardrail-skill/main/install.ps1 | iex

Then restart Codex so it can discover the skill. The scripts honor CODEX_HOME and RESEARCH_GUARDRAIL_REF (branch/tag) if you need to override them.

Other methods

Built-in skill installer:

Use $skill-installer to install the skill from https://github.com/carryons6/research-guardrail-skill.
Use path "." and install it as "research-guardrail".

Manual clone:

mkdir -p ~/.codex/skills
git clone https://github.com/carryons6/research-guardrail-skill.git ~/.codex/skills/research-guardrail

Triggering the Skill

The skill is explicit-invocation only — it will not fire on its own, even when your task looks like paper reproduction, method development, or pipeline work. Invoke it by name when you want it:

• Claude Code: run the /research-guardrail slash command, or just ask in plain language, e.g. "Use the research-guardrail skill to plan how I should reproduce this paper."
• Codex: $research-guardrail.

On the first substantial task after you invoke it, the skill runs a short calibration (3–5 questions) before it produces a plan.

What It Does

The skill adds a research-agency guardrail before substantial coding work. It guards against two different ways AI-assisted research goes wrong:

• Lost understanding — the agent did the interesting part, so the researcher never built the intuition.
• Lost trust — the agent wrote plausible code that was silently wrong, and a conclusion got poisoned.