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/api-endpoints.md
View on GitHub# knows.academy API Endpoints
Base URL: `https://knows.academy`
All endpoints are public proxies. **No authentication required**, so do not invent or send `Authorization` headers.
## Search
```
GET /api/proxy/search?q={query}
GET /api/proxy/search?q={query}&discipline={field}
```
```bash
curl -s "https://knows.academy/api/proxy/search?q=diffusion+super+resolution"
```
Response shape (verified):
```json
{
"results": [
{
"record_id": "knows:generated/{slug}/{version}",
"profile": "paper@1",
"title": "...",
"summary": "...",
"venue": "...",
"year": 2026,
"discipline": null,
"keywords": [],
"coverage_statements": "exhaustive",
"coverage_evidence": "key_evidence_only",
"provenance_origin": "machine",
"provenance_actor_name": "knows-gen",
"version_record": "1.0.0",
"lint_passed": true,
"download_count": 0,
"created_at": "...",
"stats": {...}
}
]
}
```
`record_id` format: `knows:generated/{slug}/{version}` includes colons and slashes that **must be URL-encoded** when used as a path/query param.
## Fetch Full Sidecar
```
GET /api/proxy/sidecars/{record_id}
```
The full v0.9.0 record (~22 KB / ~4.5K tokens, 55% smaller than the source PDF).
```bash
RID=$(python3 -c "import urllib.parse; print(urllib.parse.quote('knows:generated/{slug}/1.0.0', safe=''))")
curl -s "https://knows.academy/api/proxy/sidecars/${RID}"
```
## Partial Fetch (Token-Saving)
```
GET /api/proxy/partial?record_id={id}§ion={one_of}
```
Note: parameter is **`section` (singular)**, value must match `^(statements|evidence|relations|artifacts|citation)$`.
Available sections (verified):
- `statements` (typically ~700 tokens, 93% reduction vs full PDF)
- `evidence`
- `relations`
- `artifacts`
- `citation`
**Not available** via partial fetch: `methods` (statement_type), `provenance`. Fetch the full sidecar instead.
```bash
RID=$(python3 -c "import urllib.parse; print(urllib.parse.quote('knows:generated/{slug}/1.0.0', safe=''))")
# Just the claims
curl -s "https://knows.academy/api/proxy/partial?record_id=${RID}§ion=statements"
# Evidence only
curl -s "https://knows.academy/api/proxy/partial?record_id=${RID}§ion=evidence"
```
Response shape:
```json
{
"record_id": "...",
"items": [...]
}
```
**When to use partial vs full:**
- "What claims does this paper make?" -> `section=statements` only
- "What experiments?" -> `section=evidence`
- "What does it cite?" -> `section=citation` (or `section=artifacts` filtered by `role: cited`)
- Multi-section analysis -> fetch full sidecar (cheaper than 3 partial calls)
## Platform Stats
```
GET /api/proxy/jobs/stats
```
```bash
curl -s "https://knows.academy/api/proxy/jobs/stats"
```
Returns processing queue health (response shape verified; values are a point-in-time example):
```json
{
"pending": 10735,
"running": 288,
"completed": 37897,
"failed": 1243,
"skipped": 433,
"total": 50596
}
```
Use this for:
- Health check before bulk operations
- Estimating coverage ("how many papers are in the index?")
- Diagnosing slow responses
## Skill Self-Description
```
GET /api/proxy/skill/knows.md
```
The canonical generation guide (natural language, slightly different from the JSON Schema). Refresh `upstream-spec-cache.md` from here.
## JSON Schema (Reference)
Schema id used by sidecars: `https://knows.dev/schema/record-0.9.json`
The host `knows.dev` is currently unreachable (HTTPS times out as of 2026-04-25), so schema cannot be fetched directly. The `oma scholar lint` subcommand implements rules empirically derived from production records.
## Rate Limiting
No hard limits documented. Be polite:
- Avoid bursting more than ~10 req/sec
- Cache responses locally for repeated queries within a session
- Prefer partial fetch over full when possible
## Error Handling
| Status | Meaning | Recovery |
|--------|---------|----------|
| 404 | record_id not found | Verify ID via `/search`; the record may not be sidecared yet |
| 422 | Validation error (bad params) | Check `section` value against the allowed enum |
| 5xx | Platform issue | Retry once; check `/jobs/stats` |
| Timeout | Network / slow response | Retry with longer timeout; fall back to local sidecar if cached |
## URL Encoding
`record_id` contains `:` and `/`, so always URL-encode when placing in a path or query parameter. Examples:
```bash
# Bash with python3
RID=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$RAW_RID', safe=''))")
# Or with jq
echo -n "$RAW_RID" | jq -sRr @uri
```
## Notes
- Endpoints starting with `/api/proxy/` are stable public routes
- Direct (non-proxy) endpoints may exist but are not contract-stable; do not rely on them
- This skill **only consumes** the API. Submission/upload is out of scope
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 |