Open Science Collective Agent Readiness
Make your open-science tools legible to AI agents, transparently.
OSCAR is the best practices, rules, and tools that make an open-science project ready for AI agents. It helps any maintainer answer two questions:
- How do agents find out my tool exists, and what it does?
- How do agents use my tool to the fullest once they have found it?
It is a resource of the OpenScience Collective, a sibling to the Open Science Assistant (OSA). Where OSA is an assistant that uses open-science tools, OSCAR is the standard that makes those tools usable by any assistant.
Everything OSCAR asks you to publish is public, human-readable, and linked from your site. Anything an agent is told, a person can open and audit.
OSCAR does not use, and actively warns against,
hidden text, invisible instructions, or comment-only directives aimed at agents.
Those techniques are a form of indirect prompt injection;
security teams catalog them as an attack, and they erode the trust open science runs on.
See docs/principles.md.
An agent never sees your rendered page, your styling, or your buttons. It reads the text in the payload. OSCAR's job is to make that text excellent and honest.
What a human sees What an agent reads (/llms.txt)
----------------- ------------------------------
[ rendered page, CSS, buttons ] # Your Tool
> One-line description of what it is.
"Try the demo" -> button ## Start here
- [Docs](https://...): ...
- [Demo](https://...): try it now
Machine-actionability is not new.
The FAIR principles (2016) already called for data usable by an
"autonomously-acting, computational data explorer."
OSCAR operationalizes FAIR's Interoperable and Reusable principles for a new such explorer,
the AI agent, and extends them from datasets to every kind of tool.
It also closes a gap: parts of the scholarly web solved structured metadata years ago
but now regress into client-rendered app shells an agent cannot read,
while the newer agent conventions have barely reached open science at all.
See docs/grounding.md.
A "tool" is not one thing, so OSCAR gives a recipe per archetype. Most projects are a combination of two or three.
| Archetype | Example | Primary techniques |
|---|---|---|
| Website / docs site | eeglab.org, nemar.org | llms.txt, AGENTS.md, AI-friendly robots.txt, JSON-LD, markdown mirrors |
| Command-line tool | nemar-cli |
machine-readable --help, AGENTS.md, examples cookbook, optional MCP server |
| Library / toolbox | EEGLAB (MATLAB) | docstrings, typed signatures, docs llms.txt, MCP server, worked notebooks |
| Web app / API | HEDit, OSA | OpenAPI spec, MCP server, JSON-LD SoftwareApplication, clear auth and limits |
| Data archive | NEMAR | schema.org Dataset, machine-readable catalog, query + metadata + bulk download |
| Research lab / project site | a lab or project website | JSON-LD Organization/Person/SoftwareSourceCode, persistent IDs (ORCID, ROR, DOI) |
| Standard / specification | BIDS, HED | machine-readable schema, a callable validator, versioned citable spec |
OSCAR curates instructions for the kinds of project the OpenScience Collective services:
data archives, tools and toolsets, research lab and project sites, and standards.
The set is meant to be extensible; new archetypes and worked examples are added as the landscape grows.
Full guides live in docs/archetypes/.
Two files are site-wide and live at the origin root; everything else is per-resource.
| Artifact | Location | Scope |
|---|---|---|
robots.txt |
site root, /robots.txt |
one per origin, never per-page |
llms.txt |
site root, /llms.txt |
one per site; links out to per-section pages |
AGENTS.md |
repo root, optionally site root | one per repo; may nest per subdirectory, closest wins |
| JSON-LD / schema.org | each page's <head>, server-rendered |
per page |
| Markdown mirror | beside each page, /x to /x.md |
per page |
Signposting Link |
HTTP header or <link> per resource |
per resource |
You never fork llms.txt or robots.txt per page.
Per-page detail is the JSON-LD's job:
a homepage carries Organization, a dataset page Dataset, a tool page SoftwareApplication.
The one root llms.txt gains depth by linking to those pages, not by cloning itself.
oscar/
docs/ The doctrine: principles + one guide per archetype + a checklist
templates/ Copy-paste starter files (llms.txt, AGENTS.md, robots.txt, JSON-LD)
examples/ Worked case studies (HEDit, EEGLAB, NEMAR)
brand/ Logo and favicon
- Read
docs/principles.md, the non-negotiables. - Find your archetype(s) in
docs/archetypes/. - Copy the matching starter files from
templates/and fill them in. - Self-audit against
docs/checklist.md. - Link the files from your site footer so they are auditable.
Early and public.
The principles and the archetype framework are stable;
the per-archetype guides and worked examples are being written in the open.
See .context/plan.md for the roadmap.
Documentation and templates: Creative Commons Attribution 4.0 (CC-BY-4.0).
Code (generators, scripts): MIT.
See LICENSE.