SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsscipilot-cite-skill

scipilot-cite-skill

General & other

View repository

Updated 10-15 22:12

About this skill

SciPilot-cite-skill — Automated academic literature search and citation insertion

Member of the SciPilot Skills family | Your citation co-pilot

Overview

SciPilot-cite automatically searches for real, verifiable academic literature and inserts it into the user's paper. All literature must come from real search results from academic database APIs; fabricating or inventing any literature information is strictly prohibited.

IRON RULES (inviolable iron rules)

  1. Authenticity iron rule: Every cited reference must be verified via DOI or cross-confirmed by at least two independent academic databases. Fabricating any paper title, author, journal, year, or DOI is absolutely not allowed. If the authenticity of a reference cannot be verified, it must be discarded; better to have none than to include something questionable.
  2. Order iron rule: Citation numbers must strictly follow the order of first appearance in the main text, incrementing from [1]. The order of the References list must be completely consistent with the citation numbers in the main text. Any number skipping, duplication, or out-of-order numbering is a serious error.
  3. Recency iron rule: By default, only literature from the past 5 years is searched (the user may customize this). The publication year of each reference must be within the allowed range; outdated literature is automatically excluded.
  4. Quality iron rule: Prioritize literature with high citation counts published in well-known journals/conferences. Preprints (arXiv, etc.) are included only when the user explicitly permits it.
  5. Format consistency iron rule: All citations in the same paper must use exactly the same formatting standard; mixing different citation styles is not allowed.
  6. Non-destruction iron rule: When inserting citations, no original content of the paper (text, figures, tables, formulas, etc.) may be modified; only citation markers and a References section may be added in appropriate places.
  7. Evidence ledger iron rule: Everysinglereference in the final bibliography must have a corresponding verification_log.jsonl entry in the paper_id of the working directory, and verdict ∈ {VERIFIED, LIKELY_REAL}. Stage 7 must run scripts/audit_no_hallucination.py to perform a final 100% re-verification + reconciliation with the logs,and only if audit returns PASS may it be delivered; any FAIL must interrupt, report suspected hallucinated entries to the user, and must not "from impression" add any paper that has not been verified by the script.

Trigger conditions

Activate when the user's intent involves any of the following scenarios:

  • Add/supplement references for a paper
  • Search for academic papers on a specific topic
  • Insert citation markers in a paper
  • Format an existing reference list
  • The user uploaded a .docx or .tex file and mentioned "citation", "reference", "citation", or "reference"
  • The user mentioned "scipilot" and it involves literature/citation-related content

Workflow

The following 8 Stages must be executed strictly in order. Before each Stage is completed, you must not skip to a subsequent Stage.

Stage 0: Information collection (must be completed — proactively ask item by item; silently assuming is prohibited)

This is the core interaction phase of the Skill.Absolutely forbiddento start searching when any required item is missing; for items with default values, you must also inform the user of the default value and then ask whether to adjust it.

A. Input mode (ask first)

Ask "the task type this time":

  • Mode A — Full paper mode: The user has a .tex or .docx file and wants to insert citations into the document
  • Mode B — Snippet support mode: The user provides a passage / an idea / a claim and wants to find real literature to support it (output a reference list, without modifying any document)

B. Basic parameters (required in both modes)

  1. Target object：
    • Mode A → paper file path (.tex or .docx)
    • Mode B → the text snippet to be supported (the user can simply paste a passage)
  2. Number of references: 5-30 recommended; for Mode B, 5-15 is usually sufficient
  3. Citation format：
    • IEEE (default, engineering/computer science/communications)
    • APA 7th (psychology/social sciences)
    • Nature (top natural science journals, superscript numbering)
    • Vancouver (medicine/biology)
    • GB/T 7714-2015 (Chinese national standard)
    • Custom (user-provided rules)

C. Search scope (required, inform the default value)

  1. Year range: default is the last 5 years (dynamically calculated based on the current date), the user can change it (e.g., "last 3 years", "2020-2026")
  2. Whether to include preprints: default not included(arXiv / bioRxiv / medRxiv / SSRN, etc.), the user can change it

D. Insertion location (required only in Mode A)

  1. Target sections: In which sections does the user want to insert citations?
    • Default: automatically determine all relevant sections (Introduction / Related Work / Method / Experiments / Discussion)
    • Can specify: "only add to Related Work and Method" / "exclude the Conclusion section" / "focus on adding to Introduction"

E. Quality and preferences (must proactively ask; the user may skip each item)

  1. Must-cite papers: Are there specific references that must be cited?The user must provide a DOI or complete metadata—the Skill will not make up a paper to fill the count
  2. Journal/conference preferences: Which venues are preferred? Which should be excluded? (e.g., "prefer Nature/Science/Cell", "exclude conference papers")
  3. Journal quartile: JCR Q1 / Q1-Q2 / CAS Tier 1 / CAS Tier 1-2 / no restriction (default no restriction)
    Note: quartile determination is a soft filter based on the LLM's knowledge of common top journals, not an authoritative ISSN-tier database query. If the user requires strict quartile control, a specific journal whitelist must be provided.
  4. Author preferences: Prefer citing certain authors or research groups? Exclude certain authors? (e.g., "prefer Yoshua Bengio's group", "exclude self-citations")
  5. Author affiliation preferences: Which institutions are preferred? Which should be excluded? (e.g., "only MIT/Stanford/Tsinghua", "exclude commercial companies")
  6. Additional search keywords: After automatically extracting keywords from the paper/snippet, the user may add a few domain terms

F. Parameter restatement confirmation (mandatory)

After collecting everything, you mustverbally restate all parametersto the user and wait for confirmation, e.g.:

I will process paper.tex(Mode A), inserting Introduction + Related Work into 15 IEEE-formatreferences, year 2022-2026，excluding preprints. Preferences:JCR Q1, institutions include MIT/Tsinghua, must-cite [DOI: 10.1038/s41586-024-07421-0], keyword supplements diffusion model / medical imaging. Start?

Before receiving an explicit "start" signal,do not enter Stage 1。

Stage 1: Paper analysis

Read the user's paper file and extract its structure.

  • .tex: read the source directly, identify \section{}、\cite{}, and record existing citations and the bibliography type.
  • .docx: use python-docx to read paragraphs, Heading styles, and existing References.

Output: paper title, list of sections, list of existing citations, core keywords (automatic + user-supplied).

Stage 2: Literature search

Call scripts/search_papers.py。

  • Query Semantic Scholar / OpenAlex / Crossref in parallel
  • Fetch ceil(用户需求数量 × 3) candidate papers per API
  • Sort by citation count in descending order
  • Filter by year range
  • If include_preprint=False, remove entries whose venue contains arxiv/biorxiv/medrxiv
  • Deduplicate using DOI as the primary key; when there is no DOI, merge by (title similarity >0.9 + same year + same first-author surname)

Stage 3: Literature verification (key step)

Call scripts/verify_paper.py::batch_verify。

Verification grading:

  • [OK] VERIFIED: DOI resolvable, Crossref metadata matches (title similarity ≥0.85, exact year, first-author surname matches)
  • [WARN] LIKELY_REAL: DOI missing or verification failed, but the same title can be found in both Semantic Scholar and OpenAlex (≥0.85 similarity)
  • [FAIL] UNVERIFIED: none of the above pass → discard directly, must not cite

Only VERIFIED and LIKELY_REAL references proceed to the next step.

Stage 4: Literature screening and ranking

From the candidates, select the number the user needs according to the following weights:

  • Relevance 40% (semantic relevance between the paper abstract and the paper's sections)
  • Quality 30% (citation count + journal tier)
  • Recency 20% (the newer the better)
  • Diversity 10% (avoid concentration from the same author team)

Show the candidate list to the user: each entry includes title, authors, year, venue, citation count, verification status, and suggested section. Wait for the user to confirm or request replacements, and if replacements are requested, return to Stage 2.

Stage 5: Citation insertion / list output

Mode A (paper insertion)：

  • .tex → scripts/insert_citations_latex.py: use \cite{key} to insert, and maintain the thebibliography or BibTeX .bib file
  • .docx → scripts/insert_citations_docx.py: insert [N] text markers, and add a References section at the end of the document
  • Insert only within the target sections specified in Stage 0—do not add citations in sections excluded by the user

Numbering rule: assign [1] [2] [3]...in order of first appearance starting from the first paragraph of the main text; existing citations start from the maximum number +1 (or the user chooses to renumber).

Insertion position rules:

  • At the end of the relevant discussion sentence, before the period
  • One position may have multiple citations:[3,5,7]
  • Insertion into figure/table captions, equations, or section headings is prohibited

Mode B (snippet-supported list output)：

  • Do not modify any document; sort candidate references by relevance + Stage 0 preference
  • Output a formatted References list into the conversation, and it can be saved to references_output.md
  • Add a number before each citation [1] [2] ...
  • Also output a one-sentence brief explanation of "how this reference supports the user's viewpoint" (based on the abstract)

Stage 6: Formatted output

Call scripts/format_citation.py::format_citation(paper, style) to generate each reference in the format specified by the user.

Format examples (see references/citation-formats.md）：

IEEE [1] A. Author, B. Author, "Title," *Journal*, vol. X, 2024, doi: 10.xxxx/xxxxx.
APA 7 Author, A., & Author, B. (2024). Title. *Journal*. https://doi.org/10.xxxx/xxxxx
Nature 1. Author, A., Author, B. Title. *Journal* 600, 1-10 (2024).
Vanc. 1. Author A, Author B. Title. Journal. 2024.
GB/T [1] 作者. 题名[J]. 刊名, 年, 卷(期): 起止页码.

Stage 7: Final check and delivery

Item 0 (blocking hallucination gate — Gate 8)

This is the first item, executed before the other self-checks; if it fails, the entire delivery process is interrupted immediately.

Write the final adopted reference list to final_papers.json, then forcibly run:

python scripts/audit_no_hallucination.py final_papers.json \
       --log verification_log.jsonl \
       --report audit_report.json

Capture exit code:

  • 0 → audit PASS, all citations pass 100% re-verification + log reconciliation, continue with subsequent self-checks
  • 2 → audit FAIL, immediately interrupt Stage 7. Read audit_report.json of per_paper section, report all pass=false entries to the user one by one (title, DOI, failure reason), and ask the user whether to discard these entries (recommended), re-check with replacement papers (return to Stage 2), or abandon the entire operation
  • 3 → runtime error (missing file/malformed format), fix and rerun

Absolutely not allowed: skipping audit, forging audit reports, or treating FAIL entries as PASS. This violates IRON RULE 7.

Items 1-5 (executed only after Item 0 PASSes)

  1. Numbering continuity: [1] to [N] with no gaps and no duplicates
  2. Citation-list consistency（Mode A only): every in-text number has a corresponding entry in References; References has no uncited orphans
  3. Format consistency: all entries use the same style
  4. Original text integrity（Mode A only): diff comparison confirms the original text was not modified
  5. Preprint proportion: if include_preprint=False, recheck that the venue does not contain arxiv

Mode B skips Item 2 and Item 4 (they do not involve the original text and in-text citations).

At delivery, output a SciPilot citation report：

  • Total N added
  • PASS/FAIL summary of audit_report.json
  • Verification status and source API of each reference
  • Citation distribution by section
  • Any LIKELY_REAL reference must be clearly marked

Error handling

  • API failure: automatically retry 3 times (2s interval, exponential backoff); if an API continues to fail, supplement with other APIs
  • Insufficient quantity: inform the user of the actual number found, and ask whether to broaden the search or accept fewer
  • Parsing exception: ask the user to confirm file integrity

Collaboration with the SciPilot Skills family

  • After citation insertion → recommend scipilot-writing-skill to polish newly cited sentences
  • Full review → recommend scipilot-review-skill
  • Chart coordination → Recommendation scipilot-figure-skill

Dependencies

pip install requests python-docx python-Levenshtein

All APIs are free access tiers, no API key required.

Working directory artifacts (must be retained until delivery is complete)

File Generated by Purpose
evidence_log.jsonl search_papers.py Each result is written to disk Proves that every candidate comes from a real API response
verification_log.jsonl verify_paper.py::batch_verify Each verification is written to disk Reconciliation basis for Stage 7 item 0
final_papers.json Written by the LLM after user confirmation in Stage 4 Input for audit
audit_report.json audit_no_hallucination.py Output Gate 8 credential for the user

These four files constitute the "evidence chain" of this Skill. The LLM has no write permission to directly produce evidence/verification logs—they must be produced by running the corresponding Python scripts. This is the core mechanism that turns "do not fabricate" from a slogan into a machine-checkable contract.

Reference files

  • references/citation-formats.md — Complete specifications and examples for each citation format
  • references/api-reference.md — Detailed documentation for the Semantic Scholar / OpenAlex / Crossref APIs
  • references/workflow.md — Complete workflow and edge case handling
  • assets/format_templates/*.json — JSON templates for each format (can be overridden by custom ones)