biorxiv-search · diff
git:20260905.3e49039 to git:20261001.bf5afd6
57 added, 142 removed. Audit A to A.
---
name: biorxiv-search
- description: Search bioRxiv through its official API and filter title, abstract, and author metadata. Use when finding recent biology preprints, scanning date ranges, resolving DOIs, or building author shortlists.
+ description: Scan bioRxiv by date range, category, author, or DOI through its official API, with local keyword filtering. Use for recent biology preprints, bioRxiv DOI lookups, or author shortlists.
---
# bioRxiv Search
- Search bioRxiv through its official API for recent-preprint discovery, date-range scans, DOI lookups, author shortlisting, and local keyword filtering over title, abstract, and author metadata.
+ Scan bioRxiv metadata through its official API for recent preprints, date ranges, DOI lookups, and author shortlists, with local keyword filtering over title, abstract, and authors.
## Instructions
- 1. Prefer this skill when the request is about bioRxiv-native preprints, recent biology submissions, or preprint metadata that may lag in PubMed, PMC, or Crossref.
- 2. Use the bundled CLI:
- - In this repository: `skills/biorxiv-search/scripts/search`
- - After installation: `~/.agents/skills/biorxiv-search/scripts/search`
- 3. The official bioRxiv API does not provide a general server-side keyword search endpoint.
- - Use the CLI to fetch metadata from a bounded recent window or explicit date range, then filter locally.
- 4. When keywords are provided, search `title`, `abstract`, and `authors` by default.
- - If the user wants abstract-only matching, pass `--fields abstract`.
- 5. Keep the search window bounded.
- - Use `--days N` for recent scans or `--start-date YYYY-MM-DD --end-date YYYY-MM-DD` for explicit intervals.
- - If you omit the interval, the CLI defaults to the most recent 30 days.
- - The CLI converts `--days N` into an explicit date range before calling the API so pagination stays predictable.
- 6. Use `--category <name>` when the topic should stay narrow.
- - The API accepts the bioRxiv category as a query parameter such as `cell_biology`, `genomics`, or `neuroscience`.
- 7. Use `--author` for author-specific requests.
- - By default, consider both the supplied full-name form and an abbreviated-first-name form, for example `--author "Peter Nugent"` and `--author "P. Nugent"`.
- - Do not silently merge these in the final answer. Report full-name matches and abbreviated-first-name matches in separate groups because initials can be ambiguous.
- - The CLI normalizes both given-name-first and API-style `Surname, F. M.` forms. Prefer separate passes or a local partition of returned records by the literal `authors` text when you need clean buckets.
- 8. The API currently returns up to 30 records per page.
- - The API orders an interval from oldest to newest. The CLI reads `count` and `total`, starts at the newest page, and scans backward.
- - Increase `--scan-limit` when a broad query needs more of the interval inspected.
- 9. By default, the CLI collapses multiple versions of the same preprint and keeps the latest version for each DOI.
- - Use `--all-versions` only when version-by-version output matters.
- 10. Treat the API output as discovery metadata.
- - If exact citation details or the latest abstract-page presentation matter, verify the shortlisted candidates on bioRxiv or the DOI landing page before finalizing the answer.
- 11. If the user wants peer-reviewed biomedical literature or PMC full text rather than bioRxiv preprints, use `polars-dovmed` instead.
- 12. The CLI retries `HTTP 429` and transient `5xx` responses with bounded exponential backoff. Output records the retry policy, the exact latest-version rule, and separate match groups for every requested author form; initial-only groups remain explicitly ambiguous.
+ 1. Use this skill for bioRxiv preprints and for preprint metadata that may lag in PubMed, PMC, or Crossref. Use `/arxiv-search` for arXiv and `/polars-dovmed` for peer-reviewed PMC full text.
+ 2. Run the bundled CLI, `scripts/search`. Paths below are relative to this skill's directory, installed at `~/.agents/skills/biorxiv-search`.
+ 3. The API has no keyword search. The CLI fetches metadata for a bounded interval and filters it locally.
+ - Set the interval with `--days N` or `--start-date YYYY-MM-DD --end-date YYYY-MM-DD`. Without one, the CLI uses the last 30 days and says so in `warnings`.
+ - The API returns 30 records per page, oldest first. The CLI starts at the newest page and scans backward until it has read `--scan-limit` records (default 300) or reached the start of the interval, then returns up to `max_results` matches.
+ 4. Write keyword queries in local query syntax:
+ - Words are combined with `AND`: `single cell atlas` needs all three words.
+ - `OR` must be explicit: `organoid OR spheroid`.
+ - Quoted phrases stay together: `'"single cell" atlas'`. `--phrase` treats the whole query as one phrase.
+ - Matching covers `title,abstract,authors` by default; `--fields abstract` restricts it to abstracts.
+ 5. Narrow the scan with `--category`, using the bioRxiv category name with underscores (`genomics`, `cell_biology`, `developmental_biology`).
+ 6. For author requests, pass the full-name and initial forms as separate `--author` values, for example `--author "Peter Nugent" --author "P. Nugent"`. The CLI also accepts `Surname, F. M.` forms and reports each form in its own match group. Report the groups separately and label initial-form matches as possibly a different person.
+ 7. The CLI keeps the latest version of each DOI. Use `--all-versions` when version history matters.
+ 8. Treat API output as discovery metadata. Check the final candidates on bioRxiv or the DOI landing page when citation or version details matter.
+ 9. The CLI spaces page requests at least 0.2 seconds apart and retries `HTTP 429` and transient `5xx` responses with exponential backoff (`--retries`, default 3; `--retry-backoff`, default 1 second).
## Quick Reference
| Task | Action |
|------|--------|
- | Search script | `skills/biorxiv-search/scripts/search` |
- | Base API | `https://api.biorxiv.org/details/biorxiv/...` |
- | Default search fields | `title,abstract,authors` |
+ | Keyword scan | `scripts/search "<query>" [max_results]` (default 10) |
| Recent window | `--days 30` |
| Date range | `--start-date YYYY-MM-DD --end-date YYYY-MM-DD` |
| DOI lookup | `--doi 10.1101/...` |
- | Category filter | `--category cell_biology` |
- | Author filter | `--author "Name"` |
- | Author variant workflow | Check full-name and abbreviated-first-name variants separately; report them separately |
- | Abstract-only filtering | `--fields abstract` |
- | Deduping | latest version per DOI by default |
+ | Category | `--category genomics` |
+ | Author | `--author "Name"`, repeatable |
+ | Search fields | `--fields title,abstract,authors` (default) or `--fields abstract` |
+ | Scan depth | `--scan-limit 300` |
| Keep all versions | `--all-versions` |
| Network timeout | `--timeout 30` |
- | Help | `skills/biorxiv-search/scripts/search --help` |
## Input Requirements
- - Python 3
- - One of:
- - a keyword query
- - a bioRxiv DOI via `--doi`
- - a request for recent/date-bounded preprints with no keyword query
- - Interval, category, author, field, and version flags are listed in Quick Reference; `--phrase` treats the whole query as one phrase.
- - If the user asks for very old or very broad searches, widen the date range deliberately and be explicit that recall depends on the chosen interval and `--scan-limit`.
-
- ## Search Semantics
-
- - The official bioRxiv API supports:
- - recent-post windows such as `30d`
- - explicit date ranges
- - DOI lookup
- - subject-category filtering
- - The API does not support a general server-side keyword query for title or abstract.
- - The CLI performs local filtering after fetching metadata.
- - For predictable paging, the CLI implements `--days N` as an explicit UTC date range instead of relying on the API's relative-date shorthand.
- - Interval searches start from the newest cursor and scan backward, so a bounded `--scan-limit` covers recent records first.
- - Plain multi-word queries are local `AND` queries.
- - `single cell atlas` means all three terms must appear somewhere in the selected search fields.
- - `OR` must be written explicitly to broaden synonyms or alternate phrasings.
- - `"organoid OR spheroid"`
- - `"CRISPR OR Cas9"`
- - Quoted phrases are preserved when possible.
- - `"\"single cell\" atlas"` keeps `single cell` as one phrase and also requires `atlas`.
- - `--fields abstract` restricts keyword filtering to abstracts only.
- - This is the flag to use when the user explicitly cares about abstract matches.
- - Author filters can fragment across name variants.
- - For person-specific searches, check the full-name form and abbreviated-first-name form separately and keep those buckets separate in the final answer.
+ - Python 3 on `PATH` and network access to `api.biorxiv.org`.
+ - One of: a keyword query, an author, a category, a bioRxiv DOI via `--doi`, or a request for recent preprints.
+ - A bounded interval. For old or broad searches, widen the interval and `--scan-limit` deliberately, and say that recall depends on both.
## Output
- - JSON with:
- - request metadata (`query`, `query_groups`, interval, category, author filters, search fields)
- - API metadata (`pages_fetched`, `records_scanned`, `total_available`, `request_urls`)
- - warnings about defaulted windows, scan-limit truncation, or API limitations
- - normalized result records with:
- - `doi`
- - `title`
- - `authors`
- - `date`
- - `version`
- - `category`
- - `abstract`
- - `published`
- - `doi_url`
- - `biorxiv_url`
- - `matched_in`
+ JSON with:
+ - `request`: query, `query_groups`, phrase flag, DOI, interval, category, author filters and expanded variants, search fields, limits, and retry settings
+ - `api`: `base_url`, `pages_fetched`, `records_scanned`, `total_available`, `request_urls`
+ - `result_summary`: matches before and after deduplication, `returned`, `versions_collapsed`, `version_policy`, `reached_scan_limit`
+ - `warnings`: defaulted interval, scan-limit truncation, missing filters
+ - `author_match_groups`: matches per requested author form
+ - `results`: `doi`, `title`, `authors`, `date`, `version`, `category`, `abstract`, `published`, `doi_url`, `biorxiv_url`, `matched_in`, and further API fields
+
## Quality Gates
- - [ ] The request uses a bounded recent window or explicit date range
- - [ ] The chosen `--scan-limit` is large enough for the query breadth
- - [ ] The selected search fields match the user request, especially when abstract matching matters
- - [ ] Author-specific requests use one or more reasonable name variants
- - [ ] The final answer keeps abbreviated-name matches separate and labels them as potentially ambiguous
- - [ ] The answer does not overstate recall for a broad historical search
- - [ ] Final candidate metadata is verified on bioRxiv when exact citation/version details matter
- - [ ] Output states the latest-version policy, keeps requested author forms in separate match groups, and uses bounded retry/backoff for 429 and transient 5xx responses.
+ - [ ] The scan uses a bounded interval, and `--scan-limit` fits the query breadth; `reached_scan_limit` is reported.
+ - [ ] Search fields match the request, especially when abstract matching matters.
+ - [ ] Author requests report full-name and initial-form groups separately, with initial-form matches labeled ambiguous.
+ - [ ] The answer does not overstate recall for a broad historical search.
+ - [ ] Citation or version details were checked on bioRxiv when they matter.
## Examples
- ### Example 1: Recent keyword scan over title + abstract
-
```bash
- skills/biorxiv-search/scripts/search "single cell atlas" 10 --days 30
- ```
-
- ### Example 2: Broaden with `OR`
-
- ```bash
- skills/biorxiv-search/scripts/search 'organoid OR spheroid' 15 \
- --days 90 \
- --category developmental_biology
- ```
-
- ### Example 3: Abstract-only keyword filtering
-
- ```bash
- skills/biorxiv-search/scripts/search "CRISPR screen" 10 \
- --days 60 \
- --fields abstract
- ```
+ # Recent keyword scan over title, abstract, and authors
+ scripts/search "single cell atlas" 10 --days 30
- ### Example 4: Author-specific search with separate variant reporting
+ # Synonyms with OR, one category
+ scripts/search 'organoid OR spheroid' 15 --days 90 --category developmental_biology
- ```bash
- skills/biorxiv-search/scripts/search "supernova" 20 \
- --days 365 \
- --author "Peter Nugent" \
- --author "P. Nugent"
- ```
+ # Abstract-only matching
+ scripts/search "CRISPR screen" 10 --days 60 --fields abstract
- ### Example 5: DOI lookup
+ # Author variants, reported in separate groups
+ scripts/search "supernova" 20 --days 365 --author "Peter Nugent" --author "P. Nugent"
- ```bash
- skills/biorxiv-search/scripts/search --doi 10.1101/682021
+ # DOI lookup
+ scripts/search --doi 10.1101/682021
```
## Troubleshooting
- **Issue**: Results are too broad
- **Solution**: Narrow the interval, add `--category`, restrict with `--fields`, or replace a loose query with a phrase or explicit `OR` terms.
-
- **Issue**: Results are too sparse
- **Solution**: Increase `--days` or widen the date range, raise `--scan-limit`, and add alternate query terms with explicit `OR`.
-
- **Issue**: Need abstract matches, not title matches
- **Solution**: Use `--fields abstract`.
-
- **Issue**: Author search looks incomplete
- **Solution**: Repeat `--author` with explicit variants such as `"Peter Nugent"` and `"P. Nugent"`. If a middle initial is known, add that too, for example `"Peter E. Nugent"` and `"P. E. Nugent"`. Keep these result sets separate in the final answer because abbreviated forms can be ambiguous.
-
- **Issue**: The API returns multiple versions of the same preprint
- **Solution**: Keep the default deduped output, or pass `--all-versions` if version-level output matters.
+ **Issue**: Results are too broad.
+ **Solution**: Shorten the interval, add `--category`, restrict `--fields`, or use a phrase.
- **Issue**: Broad historical search may be missing expected hits
- **Solution**: This usually means the interval or `--scan-limit` was too narrow. Widen them deliberately and say so in the final answer.
+ **Issue**: Results are sparse or a known preprint is missing.
+ **Solution**: Widen the interval, raise `--scan-limit`, add `OR` synonyms, and state the change in the answer.
- **Issue**: Need peer-reviewed literature rather than preprints
- **Solution**: Use `polars-dovmed` or another peer-reviewed-literature workflow instead of bioRxiv metadata search.
+ **Issue**: Author results look incomplete.
+ **Solution**: Add more `--author` variants, such as a middle initial (`"Peter E. Nugent"`, `"P. E. Nugent"`), and keep each group separate.
## Related Skills
- - `/crossref-lookup` — resolve citation metadata from bioRxiv DOIs
- - `/polars-dovmed` — switch here if the query wants peer-reviewed PMC full text instead of preprints
+ - `/crossref-lookup`: citation metadata for bioRxiv DOIs
+ - `/arxiv-search`: arXiv preprints
+ - `/polars-dovmed`: peer-reviewed PMC full text and bioRxiv full text