Skip to content

xngg1021/academic-skills

v2.0.0LicenseRef-Source-Lineage-1.0

Harness-neutral academic research, statistical recompute, and multi-model deliberation skills.

GitHubOpen Website

academic-research-kernel

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Deutsch · Français · Español · Português · Русский · Bahasa Indonesia · Italiano · हिन्दी · العربية · বাংলা · اردو · Tiếng Việt · Türkçe · فارسی · Kiswahili · Polski

Harness-neutral deterministic research-state kernel for agentic research workflows. It unifies research object identity, empirical evidence receipts, tripartite claim-evidence graphs (CEG), and append-only research decision logs through a deterministic ingestion bridge and universal Model Context Protocol (MCP) server. 13 specialized scholarly skills act as producers and consumers of verified research state, with native support for Claude Code, Cursor, Codex, Gemini CLI, and Hermes Agent. Validation scope and external-service limitations are recorded in the audit.

Author: Junfu Shi (SJF, xngg1021), Hermes Agent. Current scoped offer: Source Lineage License 1.0.

Quick start

After 2.0.0 is published to PyPI, run with uv:

uvx academic-research-kernel mcp

Publication is a separate release step: check the 2.0.0 release manifest for the actual PyPI status. Before publication, download the release wheel and use uvx --from ./academic_research_kernel-2.0.0-py3-none-any.whl academic-research-kernel mcp. For a fixed product identity, use uvx academic-research-kernel@2.0.0 mcp. Python 3.10–3.14 is supported; uvx --python 3.12 explicitly selects a supported interpreter. All 12 deterministic tools, including statistics, are included in the base install.

Verify

uvx academic-research-kernel doctor
uvx academic-research-kernel --version

The offline diagnostic checks dependencies, schemas and all 12 tool definitions. Optional services can remain unconfigured. Use doctor --json for machine-readable output.

Package install

uv tool install academic-research-kernel==2.0.0
academic-research-kernel doctor
academic-research-kernel mcp

Alternatively, install with pipx install academic-research-kernel==2.0.0 or python -m pip install academic-research-kernel==2.0.0 inside a supported virtual environment. [full] adds libraries for extended scientific skill examples; [qa] adds repository validation tools. GPU backends and paid services remain optional.

Hermes

Install uv so it is on Hermes' process PATH, then install and explicitly enable the portable plugin:

hermes plugins install xngg1021/academic-research-kernel --no-enable
hermes plugins enable academic-skills

The existing academic-skills identity and all 13 skills are preserved. The plugin's mcp.json invokes uv run --frozen --no-dev --no-editable with Python 3.12 and the checkout's uv.lock; its environment lives under ${PLUGIN_DATA}/runtime. It bootstraps dependencies on first use, without borrowing Hermes' or the system's Python packages. First use needs network access to obtain missing packages/interpreter. The older skill-only tap remains supported under Integration & Portable Usage.

From source

git clone https://github.com/xngg1021/academic-research-kernel.git
cd academic-research-kernel
uv sync --frozen --no-dev --no-editable
uv run --frozen --no-dev --no-editable academic-research-kernel doctor
uv run --frozen --no-dev --no-editable python scripts/mcp_server.py

See distribution and release for dependency classification, reproduction, release identity, publication checkpoints and validation scope.

License

The snapshot containing this notice adopts Source Lineage License 1.0 for the Covered Material and rights identified in LICENSE-APPLICATION.md. The first SLL commit and tree, and the later boundary-recording commit, are distinguished in LICENSE-HISTORY.md and SOURCE-LINEAGE.md. Snapshots from that recorded transition forward retaining this notice carry the same scoped offer.

Historical snapshots through 439ce4a29d6d2d9137308d7f9f045863e9f0c5b3 were MIT-licensed, subject to the terms applicable to those copies. Recipients retain valid MIT permissions and need not migrate to SLL. The former project MIT text is preserved; tests/upstream/LICENSE and its third-party provenance remain unchanged. The new root offer does not erase those rights.

SLL broadly permits use, study, modification, commercial use, distribution and proprietary additions, subject to applicable license, notice and source-lineage conditions. It is not copyleft and requires no source disclosure. Pure network service without supplying copies does not by itself trigger the Core service-lineage notice condition. There is no express patent grant. Third-party material remains under its own terms. The exact English LICENSE controls this informational summary; LicenseRef-Source-Lineage-1.0 is a local reference, not SPDX assignment, and no OSI approval is claimed. Contribution intake is separate from downstream license permissions.

Skills

SkillVersionWhat it does
skills/academic-source-verification1.2.0Cross-check identity and source-specific citation counts; inspect update/retraction signals; locate OA text and verify PDF identity
skills/literature-analysis1.3.0Twelve workflows: topic similarity, local text overlap, counter-evidence, author profiles, mock review, fallacy checks, review matrix, journal candidates, BibTeX, bilingual reading, research-gap screening, reproduction
skills/academic-writing1.1.1Editing, citation guidance (ISO 690, APA, MLA, Chicago, IEEE, AMA, and regional profiles), journal instructions, optional detection services, submission materials, and institutional requirements
skills/math-computation1.2.1Existing domain/task routing with corrected numerical/statistical examples; four domain/advanced reference files
skills/quantitative-paper-audit1.1.0Recompute reported statistics (effect size, p values, CIs, OR/RR, achieved power) and detect numerical mismatches
skills/research-reproducibility1.0.1Fourteen-stage reproduction audit pipeline with structured verification checklists, five fact tiers, and reproducible audit records
skills/systematic-review-meta-analysis1.0.1PRISMA search logs, literature screening logs, effect-size conversion, heterogeneity, fixed/random pooling, sensitivity and publication-bias diagnostics
skills/literature-watch1.1.0Weekly blueprint: watch topics, authors and DOI citing works on OpenAlex and Crossref; deduplicate and report only new items
skills/retraction-watch1.1.0Weekly blueprint: recheck a DOI watchlist against OpenAlex is_retracted and Crossref update records (update-to signals); report only status changes
skills/research-object-identity1.1.0Deterministic research-resource identification and provenance tracking: identifier normalization, 5-state verification, content-addressed derivation graphs, causal DAG validation, and sub-100ms lineage tracing
skills/claim-evidence-graph1.0.0Deterministic scientific claim–evidence linking connecting assertions, evidence records, and computational provenance
skills/decision-ledger1.0.0Research Decision Log: deterministic, append-only log of research decisions, failed attempts (negative results), reasons for stopping routes, and outcome revisions
skills/cross-review-five2.0.0Dynamic multi-reviewer panel orchestration supporting arbitrary models/subagents (Kimi K3, DeepSeek V4 Pro, GLM 5.3, Claude, Gemini, etc.): v2 Sparse Deliberation pipeline with Kuhn-Munkres Hungarian assignment, assertion-level clustering, targeted anonymous challenge, and P0-P3 severity grading

There are 21 Markdown reference files across the thirteen skills. References load only when needed.

Scholarly Standards & Multi-Profile Baseline

Citation styles, reporting criteria, and metadata contracts depend on the target journal, institution, funder, discipline, and jurisdiction. The repository establishes ISO 690:2021 (Bibliographic references), ISO 5127:2017 (Information and documentation vocabulary), and W3C PROV (Provenance data model) as international baselines, alongside regional profiles (e.g., GB/T 7714-2025 in Mainland China, UNE-ISO 690:2024 in Spain, DIN ISO 690:2021 in Germany) and disciplinary standards (APA 7th, IEEE, ACM, Vancouver, Chicago, PRISMA 2020, ICMJE). Target venue requirements take precedence over default profiles. See the Scholarly Standards Architecture and Natural Terminology Guide.

The final PR #12 repair validates DOI/identifier coherence, inverse quantitative verdict flags, and the shared kernel/receipt uncertainty contract. Cache completeness is reconstructed from retained source envelopes and normalized bindings, independently of the receipt's mutation lists; removing both a record and its cache declaration cannot produce an accepted replay. See the four-blocker closeout.

Integration & Portable Usage

1. Universal Agent Plugins v1 & Model Context Protocol (MCP)

This repository conforms to the vendor-neutral Agent Plugins v1 specification (plugin.json) and exposes core academic verification and statistical recompute tools via a stdio MCP server (mcp.json / scripts/mcp_server.py). Compatible with Claude Code, Cursor, Gemini CLI, and any modern agent framework. (Note: While the repository identity is academic-research-kernel, the plugin manifest name academic-skills and MCP configuration aliases remain stable for backward compatibility.)

# Add as stdio MCP server in your agent harness
uvx academic-research-kernel mcp

2. Native Hermes Installation

From a Hermes installation:

hermes skills tap add xngg1021/academic-research-kernel
hermes skills search academic-source-verification
hermes skills install xngg1021/academic-research-kernel/skills/academic-source-verification

Install the others by substituting their directory name in the full identifier. A normal tap reads the default branch, so the skill set above is what a fresh tap installs. To inspect a work branch before merge, check out that branch locally and follow the installed Hermes version's local-folder installation instructions. Do not assume the tap command selects a PR branch.

Bundled related skills checked at upstream 245e48008fa814b3251f50755eb656bd9fb86cb1: arxiv, grounded-citations, docx, pdf, manim-video. huggingface-hub and llama-cpp are in the optional catalog and may need installation. ocr-and-documents and pc-hardware-benchmark were not found in that snapshot and are not dependencies. Session tools and document/browser backends depend on local configuration.

Data-source access

  • OpenAlex basic queries can run anonymously with a smaller daily budget. On 2026-09-06 current docs specify $0.10/day anonymous and $1/day with a free API key, plus a 100 requests/second ceiling. Costs differ by query type; this is not unlimited access. Store an optional key in OPENALEX_API_KEY. Use per_page (maximum 100) and cursor pagination.
  • Crossref has public metadata access with throttling. Update relationships and Retraction Watch signals require DOI/direction checks; missing records do not prove a paper is unaffected.
  • Unpaywall requires a real contact email in UNPAYWALL_EMAIL. An absent location does not prove that no OA copy exists.
  • arXiv, Europe PMC, PubMed E-utilities and DOAJ are supplementary sources with their own policies. They are not all exercised by default tests. Semantic Scholar has shared anonymous limits and separately assigned key limits; access does not guarantee citation-context availability.
  • Scite, Dimensions, Scopus, Web of Science and AI-detection products are optional external services. Check current account/API entitlements and quotas before use; no universal free tier or fixed price is promised.

See OpenAlex authentication, budgets/query costs, and Crossref update filters.

Deterministic ingestion and public kernel

PR #12 provides ResearchArtifactEnvelope v1, ArtifactIngestionReceipt v1, 14 adapters (the 13 skills plus opaque fallback), and 12 stateless stdio MCP tools. Accepted ingestion receipts bind each retained semantic mutation by kind, identity and canonical SHA-256: objects, CEG records, ledger records, uncertainties, physical receipts and artifact registrations. Cache replay checks those commitments independently of transport snapshot hashes. Empty ledgers are valid; failed atomic batches leave no partial state.

Lineage content authority is explicit and out of band. Trusted Python callers pass LineageVerificationContext when replaying serialized receipts or snapshots; MCP callers may supply bounded content bytes, never a host filesystem root. The default content budget is 10 MiB; a trusted host may explicitly authorize larger artifacts under the same producer/verifier policy. Without content authority, a fully_verified claim cannot be independently reproduced and returns a structured invalid verification result. Opaque prose stays opaque, dissent stays visible, and researchers retain control of commits, pruning, reopening, routing and truth judgments.

See the architecture for contracts and compatibility. Distribution and publication checkpoints are recorded in the release guide. English and Simplified Chinese README are current; other translation states remain explicit in the manifest. Final candidate identity, exact-head CI, cumulative review and merge evidence are recorded in the closeout ledger.

Validation

Use a dedicated Python environment. Runtime libraries are task-specific, not guaranteed installed in Hermes. QA dependencies are broader so all marked examples can run:

python -m pip install -r requirements-qa.txt
python -m pip install 'torch>=2.5,<3' --index-url https://download.pytorch.org/whl/cpu
python scripts/qa.py
python -m pytest -q tests
python scripts/verify_external_apis.py
git diff --check

QA validates metadata, references, personal-path/known-secret patterns, Python syntax and marked executable fences. Each smoke example runs unchanged in a fresh subprocess. Plot examples accept PLOT_DIR (default ~/plots, explicitly expanded); tests use a temporary directory. Unclassified Python fences are rejected; fragment: blocks are syntax-checked but require named inputs and are not executed standalone. external-test: blocks run only via the manual external command. It returns 0 on passed configured checks, 1 on code/schema/identity failure, and 2 on transport/authentication/quota unavailability; optional unconfigured services remain SKIP.

Pinned Hermes authoring tests are reused without changing their per-skill rules. Upstream whole-distribution population checks do not apply to this tap; our harness checks thirteen skills and resolves references against the pinned bundled/optional catalog. This is not a complete Hermes installation test. CI uses network only to install dependencies; ordinary PR tests do not call scholarly APIs.

CI runs the full QA suite across Linux x86_64 (Python 3.10-3.14), Linux ARM64 (ubuntu-24.04-arm), Ubuntu 26.04 preview canary (ubuntu-26.04 & ubuntu-26.04-arm), Windows x86_64, Windows ARM64 (windows-11-arm), macOS ARM64 (macos-latest), and macOS Intel (macos-15-intel), with live upstream canary validation. The final candidate passed 974 local tests with zero skips; exact-head remote results are recorded separately in the closeout ledger. A separate tap integration workflow runs on pushes to main: it installs the pinned Hermes checkout recorded in tests/upstream/provenance.json and exercises tap add, search, install and list against this repository. Exact versions, checks and limitations are in the audit.

tools/longtail/ holds the deterministic long-tail factor generator: 4096 SHA256-seeded candidates, 30 selected scenarios and a machine-computed coverage report. The v3 model separately counts capability families (E01), the 13 actual repository skills (E02), and task goals (E03). Each scenario has one primary skill, a supported task goal and compatible capabilities; every skill must appear at least twice under two distinct goals, including its declared core goal. Skill-directory drift fails validation. Semantic expansion (task chains, oracles and executed event injection) remains a separate stage; factor coverage does not prove workflow execution coverage.

scripts/scfabric/ is the scientific compute fabric: hardware probe, backend catalog with dtype gates, five workload profiles, paired benchmark with parity admission, and ComputeReceipt. First-round measurements on this machine are in docs/scientific-compute-fabric.md; the rule of thumb is CPU by default, accelerator only with a receipt.

Research and planning documents

These two documents are exploratory planning references, not a binding roadmap. Their direction numbers are recomputed from the stored grouping in docs/direction-primitive-mapping.json.