/oma-scholar

name: oma-scholar
description: Search academic literature and generate, validate, or compare Knows
  paper sidecars. Use for claim/evidence analysis and literature synthesis.

Scholar - Research Paper Sidecar Companion

Scheduling

Goal

Search, fetch, generate, validate, analyze, review, and compare scholarly paper sidecars using the Knows `.knows.yaml` spec for token-efficient research workflows.

Intent signature

• User asks for academic literature search, sidecar generation, sidecar validation, paper claims/evidence summary, structural paper comparison, or peer review as sidecar.
• User references Knows, `.knows.yaml`, knows.academy, OpenAlex, claims, evidence, relations, or paper sidecars.

When to use

• Reading research papers token-efficiently via Knows sidecars (~700 tokens for claims-only vs ~10K for full PDF)
• Generating `.knows.yaml` sidecars from your own paper drafts, LaTeX, or research notes
• Validating sidecar structure (rule-based) before sharing
• Producing peer reviews as sidecars
• Querying or summarizing existing sidecars
• Structurally comparing two papers (claims, methods, evidence)
• Searching/fetching sidecars from `knows.academy` (2026 papers only; current counts via `/api/proxy/jobs/stats`)

When NOT to use

• General web search or non-academic content -> use `oma-search`
• Translating papers -> use `oma-translation`
• PDF parsing only (no sidecar) -> use `oma-pdf`
• Submitting sidecars back to knows.academy -> out of scope (host LLM only consumes/produces locally)
• Full peer-review workflow with editor system -> out of scope

Expected inputs

• Paper, abstract, draft, LaTeX, research notes, sidecar file, DOI, OpenAlex ID, Knows record ID, or search query
• Desired mode: generate, validate, review, analyze, compare, or remote fetch
• Optional strictness, section filter, or CI behavior

Expected outputs

• `.knows.yaml` sidecar, review sidecar, lint report, search/fetch result, natural-language analysis, or structural comparison
• Sidecars conforming to v0.9.0 / `paper@1` profile
• Validation status and warnings before sharing generated sidecars

Dependencies

• `oma scholar` CLI subcommands
• knows.academy public API; OpenAlex and Semantic Scholar fallbacks
• `resources/sidecar-spec.md`, API endpoints, OpenAlex setup, upstream cache, checklist, and execution protocol

Control-flow features

• Branches by mode, source availability, Knows/OpenAlex coverage, strict vs lenient validation, and fetched section
• Reads/writes YAML sidecars and may call public APIs
• Avoids fabrication when source evidence is missing

Structural Flow

Entry

1. Identify mode and source artifact/query. 2. Resolve paper identity through Knows or OpenAlex when needed. 3. Load sidecar spec and mode-specific protocol.

Scenes

1. **PREPARE**: Select mode and gather source or remote identifiers. 2. **ACQUIRE**: Fetch paper metadata, sidecar sections, or local source text. 3. **REASON**: Extract claims, evidence, relations, provenance, or comparison structure. 4. **ACT**: Generate, lint, review, analyze, compare, or fetch sidecar data. 5. **VERIFY**: Check the supported local contract, IDs, relations, and provenance; report lint limitations. Full canonical conformance requires the exact schema validator. 6. **FINALIZE**: Return sidecar, report, summary, or comparison with caveats.

Transitions

• If knows.academy lacks the paper, fall back to OpenAlex metadata/abstract.
• If generating a sidecar, run lint before sharing.
• If consuming third-party sidecars with dangling references, use lenient mode when appropriate.
• If source evidence is absent, omit fields instead of guessing.

Failure and recovery

• If remote API times out, retry or use OpenAlex fallback.
• If YAML fails parsing, fix indentation and scalar types.
• If relation density or orphan statements warn, review coverage and type-appropriate links. Preserve source-anchored questions/definitions; never add unsupported relations to satisfy a quota.

Exit

• Success: requested sidecar operation completes with validation status.
• Partial success: missing metadata, fallback source, or validation warnings are explicit.

Logical Operations

Actions

| Action | SSL primitive | Evidence | |--------|---------------|----------| | Select mode | `SELECT` | Generate/Validate/Review/Analyze/Compare/Remote | | Read paper or sidecar | `READ` | Source files or YAML | | Request remote data | `REQUEST` | Knows/OpenAlex APIs | | Infer claims/evidence/relations | `INFER` | Sidecar generation/analysis | | Write sidecar | `WRITE` | `.knows.yaml` outputs | | Validate sidecar | `VALIDATE` | `oma scholar lint` | | Report result | `NOTIFY` | Summary or lint report |

Tools and instruments

• `oma scholar search|resolve|get|lint`
• Knows public API, OpenAlex fallback, sidecar spec, checklist

Canonical command path

oma scholar search "<query>"
oma scholar resolve "<title-or-doi>"
oma scholar get "<record-id-or-doi>"
oma scholar lint "<paper.knows.yaml>"

Resource scope

| Scope | Resource target | |-------|-----------------| | `LOCAL_FS` | Paper drafts, sidecar YAML, review sidecars | | `NETWORK` | knows.academy and OpenAlex APIs | | `PROCESS` | `oma scholar` CLI and lint | | `USER_DATA` | User-provided paper content and research notes |

Preconditions

• Mode and source are identifiable.
• Spec rules are available for generation or validation.

Effects and side effects

• May create local sidecar or review sidecar files.
• May query public scholarly APIs.
• Does not submit sidecars back to knows.academy.

Guardrails

1. **Local generation targets v0.9.0 production compatibility / `paper@1`** (review sidecars use `review@1`). This is narrower than complete canonical schema conformance; see `resources/sidecar-spec.md`. 2. **Host LLM generates sidecars**: never shell out to `anthropic` SDK or external LLM CLI; this skill runs inside an agent 3. **Anti-fabrication*