QUICK START

Quick Start

Choose a task. Copy its instructions into an AI conversation with your papers attached.

  1. 1Attach Your Papers
  2. 2Copy a Prompt
  3. 3Download the Collection

Start With Your Papers

For creating or editing a collection, use an AI app that can read files and run code. Attach PDFs, photos, or an existing .showpapers file, then copy the instructions below.

Make A File From My Papers

Prompt
Make a ShowPapers collection from the papers I attached.

1. Read https://protocol.showpapers.app/llms.txt and follow the Agent Guide it links (https://protocol.showpapers.app/md/SHOWPAPERS_AGENT_GUIDE.md) exactly.
2. Create a .showpapers collection using the current collection format (formatVersion: 4): one original per paper, a clear title for each (no "/" or "\"), and all useful details supported by every page (including continuation pages) as agent details with your confidence and a short quote as evidence. Propose each paper's type. Do not stop after a few example fields; capture document-specific details, and report unreadable pages, missing information and uncertain values without guessing.
3. Mark extracted details and proposed relationships as origin "agent", identify yourself in agents[], and use type.agentSuggestion for proposed paper types. Use only the defined fields for notes, folders, people and reminders. Leave your suggestions unconfirmed; I will review them in ShowPapers.
4. Run showpapers_format.py validate using https://protocol.showpapers.app/tools/showpapers-format.zip, or check the file in https://protocol.showpapers.app/validate, and fix every error. State which checker ran and its result. If you cannot run either checker, clearly mark the file unvalidated and ask me to check it; do not present reading the rules as validation.
5. Give me the file, named something like "My papers.showpapers", and a short list of what you added. Include https://protocol.showpapers.app/open for instructions on previewing, sharing and opening the downloaded collection.

Already have your file? See What To Do Next: check its contents here, get ShowPapers if you need it, and find the opening instructions for your device.

Find Missing Details In My Collection

Prompt
Enrich the ShowPapers collection I attached. Follow https://protocol.showpapers.app/md/SHOWPAPERS_AGENT_GUIDE.md.

1. Inspect the saved records and every page of each available original, including continuation pages. Compare them and propose useful details the records missed, using the defined vocabulary or "other" with a precise label.
2. Include source quotes and zero-based pages when available. Flag uncertain or conflicting values and tell me which originals or pages you could not read. Do not guess missing information.
3. Preserve original bytes, IDs, readings, confirmed and corrected values, evidence and removed suggestions. Do not duplicate existing details or restore suggestions I removed. Mark new details as origin "agent", identify yourself and leave them unconfirmed.
4. Use the reference tool to edit, create and validate a new file. If you cannot write an archive, return a supported changes document bound to the exact collection instead.
5. Give me the validated file or changes document, a concise list of what you added, what you inspected and the gaps I still need to review. Include https://protocol.showpapers.app/open.

Organize My Existing File

Prompt
This is my ShowPapers collection (.showpapers or .showpapers.zip). Using the rules at https://protocol.showpapers.app/llms.txt:

- Group the papers into sensible folders, suggest who each paper belongs to, and add reminders for papers with an end date.
- Keep every existing record, ID and value exactly as it is. Add only what I asked for. Mark new details and relationships as origin "agent" with your agentId; put type proposals in type.agentSuggestion. Other records use their defined fields, without invented origin or review members.
- Use "edit" and then "create" from the reference tool (https://protocol.showpapers.app/tools/showpapers-format.zip), or a changes document if you cannot run code.
- Validate the result, then give me the new file and a list of every change. Include https://protocol.showpapers.app/open for local preview and opening instructions.

Answer Questions And Propose Changes

ShowPapers shares the plain .showpapers file itself, unchanged — the receiving AI app must support reading the attachment. If you can open ZIP files, just read it directly:

Prompt
The attached file is a ShowPapers collection (.showpapers, a ZIP archive — unzip it and read manifest.json and the files it lists). Use it to answer my questions. If I ask you to change anything and you cannot write a new file, follow https://protocol.showpapers.app/hand-back and give me a changes document (schema urn:showpapers:changes:1) whose base uses the collection id and revision from manifest.json and the SHA-256 of the exact archive bytes. Hash the archive or use archive.sha256 from its companion; the manifest does not contain the archive’s own digest. Put every value you propose in it; don't claim anything is confirmed.

If your app cannot open ZIP files at all, ask for the optional plain JSON companion instead:

Prompt
I can't open ZIP files. Please export a plain JSON companion of your ShowPapers collection (see https://protocol.showpapers.app/spec/ai-interchange#companion-optional, schema urn:showpapers:companion:2) and attach that instead, or tell me what's in the collection yourself.

Check A File

Prompt
Check this .showpapers file against https://protocol.showpapers.app/md/SHOWPAPERS_FULL_FIDELITY.md. Run the reference validator if you can (https://protocol.showpapers.app/tools/showpapers-format.zip: python3 showpapers_format.py validate FILE). Tell me whether it is valid, what it contains (papers, details and who proposed them, people, folders, reminders, notes, relationships), and every problem with the exact rule it breaks.

Files are readable by anyone who receives them. Cloud AI services can read uploaded papers and handle them under their own privacy and retention practices. For sensitive papers, use a service you trust or a trusted local AI setup configured to keep document content on your device, including any connected tools. You can also check any file yourself in the browser validator, which never uploads it.

Use It In Your Workspace

Install the ShowPapers Collections skill to give a compatible assistant reusable instructions for creating, enriching and checking collections. It includes the guide, schemas and a Python reference tool, so the collection tools can run locally after installation. A local skill does not make a cloud assistant local: the assistant may still send document content to its provider.

Download the ZIP, inspect its contents, then extract its showpapers-collections folder into your assistant's workspace skill directory. For Codex, run these commands from the workspace root:

mkdir -p .agents/skills
unzip -n /path/to/showpapers-collections-skill.zip -d .agents/skills

Ask: Use the showpapers-collections skill to create a collection from these papers, checking every page for useful details. For an existing file, ask it to inspect the originals and propose missing details while preserving your reviewed work. Other assistants can use the same SKILL.md folder when they support local skills; use that assistant's documented installation directory.

See Codex skill installation guidance. An assistant still needs access to the files and a code execution environment to create a collection.

For Developers

The reference tool needs Python 3.10 or later and nothing else. Download it, unzip, and inspect the manifest schema:

python3 showpapers-format/showpapers_format.py schema --kind manifest --version 4

Create a file from a build specification (see the agent guide for a complete example), then check it:

python3 showpapers-format/showpapers_format.py create --spec build.json --output trip.showpapers
python3 showpapers-format/showpapers_format.py validate trip.showpapers
python3 showpapers-format/showpapers_format.py contents trip.showpapers

Edit any file, or apply a changes document, always writing a new file:

python3 showpapers-format/showpapers_format.py edit trip.showpapers --output-directory trip-edit
python3 showpapers-format/showpapers_format.py create --spec trip-edit/build.json --output trip-2.showpapers

For a changes document, preview it against its base and write a separate new file:

python3 showpapers-format/showpapers_format.py preview trip.showpapers --changes changes.json
python3 showpapers-format/showpapers_format.py apply trip.showpapers --changes changes.json --output trip-changed.showpapers
python3 showpapers-format/showpapers_format.py companion trip.showpapers --output trip.showpapers.json

Implementing a reader or writer in another language? Read the collection format, generate code from the schemas, and test against every file in Examples: read the valid ones with every value intact, and refuse each invalid one with its error code.