II-Commons Retrieval Skill
Gives AI agents deterministic, daily-updated search over arXiv, PubMed/PMC, and US state policy corpora via a CLI that returns reproducible JSON.
Evidence shows least privilege (only outbound network to commons.ii.inc, local config reads), explicit claim that the client never prints token values, tokens via env or XDG config, no file writes or external side effects; deducted for: opaque data flow into a remote closed-source service, npx supply-chain surface, implicit invocation (allow_implicit_invocation: true) without user confirmation, and no rollback guidance.
Script is self-consistent with strict arg validation, machine-readable JSON errors and non-zero exits; the repo ships a test suite covering parsing, retries, timeouts, 401/429 and config loading; deducted because static review cannot execute anything, no committed CI workflow proves tests actually pass, and server-side behavior is not independently reproduced.
Corpus boundaries, routing rules, date-filter mapping and cutoff-based freshness rules are clearly written, with declared non-fit ranges (policy limited to CA/TX/WA); deducted for total dependence on the overseas service commons.ii.inc with no mainland-China reachability statement, no Chinese-language support, and implicit-invocation false-trigger risk.
Well-layered docs (SKILL.md routing plus api.md contract), npm publish config, Apache-2.0 license, Node>=18 engines; deducted for no CHANGELOG or version history evidence, maintenance responsibility and update cadence only implied by repo links, and unverified publisher identity.
Deterministic CLI retrieval offers marginal value over manual arXiv/PubMed searches, structured JSON output is directly usable, and the markdown-to-meta/PDF fallback anticipates real failures; deducted because static review cannot verify retrieval quality or result correctness, and no executed representative outputs exist.
The committed test suite is auditable primary material, and docs/code contracts (endpoints, error codes) cross-check consistently; deducted for the absence of CI workflows, third-party execution evidence, or independent reproduction — the multi-source corroboration needed above 5 is not met.
- Core function depends entirely on the overseas service commons.ii.inc with no mainland-China reachability disclosure; verify connectivity first, otherwise the skill is effectively unusable.
- openai.yaml allows implicit invocation, which may trigger network retrieval when it should not; prefer explicit invocation in sensitive environments.
- This is static review with nothing executed; the npx install path carries supply-chain risk — pin an audited version rather than always pulling latest.
- No CHANGELOG or CI evidence; version governance and test-pass status are not independently verified.
What does this skill do, and when should you use it?
II-Commons is an agent skill and CLI from Intelligent-Internet, powered by the PostgreSQL BM25S extension psql_bm25s, providing fast lexical retrieval over arXiv, PubMed/PMC, and California, Texas, and Washington policy texts. Coverage is updated daily, and the `cutoff` command reports the latest coverage date per corpus. It supports server-side filtering by date, category, journal, and jurisdiction, and can convert matched documents to full-document Markdown. Basic usage works without authentication; higher limits require an API token from commons.ii.inc.
When installed it provides a Node.js CLI named ii-commons (also runnable via npx @intelligentinternet/ii-commons, or installable as an agent skill via skills/ii-commons/SKILL.md). Core commands: search <corpus> <topic> [filters] runs deterministic search across the arxiv/pubmed/policy corpora with --start/--end (integer formats like YYYYMMDD), --categories, --jurisdictions, and --max-results filters; meta looks up metadata by canonical identifier (e.g. arXiv:2402.03578, PMCID:PMC11152602, DOI:<doi>); markdown fetches and converts full documents to Markdown; cutoff returns the latest coverage date per corpus. Output is JSON on stdout; errors are machine-readable JSON on stderr with a non-zero exit code.
- AI/ML researchers doing literature reviews who want an agent to search arXiv preprints filtered by date range and category, e.g. retrieval-augmented generation papers from the last two years.
- Biomedical or clinical researchers asking agents about drugs, trials, or public health, with PubMed/PMC search plus full-text Markdown for quote-level grounding.
- Legal and compliance professionals comparing California, Texas, and Washington policy or legal texts, such as overtime rules for agricultural workers.
- Freshness-sensitive users who run `cutoff` first to confirm each corpus's coverage boundary before trusting results.
- Cross-domain investigators who search multiple corpora for one question and compare results explicitly.
What are this skill's strengths and limitations?
- Deterministic, reproducible retrieval flow: search/meta/markdown/cutoff have well-defined behavior and structured JSON output that agents can process programmatically.
- Daily-updated data with a `cutoff` command that gives a citable freshness boundary — good for time-sensitive research tasks.
- Server-side date, category, journal, and jurisdiction filters avoid broad searches followed by manual screening.
- Works without authentication for basic use; portable CLI needing only Node.js 18+ and network access.
- One command interface spans three heterogeneous corpora: academic preprints, biomedical literature, and US state policy.
- Policy corpus covers only California, Texas, and Washington — other jurisdictions are out of scope.
- Depends on the availability of the external service commons.ii.inc; the source gives no SLA or long-term availability guarantees.
- Basic usage has limits; higher limits require an API token whose specific quota values are not stated in the source.
- No test suite, platform testing evidence, or retrieval quality benchmarks are provided in the source — evaluate fit yourself.
- Markdown conversion can occasionally return truncated or damaged documents (SKILL.md provides a fallback path), so full-text extraction is not guaranteed.
How do you install this skill?
Option 1: run without installing — npx @intelligentinternet/ii-commons --help; or install globally — npm install -g @intelligentinternet/ii-commons (requires Node.js 18+). Option 2: install as an agent skill by placing the repository's skills/ii-commons/ folder into your agent runtime's native skill discovery path (or point a repository-URL install at skills/ii-commons/); the skill name is ii-commons. Source repo: https://github.com/Intelligent-Internet/II-Commons-Skills . Outbound access to commons.ii.inc is required.
How do you use this skill?
Tell your agent: "Please use the ii-commons skill to answer this: <your question or topic>". Direct CLI examples: ii-commons cutoff for latest corpus coverage; ii-commons search arxiv "large language model inference" --max-results 10; ii-commons search pubmed "type 2 diabetes review" --start 20240000 --max-results 10; ii-commons search policy "state overtime rule for agricultural workers" --jurisdictions US-CA --max-results 10; ii-commons meta "arXiv:2402.03578"; ii-commons markdown "PMCID:PMC11152602". When running from an installed skill directory, use node scripts/ii_commons.js instead of ii-commons. If markdown returns a truncation/damage error, SKILL.md advises calling meta for the same identifier and continuing from the PDF URL. The REST client contract is documented in references/api.md in the repo.