SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsacademic-ref-check

academic-ref-check

Data & analytics

View repository

Updated 10-16 02:35

About this skill

Reference Check

The complete process of checking, verifying, repairing, and formatting academic references. From the raw reference list to final reference output that is format-compliant, database-verified, and accompanied by a manual review checklist.

Core Rules

The following five rules are the cornerstone of the entire process. Violating any one of them will lead to errors in downstream outputs, and the errors will be difficult to detect in subsequent stages.

1. Use author + year fingerprint IDs, not sequence numbers

All stages use content fingerprints when citing references (作者姓_年份_标题关键词), not positional sequence numbers (such as中[3]、英[218]). This is because deduplication, repair, and reordering all change reference positions; positional sequence numbers will point to the wrong reference after the first modification, whereas fingerprint IDs are bound to reference content and remain valid no matter how they are reordered.

Fingerprint ID generation rules:

  • English:{第一作者姓}_{年份}_{标题前3个实词}(skip a/an/the/of/in/on/for/and/with/to)
  • Chinese:{第一作者姓}_{年份}_{标题前5个字}
  • Example:Harding_2025_Musical_neurodynamics、安心_2017_高海拔驻留时间对

2. Repair only with database evidence

Academic citations must be precise—reference content must not be modified based on guesswork. Automatic repair is limited to scenarios where database confidence is high and the repair direction is unambiguous (such as DOI supplementation and obvious year errors). In cases involving author additions or deletions, substantive title differences, etc., report only and do not modify, leaving the judgment to the user. For specific judgment criteria, see references/fix_decision_matrix.md。

3. The final file is the only authoritative source

The "current content" cited in the manual review checklist (or any user-facing document) must be copied verbatim from the final reference file. Intermediate-stage verification reports are only used to determine "which entries need attention," not to provide the specific content of entries. The reason this rule exists is that reference snapshots recorded during the verification stage will become outdated in subsequent repairs; if the checklist copies content from an old snapshot, a serious error will occur in which the checklist description is completely inconsistent with the final file.

4. Separate rule-based checks from judgment-based review

Rule-based issues such as sentence case, the ampersand, and DOI formatting are checked item by item by a full-scan SubAgent to ensure 100% coverage. Issues requiring judgment, such as journal authenticity and citation accuracy, are reviewed by domain experts. The two run in parallel but their responsibilities do not overlap. Mixing them will cause rule-based issues to be missed by expert-style sampling (the lesson from the first execution was that 58 sentence case issues were all missed by 4 experts).

5. The checklist is the terminal product of the pipeline

The manual review checklist must be generated independently as the final stage after all automatic repairs and expert reviews are completed. Generating it too early will include issues that have already been fixed subsequently, causing the checklist to be inconsistent with the final file.

SubAgent Roles and Operation Guide

After each SubAgent loads this Skill, it reads the corresponding operation guide and reference files according to the role assigned to it.

Parser

Responsibilities: Parse the raw reference text into structured data, and assign a fingerprint ID to each reference.

Key operation points:

  1. Identify reference entries broken across multiple lines (cases where the title and journal name are split into multiple lines) and merge them into complete entries
  2. Identify non-standard citation formats (Nature style, numbered format[2], Chinese[J]annotations, etc.)
  3. Generate a fingerprint ID for each reference (rules see Core Rules item 1)
  4. Extract structured fields: authors, year, title, source, volume/issue/pages, DOI, document type, language
  5. Flag identified formatting issues (DOI format errors, mixed full-width punctuation, residual annotations, etc.)

Deduplication rules:

  • Identical DOI → keep the more complete version
  • Title similarity >90% and same year → keep the more complete version
  • Preprint vs formally published version → keep the formally published version

Formatter

Responsibilities: Output structured reference data in APA 7th edition format.

Before formatting, read references/apa7_rules.md for the complete APA 7th edition formatting rules.

Key operations:

  1. Author format:姓, 名首字母., list all for 1-20 authors, use ellipsis rule for 21+
  2. Title: sentence case (capitalize only the first letter and proper nouns)
  3. Journal name: title case + italics (in Markdown use*期刊名*markup)
  4. DOI uniformly ashttps://doi.org/prefix format
  5. Sorting: Chinese references by pinyin first, English references alphabetically after
  6. Chinese references also use&to connect the last two authors

Verifier

Responsibilities: Verify the accuracy of each reference through academic databases.

Before verifying, read references/verification_guide.md for the complete database query workflow and result classification rules.

Primary verification path = scripts/verify_http.py(OpenAlex + CrossRef public HTTP API, no key required). If the runtime environment does not provide semantic-scholar / openalex MCP server (the common default case), the original "mandatory loading of SS/OpenAlex MCP" path will spin idle. This Skill accepts this degradation, and verification switches to HTTP scripts:

python3 scripts/verify_http.py --in refs.json --out-dir <dir>     # 结构化 JSON 输入
python3 scripts/verify_http.py --in-text refs.md --out-dir <dir>  # 原始文本/Markdown 引用列表（自解析）
  • Artifacts:L11_ref_verify_report.md(human-readable, four states green/yellow/red/unverified) + L11_ref_verify_report.json(machine-readable).
  • Exit codes (can directly connect to the SP7 preflight gate):any red→1 / otherwise any unverified→3 / otherwise any yellow→2 / all green→0.
  • Iron rule (inviolable): network failure / no match found must never be disguised as passing—no fake green. All "uncertain" cases fall to yellow or red, never to green; network failures are marked unverified (rendered as yellow, must be rerun, cannot be treated as passing). Matching trusts only self-computed title similarity, not the API's "has results"/score/total-results. Chinese references not covered by international databases→yellow (not hallucination, not red).

MCP channel (optional · only when SS/OpenAlex MCP exists in the environment): If the environment indeed has semantic-scholar / openalex MCP server installed, it can be used as asupplementary verification channelto cross-corroborate with the HTTP scripts (use ToolSearch to load mcp__semantic-scholar__* / mcp__openalex__* then call, for tool usage see references/verification_guide.md). This is a conditional branch, not a prerequisite step—if the environment does not have these MCPs, just use the HTTP primary path directly, no need to attempt loading.

Verification strategy: Under the primary path, verify_http.py internally completes "DOI first → title search → self-computed similarity determination" and classifies by green/yellow/red/unverified (see the ABCD category comparison below); when MCP is present, yellow/red entries can be cross-corroborated. Only when neither database (HTTP or MCP) can find it is it marked as category D.

Result classification:

Category Meaning Follow-up handling
A Verification passed No action needed
B Can be automatically fixed (high confidence) Hand off to the fixer
C Requires manual judgment Add to the review checklist
D Not found Decide whether to add to the checklist based on the document type

Special handling for Chinese-language literature: OpenAlex and Semantic Scholar have limited coverage of Chinese-language literature. It is normal for Chinese-language literature not to be found and should not be treated as a signal that the information may be incorrect, unless the literature itself has formatting anomalies.

Fixer

Responsibilities: Aggregate verification results and perform automatic fixes on Category B entries.

Before fixing, read references/fix_decision_matrix.md for the auto-fix vs report-only decision rules.

Key operating points:

  1. Only fix entries in Category B with "high" confidence. Medium/low confidence entries are all transferred to the Category C report
  2. Each fix must simultaneously be recorded in the fix operation log: fingerprint ID, fix type, value before fix, value after fix, basis for fix
  3. After fixes are completed, verify that the total number of references is conserved (fixes should not add or remove references)
  4. Update the fix status summary table

Typical scenarios that can be automatically fixed: DOI supplementation/format correction, obvious year errors (e.g., 2026→2025), sentence case conversion, removal of PubMed annotations from journal names, punctuation correction, sorting correction.

Typical scenarios that are report-only: Major changes to the author list, substantive differences in titles, major inconsistencies in volume/issue/page numbers, literature not indexed in the database.

Rule Scanner

Responsibilities: Perform a full item-by-item rule check on the final version of the references to ensure 100% coverage.

Before scanning, read references/apa7_rules.md for the complete checklist of rules to verify.

Difference from expert review: The rule scanner checks formatting rules that can be programmatically determined (with clear right/wrong criteria), while expert review handles issues that require academic judgment.

Rules that must be scanned item by item (every reference is checked):

  1. Sentence case (English titles capitalize only the first letter and proper nouns)
  2. Between authors&symbol (must be checked for both Chinese and English literature)
  3. DOI format (https://doi.org/prefix, no extra spaces/duplicate prefixes)
  4. Journal name italic markup (*期刊名*）
  5. Punctuation conventions (half-width, period at end of sentence, comma placement)
  6. Year format (inside parentheses, after comma)
  7. Sorting correctness (Chinese pinyin, English letters)
  8. 21+ author ellipsis rule

Domain Expert

Responsibilities: Perform non-rule-based review that requires academic judgment.

Review dimensions:

  • Journal authenticity: whether the journal exists, whether it is a predatory journal
  • Citation accuracy: whether the literature is consistent with the paper's subject area
  • Content reasonableness: whether the year, volume/issue, and page numbers are within a reasonable range
  • Special format judgment: situations where conference papers, preprints, etc. have multiple reasonable formats

Matters not within its responsibility: Rule-based checks such as sentence case and the & symbol (handled by the rule scanner).

Checklist Generator

Responsibilities: Generate the user-facing manual review checklist. This is the step in the entire process with the highest accuracy requirements.

Before generating, read references/checklist_spec.md for the complete checklist format specification, category definitions, and validation rules.

Mandatory generation process:

  1. Read the final literature file and build a complete mapping table of fingerprint ID → final content
  2. Read the validation summary report and extract Category C and Category D entries
  3. Read the fix status summary table and exclude entries that have already been fixed
  4. Read the expert review report and extract unfixed issues
  5. Merge to obtain the "items pending review pool"
  6. For each item pending review, extract the final content from the mapping table in step 1 via the fingerprint ID (do not copy from the validation report)
  7. Organize the list by the five categories
  8. Perform consistency validation (usescripts/validate_checklist.py）

Five categories:

  1. Must Fix
  2. Not Found in database
  3. Auto-fixed, Please Verify
  4. Suggested Additions
  5. FYI

Word Converter

Responsibilities: Convert the final Markdown literature file into a Word document that meets doctoral dissertation formatting standards.

Use scripts/convert_refs.py to perform the conversion:

python scripts/convert_refs.py <input.md> [output.docx]

Formatting specifications:

  • Title: SimHei size 3 (16pt), centered, bold
  • Entries: SimSun + TNR size 5 (10.5pt), fixed line spacing 20pt, hanging indent 2 characters
  • Journal names: italic (automatically recognized via*期刊名*markers)
  • Page: A4, margins top 3/bottom 2.5/left 3/right 2.5cm

Dependencies: pip install python-docx

APA 7th edition format quick reference table

The following are the 10 most commonly used rules; for the complete rules, see references/apa7_rules.md。

# Rule Correct example
1 Author format: Surname, First initial. Zhang, L. M.
2 For multiple authors use,as separator, and use& Li, A., Wang, B., & Chen, C.
3 21+ authors: first 19...last 1 Author, A., Author, B., ... Author, U.
4 Year in parentheses after the authors Smith, J. (2023).
5 Article title in sentence case Effects of music on cognitive development in children
6 Journal name in title case + italic *Journal of Experimental Psychology*
7 Volume number italic, issue number not italic and in parentheses *12*(3), 45-67
8 Use DOIhttps://doi.org/前缀 https://doi.org/10.1037/rev0000106
9 Book title italic + sentence case *Cognitive psychology: A student's handbook*
10 No period at the end of an entry (e.g., when ending with a DOI) Do not add a period after a DOI link

Supplementary rules for Chinese-language literature:

  • Chinese-language literature also uses&to connect the last two authors (do not use "and")
  • Doctoral dissertation format:作者. (年份). *标题* [博士学位论文, 院校名称]. 数据库名称.
  • Chinese journal names are not italicized

Script Usage Guide

convert_refs.py — Markdown to Word

# 基本用法
python scripts/convert_refs.py input.md output.docx

# 默认输出（与输入同名.docx）
python scripts/convert_refs.py input.md

The script automatically handles: metadata skipping, category heading recognition, journal name italic rendering, and square bracket comment cleanup.

validate_checklist.py — Checklist validation

python scripts/validate_checklist.py checklist.md final_refs.md

Perform five validations:

  1. Content consistency: the literature content cited in the checklist matches the final file word for word
  2. Classification accuracy: Category D labels are consistent with the validation summary report
  3. Completeness: all Category C and unfixed issues are covered
  4. Numbering continuity: within each category the numbers are continuous, and the total is consistent with the statistics table
  5. Statistical cross-validation: total number of references = number not requiring review + number requiring review

Performance Notes

  • The validation phase is the most time-consuming step. One SubAgent is assigned per batch of 25-30 references, with up to 12 running in parallel, and each batch uses dual databases (Semantic Scholar + OpenAlex) for cross-validation
  • Quality takes priority over speed: do not skip any verification step, and do not give up querying the second database just because the database responds slowly
  • Keep the review loop to 1-2 rounds: through a first-round full-coverage design combining rule scanner + expert review in parallel, strive to find 90%+ of issues in the first round, reducing the number of iteration rounds
  • All SubAgents must use the Opus 4.6 model

Change Log

  • S7（2026-06-23，Lane C）: The Verifier role has been entirely rewritten as HTTP primary path (scripts/verify_http.py)/ optional supplement when MCP is present—the runtime environment has no SS/OpenAlex MCP, and it is acceptable to degrade to using the OpenAlex/CrossRef public HTTP APIs. Remove the overstatement in the original mandatory MCP loading block that "MCP in the environment can definitely be loaded" and the prerequisite mandate that "MCP must be loaded first before verification can be performed," and remove the to-do annotation for this section left by S3.verification_guide.md §1 Synchronized closure.