agentleFS
Sign inStart free
sepi2psepi2p/research-explainer-skill/AGENTS.md

research-explainer-skill

AGENTS.md9 starsChanged 13 days agoMITView on GitHub

You are installing or using research-explainer, a skill that builds 3Blue1Brown-style research explainer videos with Manim (English and Persian). Follow these steps in order. Ask the user before any sudo command, any paid API use, and any download larger than about 500 MB. 1. Check the platform. Linux and macOS are supported. On Windows, use WSL (Ubuntu) and follow the Linux steps inside it. 2. System tools. Check with ffmpeg -version, pkg-config --modversion pangocairo, uv --version. Install only what is…

  • Pipes a download into a shell
  • Installs packages
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository4 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

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

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

    System tools: Check with ffmpeg -version, pkg-config --modversion pangocairo, uv --version.

    line 10
  2. Very specific:

    If manim is not on PATH, it is in ~/.local/bin/manim.

    line 16
  3. Very specific:

    Start with rx.py status in the project folder.

    line 76
  4. Very specific:

    Every new feature updates skills/research-explainer/SKILL.md (or the relevant reference file) and CHANGELOG.md in the same commit, or …

    line 89
  5. Very specific:

    Before pushing: python3 skills/research-explainer/scripts/rx.py selftest must print PASS, and claude plugin validate .

    line 92
  6. Distinctive:

    Keep outputs short: commands print one line per item and a next step, not whole files.

    line 94
  7. Distinctive:

    Never commit unpublished research data, private paths, or keys.

    line 95

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “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
AGENTS.md

Instructions for AI agents

You are installing or using research-explainer, a skill that builds 3Blue1Brown-style research explainer videos with Manim (English and Persian). Follow these steps in order. Ask the user before any sudo command, any paid API use, and any download larger than about 500 MB.

Install (Claude Code)

  1. Check the platform. Linux and macOS are supported. On Windows, use WSL (Ubuntu) and follow the Linux steps inside it.
  2. System tools. Check with ffmpeg -version, pkg-config --modversion pangocairo, uv --version. Install only what is missing, after the user agrees:
    • Debian/Ubuntu: sudo apt install -y ffmpeg libcairo2-dev libpango1.0-dev pkg-config python3-dev
    • macOS (Homebrew): brew install ffmpeg cairo pango pkg-config
    • uv: curl -LsSf https://astral.sh/uv/install.sh | sh (or pipx install uv)
  3. Manim. uv tool install manim, then check with manim --version (expect "Manim Community v0.19" or newer). If manim is not on PATH, it is in ~/.local/bin/manim.
  4. The skill. Either way works; prefer A inside Claude Code.
    • A (plugin): run claude plugin marketplace add sepi2p/research-explainer-skill and then claude plugin install research-explainer@research-explainer-skill (add --scope project for one project only). Then install the fonts: python3 <plugin skill dir>/scripts/rx.py fonts. The skill folder is under ~/.claude/plugins/cache/research-explainer-skill/research-explainer/<version>/skills/research-explainer/.
    • B (script):
      git clone https://github.com/sepi2p/research-explainer-skill.git
cd research-explainer-skill && ./install.sh          # --project: this project only; --codex: ~/.agents/skills
      This copies research-explainer, manim-composer, manimce-best-practices and manimgl-best-practices into ~/.claude/skills/, and installs the Inter and Vazirmatn fonts.
  5. Verify. python3 <skill dir>/scripts/rx.py check must end with ready. Lines starting with (optional) may show --; that only means those features are unavailable.
  6. Optional extras (ask the user):
    • free voice: uv tool install piper-tts. Voices download on first use.
    • paid OpenAI voice: the user creates ~/.config/openai/key themselves (chmod 600). Never ask for the key in the chat, never print it, and never write it anywhere else.
    • LaTeX for MathTex: sudo apt install texlive-latex-extra (Linux) or brew install --cask mactex-no-gui (macOS).
  7. Smoke test (about 1 minute; needs the cloned repo, or the plugin folder, which contains examples/ too):
    cd examples/averaging-noise
python3 ../../skills/research-explainer/scripts/rx.py build en --voice none --quality l
    It must print a line ending in .srt. The video is in examples/averaging-noise/build/.
  8. Tell the user it is installed and that a new Claude Code session is needed for the skill to appear. Then tell them how to start: "make an explainer video of <paper/project>".

Optional: launch-video engine

Needed only for rx.py promo (short promo videos). Requires Node.js 18+:

cd <skill folder>/promo && npm install && npx playwright install chromium

(Chromium download is ~150 MB; ask the user first.)

Install (OpenAI Codex CLI / IDE, ChatGPT desktop app)

Steps 1-3 above (system tools, Manim) are the same. Then either:

  • plugin: codex plugin marketplace add sepi2p/research-explainer-skill and codex plugin add research-explainer@research-explainer-skill. In the ChatGPT desktop app, add the same marketplace and install the plugin from the Plugins directory (not tested yet).
  • or copy the skills: ./install.sh --codex (into ~/.agents/skills; restart Codex).

Then python3 <skill dir>/scripts/rx.py fonts and rx.py check. In Codex the skill is invoked with $research-explainer (or implicitly when the user asks for an explainer video). ${CLAUDE_SKILL_DIR} in SKILL.md means the folder that contains SKILL.md; substitute that path yourself if your agent does not.

ChatGPT on the web or mobile

There is no local shell there, so Manim and FFmpeg cannot run. The skill still works for planning: intake, claims ledger, scene plan, narration and scene code. Rendering needs Claude Code, Codex, or the ChatGPT desktop app. Say so to the user; never claim a video was rendered.

Use

Load skills/research-explainer/SKILL.md and follow it. In short: intake questions, then the claims ledger, real assets, a scene plan the user approves, narration and scenes, rx.py build, contact-sheet review, and delivery. Accuracy rules are in references/accuracy.md; follow them strictly.

Start with rx.py status in the project folder. If something the user needs is missing, log it with rx.py request (see SKILL.md) instead of silently working around it.

Troubleshooting

symptomfix
pangocairo / cairo build error while installing maniminstall the system libraries in step 2, then uv tool install --force manim
font Vazirmatn missing in checkrx.py fonts; on Linux also fc-cache -f
scene fails only during parallel rendersrx.py retries it alone automatically; if it persists, run with JOBS=1
MathTex errorsLaTeX is missing: install it, or use T() text instead
Persian label still in Englishrx.py strings fa, then add it to strings_fa.json

For maintainers (and agents changing this repo)

  • Every new feature updates skills/research-explainer/SKILL.md (or the relevant reference file) and CHANGELOG.md in the same commit, or agents will not know it exists.
  • Error messages say what to do (ERROR: ... / FIX: ...). Accept common wrong names where it is cheap.
  • Before pushing: python3 skills/research-explainer/scripts/rx.py selftest must print PASS, and claude plugin validate . must pass.
  • Keep outputs short: commands print one line per item and a next step, not whole files.
  • Never commit unpublished research data, private paths, or keys. Examples use public or synthetic data only.
  • Answer feature-request issues with the steps to use the new feature, then close them.

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.

Check your setup, free