oma-scholar

Scholarly research companion using Knows sidecar spec (.knows.yaml). Generates, validates, reviews, queries, and compares structured research-paper sidecars, and fetches them from knows.academy. Use for academic literature search, survey synthesis, paper authoring assistance, and peer review with token-efficient claim/evidence/relation access.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

85%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

Highly actionable and well-sequenced content with concrete commands and explicit validation/feedback loops. It is let down by progressive disclosure: the referenced bundle files do not exist on disk, and material that belongs in separate files is inlined.

Suggestions

Create the referenced resources/ files (execution-protocol.md, sidecar-spec.md, api-endpoints.md, setup-openalex.md, upstream-spec-cache.md, checklist.md) or remove the dangling references so navigation resolves.

Move the 18-rule guardrail list and the raw-API curl block into dedicated referenced files, keeping only the most load-bearing rules inline in SKILL.md.

Trim the troubleshooting table to the highest-frequency errors and point to a resource for the full catalog to reduce inline token weight.

Dimension	Reasoning	Score
Conciseness	Dense and assumes Claude's intelligence (no explaining YAML/DOI/PDF), but ~275 lines inline substantial reference material (18-rule guardrail list, raw curl API block, full troubleshooting table) that could be trimmed or moved to referenced files.	4 / 5
Actionability	Copy-paste-ready CLI commands with real arguments across all six modes ("oma scholar get --section statements", "10.48550/arXiv.1706.03762") plus curl fallbacks and an exact-error-to-fix troubleshooting table.	5 / 5
Workflow Clarity	Numbered Entry/Scenes/Transitions/Failure-and-recovery/Exit flow with an explicit VALIDATE scene, lint-after-generate guardrail, and feedback loops (API timeout -> OpenAlex fallback; YAML parse -> fix; relation warning -> add relations).	5 / 5
Progressive Disclosure	A References section lists one-level-deep resources/ files, but no resources/, references/, scripts/, or assets/ directory exists, so every reference is a dangling pointer; meanwhile bulk content (guardrails, troubleshooting, raw API) is inlined rather than split out.	3 / 5
	Total	17 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, specific description that names concrete actions, gives explicit 'Use for...' triggers, and stakes out a clearly distinct niche. The only soft spot is trigger-term naturalness, which leans somewhat on spec jargon over plain user phrasing.

Dimension	Reasoning	Score
Specificity	Enumerates five concrete actions ("Generates, validates, reviews, queries, and compares... sidecars, and fetches them from knows.academy") covering the full mode surface with no gaps.	5 / 5
Completeness	Explicitly answers both what (the six sidecar operations) and when ("Use for academic literature search, survey synthesis, paper authoring assistance, and peer review...") with concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes natural phrases users would say ("academic literature search", "survey synthesis", "peer review") plus spec terms, but leans on technical jargon (.knows.yaml, knows.academy) with thin file-extension coverage rather than a comprehensive synonym list.	4 / 5
Distinctiveness Conflict Risk	Sharp niche defined by Knows/.knows.yaml/knows.academy and claim/evidence/relation framing yields minimal overlap with other skills.	5 / 5
	Total	19 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: first-fluke/oh-my-agent
Path: .agents/skills/oma-scholar/SKILL.md
Commit: 7721120

Reviewed: 2 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.