agentleFS
ZhangyanboZhangyanbo/vibe-research-skill/skills/vibe-research/SKILL.md

vibe-research

Skill27 starsChanged 3 months agoMITView on GitHub

Set up and organize a Vibe Research project - a research workflow where the human scientist defines goals, standards and boundaries, and agents work autonomously within them. Use when starting a new research project, migrating an existing project into this structure, preparing a branch merge, or whenever the user mentions vibe research, research project setup, experiment scaffolding, or project migration.

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use my-scientific-taste together with other skills when writing paper, writing code, exploring ideas.

    line 39
  2. Very specific:

    Use my-scientific-taste when you facing situations that user did not specify.

    line 40
  3. Distinctive:

    Never overwrite a file that has content.

    line 63
  4. Very specific:

    Every formal figure in result/ can be re-plotted directly from git-tracked data

    line 72
  5. Distinctive:

    After the merge, clean up branches that are safe to delete.

    line 74

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Vibe Research (core skill)

Set up and maintain Vibe Research projects: the user defines goals, standards and boundaries; the agent chooses the means within them. This skill covers project setup, migration of existing projects, deciding which skill to use when, and merge acceptance. Only this skill references other skills; the other skills never reference each other.

This skill's version is recorded in VERSION (currently 2.2.0).

Staying current (do this first, once per session)

The first time this skill loads in a session, run the version check and act on its verdict. It is read-only and fails silently offline, so it never blocks work.

bash ~/.claude/skills/vibe-research/check-update.sh

(If the skills live elsewhere, run the check-update.sh sitting next to this file.) It compares the installed VERSION files against the published ones on GitHub and prints ACTION lines:

  • ACTION AUTO_UPDATE vibe-research — a minor or patch update. Update without asking, then tell the user in one line what changed.
  • ACTION ASK_USER vibe-research — a major update. Summarize what a major bump implies and ask before updating.
  • ACTION ASK_USER my-scientific-taste — always ask. That file holds the user's own taste; never overwrite it silently. If the check reports it as customized, leave it alone.
  • ACTION NONE / any check skipped line — do nothing, say nothing, continue.

To update: clone https://github.com/Zhangyanbo/vibe-research-skill and copy the relevant folders under skills/ into the skills directory (~/.claude/skills/), replacing the old ones — but never replace my-scientific-taste without the user's approval. The copied folder brings its new VERSION with it, so the next check sees the bump. Do this once; do not re-check later in the same session.

Which skill to use when

SituationDefault skillAlso consult
Writing codevibe-research-codingmy-scientific-taste
Writing the papervibe-research-papermy-scientific-taste
Exploring ideas, running experimentsvibe-research-exploremy-scientific-taste
Large-scale parameter searchvibe-research-optimizemy-scientific-taste
Plottingnature-style
  • Use my-scientific-taste together with other skills when writing paper, writing code, exploring ideas.
  • Use my-scientific-taste when you facing situations that user did not specify. Taste is your boundary for what is acceptable and what is not. It is your default when the user did not specify.
  • For plotting, use nature-style; if it is not installed, install it from https://github.com/Zhangyanbo/nature-style-skill.

Project template

This skill ships with template/: the project structure and the CLAUDE.md file for each directory. Copy it directly when initializing or migrating, then instantiate it for the user's situation. The CLAUDE.md files carry the always-on rules (directory organization, decision boundaries, figure requirements) and the project's accumulated lessons; skills carry workflows. The two do not repeat each other.

Initializing a project

  1. Ask first; never skip this:
    • What is the research question? (a sentence or two is enough)
    • What are the hard boundaries? (compute budget, data that must never be touched, anything else off-limits)
    • Which language does the user read the paper in? (English is always the authoritative version; the user-language version serves the user's own thinking)
    • Where do existing code and data live?
  2. Copy template/ to create the structure: CLAUDE.md, paper/, src/, result/, data/, tmp/, todo.md.
  3. Instantiate the CLAUDE.md files from the user's answers (the language policy goes into the slot in paper/CLAUDE.md).
  4. git init, uv init.

Migrating an existing project

  1. Understand the project first: the experiment flow, the goal, where results live. Ask if unclear.
  2. Inventory existing files and place them by whether the user reads them: code → src/, figures and conclusions for humans → result/, large artifacts → data/, drafts → tmp/.
  3. Move files with git mv; update path references in code; run a small smoke test (estimate the runtime first; ask before anything over 10 minutes).
  4. Never overwrite a file that has content; show the user the diff when there is a conflict.

Merge acceptance

Merging back to the main branch requires the user's confirmation: a merge is acceptance, and work is never accepted by the one who did it. The user judges mainly from the figures; every check below exists to make that judgment cheap and truthful. Before the merge, check:

  • Paper and code are in sync (this is the moment to sync, not on every change)
  • The paper-code-figure consistency check reports factual mismatches only (contradicting numbers, text contradicting figures); loose wording is not a violation
  • tmp/ is empty; sweep-style temporary outputs are cleaned up
  • Every formal figure in result/ can be re-plotted directly from git-tracked data

After the merge, clean up branches that are safe to delete.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.