skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
first-fluke/oh-my-agent64 installs

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-scholar
view source ↗

Is 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.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, 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

  1. Identify the mode (see Modes) and the source artifact, identifier, or query. Load resources/execution-protocol.md for the selected mode, and resources/sidecar-spec.md when generating, reviewing, or fixing lint findings.
  2. 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).
  3. 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.
  4. Perform the mode's operation: extract claims, evidence, relations, and provenance to generate or review a sidecar, or analyze or compare existing sidecars.
  5. 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.
  6. 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

  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: if DOI/venue/year is not visible in source, omit the key entirely; never write doi: TODO or guess
  4. Field shapes are exact: top-level metadata, field names, closed enums, the single provenance.actor object, the confidence and coverage objects, unquoted numbers, and descriptive prefixed kebab-case IDs all follow resources/sidecar-spec.md. Copy its names and values; do not improvise variants.
  5. 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.
  6. Validate before sharing: run oma scholar lint after Generate and Review; cross-record refs (record_id#local_id) in review sidecars are recognized and not flagged as dangling
  7. Remote API has no auth: https://knows.academy/api/proxy/* is public; do not invent auth headers
  8. Partial fetch param is section (singular): fixed enum statements|evidence|relations|artifacts|citation
  9. Fallback API keys are optional: OPENALEX_API_KEY (metadata enrichment) and S2_API_KEY (Semantic Scholar dedicated rate limit) both improve throughput but the cascade degrades gracefully without them
  10. Sidecar content stays English: schema fields, IDs, statement text follow upstream convention; user-facing responses follow oma-config.yaml language
  11. 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 $schema without validation against that exact schema; see resources/canonical-delta.md.

Modes

ModeTriggerOutput
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>&section=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

IssueSolution
[ERROR] *.value: numeric value '22' is quotedRemove quotes: value: '22' -> value: 22
[ERROR] provenance.actor.type: 'ai' is not allowedChange 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 idFix 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 ≥ 8Expected when generating from abstract only; full-paper Generate should hit 15+
[WARN] *.predicate: past-tense '...' is suspiciousSwitch to present tense (evaluated_on -> evaluates_on)
Remote API returns empty resultsTry 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/429Set 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 parseCheck 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 under cli/commands/scholar/)
  • Context loading: references/_shared/core/context-loading.md
  • Quality principles: references/_shared/core/quality-principles.md
  • i18n rules: ../../rules/i18n-guide.md

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>