oma-scholar
Search academic literature and generate, validate, or compare Knows paper sidecars. Use for claim/evidence analysis and literature synthesis.
How do I install this agent skill?
npx skills add https://github.com/first-fluke/oh-my-agent --skill oma-scholarIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The oma-scholar skill is a research assistant for academic literature that allows users to search scholarly databases and generate or analyze structured paper summaries (sidecars). The skill is safe for its intended use, although it possesses a standard indirect prompt injection surface due to its core function of processing untrusted scholarly content.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 2 issues
What does this agent skill do?
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.yamlsidecars 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.yamlsidecar, review sidecar, lint report, search/fetch result, natural-language analysis, or structural comparison- Sidecars conforming to v0.9.0 /
paper@1profile - Validation status and warnings before sharing generated sidecars
Dependencies
oma scholarCLI subcommands- knows.academy public API; OpenAlex and Semantic Scholar fallbacks
resources/sidecar-spec.md, API endpoints, OpenAlex setup, canonical delta, checklist, and execution protocol
Structural Flow
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
Canonical command path
- Identify the mode (see Modes) and the source artifact, identifier, or query. Load
resources/execution-protocol.mdfor the selected mode, andresources/sidecar-spec.mdwhen generating, reviewing, or fixing lint findings. - Resolve the paper identity through Knows or OpenAlex when needed:
oma scholar search "<query>"to discover papers,oma scholar resolve "<title-or-doi>"to find one specific paper (see Provider Fallback). - Acquire the source:
oma scholar get "<record-id-or-doi>"for paper metadata or sidecar sections, or read the local paper, draft, notes, or sidecar. - Perform the mode's operation: extract claims, evidence, relations, and provenance to generate or review a sidecar, or analyze or compare existing sidecars.
- Run
oma scholar lint "<paper.knows.yaml>"on a generated, reviewed, or supplied sidecar. Check the supported local contract, IDs, relations, and provenance; report lint limitations. Full canonical conformance requires the exact schema validator. - Return the sidecar, report, summary, or comparison with caveats.
Resource scope and effects
May create local sidecar or review sidecar files ({paper}.knows.yaml, {paper}.review.knows.yaml) from user-provided paper content and research notes. The oma scholar CLI queries the public knows.academy, OpenAlex, and Semantic Scholar APIs. Does not submit sidecars back to knows.academy.
Guardrails
- Local generation targets v0.9.0 production compatibility /
paper@1(review sidecars usereview@1). This is narrower than complete canonical schema conformance; seeresources/sidecar-spec.md. - Host LLM generates sidecars: never shell out to
anthropicSDK or external LLM CLI; this skill runs inside an agent - Anti-fabrication: if DOI/venue/year is not visible in source, omit the key entirely; never write
doi: TODOor guess - Field shapes are exact: top-level metadata, field names, closed enums, the single
provenance.actorobject, theconfidenceandcoverageobjects, unquoted numbers, and descriptive prefixed kebab-case IDs all followresources/sidecar-spec.md. Copy its names and values; do not improvise variants. - Relation coverage: review the local ratio/orphan warnings; add only source-supported, type-appropriate relations. Claims with evidence use
supported_by; definitions and open questions can remain source-anchored. A ratio of 1.5 is diagnostic, not a graph-padding quota. - Validate before sharing: run
oma scholar lintafter Generate and Review; cross-record refs (record_id#local_id) in review sidecars are recognized and not flagged as dangling - Remote API has no auth:
https://knows.academy/api/proxy/*is public; do not invent auth headers - Partial fetch param is
section(singular): fixed enumstatements|evidence|relations|artifacts|citation - Fallback API keys are optional:
OPENALEX_API_KEY(metadata enrichment) andS2_API_KEY(Semantic Scholar dedicated rate limit) both improve throughput but the cascade degrades gracefully without them - Sidecar content stays English: schema fields, IDs, statement text follow upstream convention; user-facing responses follow
oma-config.yamllanguage - Contract scope: local generation rules and lint track production compatibility, not the complete canonical v0.9 schema. Preserve canonical imported shapes and report local-lint incompatibilities. Do not claim full schema compliance or add
$schemawithout validation against that exact schema; seeresources/canonical-delta.md.
Modes
| Mode | Trigger | Output |
|---|---|---|
| Generate | "create sidecar from this paper / abstract / draft", "generate .knows.yaml" | {paper}.knows.yaml (host LLM emits, then oma scholar lint validates) |
| Validate | "lint this sidecar", "validate .knows.yaml" | Pass/fail report with file:line issues |
| Review | "peer review this paper as sidecar" | {paper}.review.knows.yaml |
| Analyze | "summarize this sidecar", "what claims does it make?" | Natural-language answer |
| Compare | "compare paper A and paper B structurally" | Diff table (claims/methods/evidence) |
| Remote | "find papers on X", "fetch sidecar :id", "get claims only for :id" | Search results / sidecar payload |
Provider Fallback (knows.academy → OpenAlex → Semantic Scholar)
knows.academy currently indexes only 2026 papers (mostly arXiv). For
older or non-2026 papers (Transformer 2017, BERT 2018, classics, journals),
the skill automatically falls back to OpenAlex for metadata and abstract,
then to Semantic Scholar (AI TL;DR, citation + influential-citation
counts) when OpenAlex also has nothing. See resources/fallback-providers.md.
When OpenAlex returns the answer (knows.academy lacks the paper), use the returned abstract as input to Mode 1 Generate to produce a local sidecar. Commands are in Quick Reference below.
Quick Reference
Search (knows + auto OpenAlex fallback)
oma scholar search "diffusion super resolution"
oma scholar search --year-min 2024 "vision language action"
search returns JSON with primary (always knows.academy), fallback
(openalex, semanticscholar, or null), and results, each tagged with its
source. --always-fallback queries every tier regardless of earlier hits.
Find one specific paper
oma scholar resolve "Attention Is All You Need"
# returns top hit from each source + recommendation
Fetch a sidecar or work
# knows.academy full sidecar
oma scholar get "knows:generated/reconvla/1.0.0"
# Partial fetch (claims only, ~700 tokens, 93% reduction vs PDF)
oma scholar get --section statements "knows:generated/reconvla/1.0.0"
# By DOI or OpenAlex W-id (works regardless of knows.academy availability)
oma scholar get "10.48550/arXiv.1706.03762"
oma scholar get "W2147144213"
# Semantic Scholar: AI TL;DR + citation/influential-citation counts
oma scholar get "arXiv:1706.03762"
oma scholar get "CorpusId:13756489"
When knows.academy is unreachable, get knows:... automatically falls back
to OpenAlex by extracting the slug from the record_id. The result is marked
with fallback: "openalex" and contains metadata + abstract, useful for
running Mode 1 Generate locally.
Validate
# Strict mode for own Generate output (default)
oma scholar lint paper.knows.yaml
# Lenient mode for third-party / fetched sidecars
oma scholar lint --lenient remote.knows.yaml
# Treat warnings as failures (CI mode)
oma scholar lint --fail-on-warning paper.knows.yaml
knows.academy-served sidecars can contain dangling cross-references (a typo
in subject_ref/object_ref). Use --lenient when consuming third-party
records so these surface as warnings rather than blocking errors.
Raw API (when CLI is unavailable)
curl -s "https://knows.academy/api/proxy/search?q=..."
curl -s "https://knows.academy/api/proxy/sidecars/<encoded-id>"
curl -s "https://knows.academy/api/proxy/partial?record_id=<id>§ion=statements"
curl -s "https://knows.academy/api/proxy/jobs/stats" # platform health
Configuration
The oma scholar CLI always uses https://knows.academy and reads no config file. One key exists for raw HTTP use only: when calling the API without the CLI against a self-hosted Knows instance, take the host from scholar.base_url in .agents/oma-config.yaml, falling back to api.base_url in config/scholar-config.yaml.
Troubleshooting
| Issue | Solution |
|---|---|
[ERROR] *.value: numeric value '22' is quoted | Remove quotes: value: '22' -> value: 22 |
[ERROR] provenance.actor.type: 'ai' is not allowed | Change to tool, person, or org |
[ERROR] *.type: use \statement_type` instead of `type`` | Rename type -> statement_type (or evidence_type/predicate/artifact_type) |
[ERROR] provenance.actors: v0.9 spec uses singular \actor`` | Replace actors: [{...}] array with actor: {...} object |
[ERROR] *.object_ref: reference 'X' does not match any defined id | Fix the subject_ref/object_ref to point to a real id, OR use --lenient if consuming third-party data (cross-record record_id#local_id refs are recognized and never flagged) |
[WARN] relations: avg relations/statement is N.NN (target ≥ 1.5) | Review coverage; add only supported, type-appropriate links, never pad the graph |
[WARN] statements: only N statements; most papers warrant ≥ 8 | Expected when generating from abstract only; full-paper Generate should hit 15+ |
[WARN] *.predicate: past-tense '...' is suspicious | Switch to present tense (evaluated_on -> evaluates_on) |
| Remote API returns empty results | Try broader query; check /api/proxy/jobs/stats; CLI auto-falls-back to OpenAlex |
knows.academy search failed: fetch failed (stderr) | Platform timeout; fallback to OpenAlex is automatic; retry later for sidecars |
| OpenAlex 403/429 | Set OPENALEX_API_KEY (see resources/setup-openalex.md) |
semanticscholar error: HTTP 429 (stderr) | Anonymous pool throttled; CLI retries once then skips the source. Set S2_API_KEY (free form at semanticscholar.org/product/api) for a dedicated limit |
| YAML won't parse | Check indentation; numbers/booleans must be unquoted; strings with : need quotes |
References
- Execution steps (follow for the selected task):
resources/execution-protocol.md - Sidecar spec rules (Generate, Review, or fixing lint findings):
resources/sidecar-spec.md - Canonical vs local delta (importing or linting a third-party record, a shape local lint rejects, or any canonical-conformance statement):
resources/canonical-delta.md - API endpoints (raw HTTP without the CLI):
resources/api-endpoints.md - Provider cascade and trust notes (a paper missing from knows.academy):
resources/fallback-providers.md - OpenAlex setup (OpenAlex 403/429 or the user asks for a key):
resources/setup-openalex.md - Post-generation checklist (after Generate or Review):
resources/checklist.md - CLI subcommands:
oma scholar search|resolve|get|lint(implementation undercli/commands/scholar/) - Context loading:
references/_shared/core/context-loading.md - Quality principles:
references/_shared/core/quality-principles.md - i18n rules:
../../rules/i18n-guide.md
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/first-fluke/oh-my-agent/oma-scholar">View oma-scholar on skillZs</a>