gracefullight/pkgs / .agents/skills/oma-scholar
oma-scholar
UnverifiedSearch academic literature and generate, validate, or compare Knows paper sidecars. Use for claim/evidence analysis and literature synthesis.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.2 KB |
| config/scholar-config.yaml | config | 2.7 KB |
| resources/api-endpoints.md | markdown | 4.7 KB |
| resources/checklist.md | markdown | 3.8 KB |
| resources/execution-protocol.md | markdown | 9.0 KB |
| resources/fallback-providers.md | markdown | 6.0 KB |
| resources/setup-openalex.md | markdown | 2.5 KB |
| resources/sidecar-spec.md | markdown | 10.8 KB |
| resources/upstream-spec-cache.md | markdown | 43.7 KB |
resources/fallback-providers.md
View on GitHub# Fallback Provider Cascade
`oma-scholar` queries `knows.academy` first, then falls back to OpenAlex, then
Semantic Scholar for records the platform doesn't have. The fallback is what
makes the skill useful beyond the (currently 2026-only) knows.academy index.
## Coverage Matrix
| Source | Coverage | Gives | Doesn't give |
|--------|----------|-------|--------------|
| **knows.academy** | **2026 only**, mostly arXiv (verified empirically; current counts via `/api/proxy/jobs/stats`) | Full v0.9 sidecar (claims, evidence, relations, methods) | Pre-2026 papers, full text |
| **OpenAlex** | ~240M works, all years | Title, authors, year, venue, DOI, abstract (reconstructed), OA PDF URL, citation count, references | Structured claims/evidence (no sidecar) |
| **Semantic Scholar** | ~214M papers, all years (Ai2) | AI TL;DR, abstract (verbatim), citation + influential-citation counts, arXiv/DOI/CorpusId cross-ids, OA PDF URL | Structured claims/evidence; anonymous access 429s under load |
When a paper is in **both**, prefer knows.academy (richer structure). When a
paper is **only in OpenAlex** (most pre-2026 work), use OpenAlex metadata as
the source for **Mode 1 Generate**, where the host LLM produces a local sidecar from
the abstract.
## Cascade Logic
```
search "query"
│
├─ knows.academy ── any hits? ──► return immediately (sidecars available)
│ │
│ no hits
│ ▼
├─ openalex ──── any hits? ────► return metadata + abstract (no sidecar)
│ │
│ no hits
│ ▼
└─ semanticscholar ───────────► return metadata + TL;DR + citations
↓
user wants deeper? → Mode 1 Generate locally
```
`--always-fallback` includes every tier regardless of earlier hits.
## CLI Reference (`oma scholar`)
### Search both sources
```bash
oma scholar search "vision language action"
```
Returns JSON with:
- `primary`: which source returned hits
- `fallback`: which source was used as fallback (if any)
- `results`: unified list with `source: "knows.academy" | "openalex"` per item
### Get a specific record
```bash
# knows.academy sidecar
oma scholar get "knows:generated/reconvla/1.0.0"
# Partial fetch (saves up to 93% tokens)
oma scholar get --section statements "knows:generated/reconvla/1.0.0"
# OpenAlex by DOI
oma scholar get "10.48550/arXiv.1706.03762"
# OpenAlex by W-id
oma scholar get "W2147144213"
# Semantic Scholar: TL;DR + citation/influential-citation counts
oma scholar get "arXiv:1706.03762"
oma scholar get "CorpusId:13756489"
```
When `oma scholar get` is asked for a `knows:...` id and the platform is
unreachable, the command extracts the slug from the record_id and searches
OpenAlex for the same paper, returning metadata with a `fallback: "openalex"`
marker. The user can then run **Mode 1 Generate** from the abstract.
### Resolve a title across all sources
```bash
oma scholar resolve "Attention Is All You Need"
```
Returns the best match from each source (knows.academy, OpenAlex, Semantic
Scholar) side-by-side, plus a recommendation.
## When Fallback is Needed
Fallback to OpenAlex is the right move when:
- **Pre-2026 papers**: knows.academy doesn't index them
- **Cross-archive coverage**: non-arXiv venues, journals, books
- **Citation counts**: knows.academy doesn't track citations; OpenAlex does
- **Reference resolution**: when a sidecar's `cites` predicate points to a paper not in knows.academy
Fallback is NOT needed for:
- Recent (2026) arXiv papers, since knows.academy has them with rich sidecars
- Full-text reading, since neither source provides full text; fetch the OA PDF and use `oma-pdf`
## Local Generate from Fallback Result
When OpenAlex returns metadata + abstract, but you want a structured sidecar:
```
1. oma scholar get <doi> → get title, authors, year, venue, abstract
2. (optional) download OA PDF → oma-pdf to extract full text
3. Mode 1 Generate → host LLM produces .knows.yaml using sidecar-spec.md
4. oma scholar lint → validate locally
```
The locally-generated sidecar is **not registered** with knows.academy; it's
yours. If you want it shared, that's a separate publishing flow (out of scope
for this skill).
## Authentication
OpenAlex anonymous use is free up to ~$1/day. For higher limits or polite
pool access, see `setup-openalex.md`. The skill works without any key.
`oma scholar` reads:
- `OPENALEX_API_KEY`: passed as `?api_key=` (recommended)
- `OPENALEX_EMAIL`: passed as `?mailto=` (polite pool, no signup)
- `S2_API_KEY`: Semantic Scholar key, passed as the `x-api-key` header
None are required. Without `S2_API_KEY`, Semantic Scholar uses the shared
anonymous pool, which 429s under load; the CLI retries once after a short
delay, then skips the source. Request a free key via the form at
https://www.semanticscholar.org/product/api (delivered by email; grants a
dedicated 1 req/sec).
## Trust Considerations
- **knows.academy sidecars are AI-generated**: all have `provenance.origin: machine`. Verified `lint_passed: true` is platform-internal; our local `oma scholar lint` finds dangling refs in ~47% (use `--lenient` when consuming)
- **OpenAlex metadata is curated**: generally reliable for title/authors/DOI/year, but venue and abstract can be missing for older works
- **Reconstructed abstracts** from OpenAlex's inverted index are exact (no paraphrasing), but punctuation/formatting may be lossy
- **Semantic Scholar TL;DRs are AI-generated** (Ai2's TLDR model): good `summary` seeds for Mode 1 Generate, but verify against the abstract before citing; citation counts differ from OpenAlex's (different corpora)
## Limitations
- arXiv-only papers without DOI may show `doi: None` in OpenAlex
- Some 2026 papers exist in both sources with slightly different titles; `resolve` does case-insensitive contain matching as a heuristic
- knows.academy proxy can timeout under load; fallback to OpenAlex is automatic
- OpenAlex rate-limits: respect ~10 req/sec courtesy limit
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |