citation-assistant
Use when the user needs academic citations, BibTeX, venue/author quality checks, or help filling [CITE] placeholders. Triggers include 文献引用、找引用、citation、bib、参考文献、替换不规范引用、查询作者 H-index、判断期刊/会议质量。
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/zhangny301--citation-assistant)HTML
<a href="/listings/zhangny301--citation-assistant"><img src="/api/listings/zhangny301--citation-assistant/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Requires Bash, `curl` (7.55.0+), `jq`, and a version of `sqlite3` that supports `-json`. On Windows, install and run through WSL. Online searches require network access; local venue database queries do not require an API key.
Codex
Install for your user account to make the Skill available across projects:
mkdir -p ~/.agents/skills git clone https://github.com/ZhangNy301/citation-assistant.git ~/.agents/skills/citation-assistant # Optional: create .env in the installation directory and enter your S2_API_KEY. # Do not overwrite an existing .env file. cp -n ~/.agents/skills/citation-assistant/.env.example ~/.agents/skills/citation-assistant/.env
Alternatively, install only for a manuscript project by running the following from that project's root. Choose either this or the user-level installation:
mkdir -p .agents/skills git clone https://github.com/ZhangNy301/citation-assistant.git .agents/skills/citation-assistant
Invoke the Skill in Codex:
$citation-assistant Assess the quality of Nature Medicine and explain the sources of the metrics.
Natural-language requests such as “Find references for this paragraph” can also trigger the Skill. Restart Codex if it does not appear after installation. See the [official Codex Skills documentation](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills) for discovery paths.
Verify a user-level installation from any manuscript directory, without network access:
bash "$HOME/.agents/skills/citation-assistant/scripts/venue_info.sh" "Nature Medicine"
For a project-level installation, replace the path with the absolute path to that project's `.agents/skills/citation-assistant` directory. All clients share the same `SKILL.md`, scripts, and databases. There is no need to set `CLAUDE_SKILL_ROOT`.
Claude Code
# Clone the repository. git clone https://github.com/ZhangNy301/citation-assistant.git # Copy the Skill into Claude Code's skills directory. mkdir -p ~/.claude/skills/citation-assistant cp citation-assistant/SKILL.md ~/.claude/skills/citation-assistant/ cp -r citation-assistant/scripts ~/.claude/skills/citation-assistant/ cp -r citation-assistant/data ~/.claude/skills/citation-assistant/ # Configure an API key (recommended). echo 'S2_API_KEY="your_key_here"' > ~/.claude/skills/citation-assistant/.env
Cursor
# Create the skills directory and clone the repository. mkdir -p ~/.cursor/skills cd ~/.cursor/skills git clone https://github.com/ZhangNy301/citation-assistant.git # Configure an API key (recommended). echo 'S2_API_KEY="your_key_here"' > ~/.cursor/skills/citation-assistant/.env
Request an API key from [Semantic Scholar](https://www.semanticscholar.org/product/api).
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 242 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: citation-assistant
- description: Use when the user needs academic citations, BibTeX, venue/author quality checks, or help filling [CITE] placeholders. Triggers include 文献引用、找引用、citation、bib、参考文献、替换不规范引用、查询作者 H-index、判断期刊/会议质量。
- ---
- # Citation Assistant 学术文献引用助手
- ## ⚠️ 核心原则
- 1. **必须通过 `scripts/` 目录中的脚本执行**,禁止手动编写 curl 命令
- 2. **禁止使用 Tavily、WebSearch 等非学术搜索工具**进行文献检索
- 3. **语义优先**:理解引用意图,避免仅用关键词检索
- 4. **不自动修改文稿**:所有推荐需用户确认后再应用
- ---
- ## 运行路径(Codex / Claude Code / Cursor)
- 以本次加载的 `SKILL.md` 所在目录为 Skill 根目录,**不要使用论文项目的当前工作目录来定位脚本**,也不要假设客户端会注入 `CLAUDE_SKILL_ROOT` 等环境变量。
- 下面示例中的 `CITATION_ASSISTANT_ROOT` 是自行设置的 shell 变量:将其设为本次加载的 Skill 的绝对路径(包含 `SKILL.md`、`scripts/` 和 `data/`)。每次新的 shell 调用都需重新设置它,或直接使用脚本的完整绝对路径;路径始终加双引号。
- ```bash
- # 将此路径替换为本次加载的 SKILL.md 所在目录
- CITATION_ASSISTANT_ROOT="/absolute/path/to/citation-assistant"
- bash "${CITATION_ASSISTANT_ROOT}/scripts/venue_info.sh" "Nature Medicine"
- ```
- 脚本从自身位置读取同一安装目录内的 `.env` 和 `data/`,可以在任意论文目录运行。在 Codex 中可通过 `$citation-assistant` 显式调用,也可用自然语言请求引用检索、BibTeX 或期刊质量查询。
- ## 📦 可用脚本
- 依赖:Bash、`curl`、`jq`、支持 `-json` 的 `sqlite3`。搜索、作者查询和 DOI 转换需要网络;CCF / IF 查询只读本地数据库。
- 下表中的相对路径以 Skill 根目录为基准;从论文目录调用时使用上述绝对路径。
- | 脚本 | 用途 | 用法 |
- |------|------|------|
- | `search_papers.sh` | 默认文献检索:S2 搜索持续 429 后自动转 CrossRef,结果带来源 | `bash scripts/search_papers.sh "query" [limit]` |
- | `s2_search.sh` | 少量高相关结果检索(含 arXiv 判断) | `bash scripts/s2_search.sh "query" [limit]` |
- | `s2_bulk_search.sh` | 批量拉取候选结果并按本地 limit 输出(含 arXiv 判断) | `bash scripts/s2_bulk_search.sh "query" "year_range" limit` |
- | `author_info.sh` | 作者信息查询(H-index) | `bash scripts/author_info.sh "author_id"` |
- | `venue_info.sh` | 期刊综合查询 | `bash scripts/venue_info.sh "venue_name"` |
- | `ccf_lookup.sh` | CCF 分级查询 | `bash scripts/ccf_lookup.sh "venue_name"` |
- | `if_lookup.sh` | 影响因子查询 | `bash scripts/if_lookup.sh "journal_name"` |
- | `doi2bibtex.sh` | DOI 转 BibTeX | `bash scripts/doi2bibtex.sh "doi"` |
- | `crossref_search.sh` | CrossRef 搜索(fallback) | `bash scripts/crossref_search.sh "query" [limit]` |
- ---
- ## 🆕 增强功能
- ### arXiv 文章智能判断
- 搜索结果会自动标记 arXiv 文章的引用状态:
- | 状态 | 条件 | 推荐建议 |
- |------|------|----------|
- | `recommended` | arXiv + 引用 ≥ 100 | ✅ 高影响力 arXiv,可引用 |
- | `caution` | arXiv + 引用 < 100 | ⚠️ 低引用 arXiv,谨慎引用 |
- | `normal` | 正式发表 | ✅ 正式发表 |
- **配置引用阈值**(默认 100):
- ```bash
- export ARXIV_CITATION_THRESHOLD=100
- ```
- ### 作者信息查询
- 搜索结果包含前 3 位作者的 ID,可用于查询 H-index:
- ```bash
- # 查询作者 H-index、总引用量、论文数
- bash "${CITATION_ASSISTANT_ROOT}/scripts/author_info.sh" "18119920"
- ```
- 返回示例:
- ```json
- {
- "name": "Daquan Zhou",
- "hIndex": 25,
- "citations": 8500,
- "papers": 42
- }
- ```
- ---
- ## 🔄 工作流程
- ### Step 1: 解析需求
- 识别用户需求类型:
- - **[CITE] 占位符**:提取上下文,构造语义查询
- - **替换不规范引用**:分析原文引用的语义意图
- - **期刊查询**:直接查询 CCF/IF 数据库
- - **作者质量评估**:查询第一/通讯作者的 H-index
- ### Step 2: 语义化查询构造
- | 引用目的 | 查询策略示例 |
- |----------|--------------|
- | 事实背书 | "chest radiography most widely used imaging test globally statistics" |
- | 方法引用 | "attention mechanism transformer neural machine translation" |
- | 背景介绍 | "deep learning medical image analysis survey review" |
- ### Step 3: 执行搜索
- - 日常文献检索优先使用 `search_papers.sh`:S2 相关性搜索,持续 429 时自动转 CrossRef;若用户明确只接受 S2 数据,则使用 `s2_search.sh`
- - 需要减少请求次数、批量拉取候选结果并再做筛选时,使用 `s2_bulk_search.sh`
- ```bash
- # 默认检索入口(自动处理 S2 持续限流)
- bash "${CITATION_ASSISTANT_ROOT}/scripts/search_papers.sh" "YOUR_QUERY" 10
- # 批量候选结果(bulk endpoint),再由脚本按 limit 输出前 N 条
- bash "${CITATION_ASSISTANT_ROOT}/scripts/s2_bulk_search.sh" "YOUR_QUERY" "2020-" 20
- ```
- **直接使用原始 S2 脚本且返回 429 错误时**,可显式使用 CrossRef fallback(`search_papers.sh` 已自动处理):
- ```bash
- bash "${CITATION_ASSISTANT_ROOT}/scripts/crossref_search.sh" "YOUR_QUERY" 20
- ```
- 自动降级限定期刊论文、会议论文与预印本类记录;检查 CrossRef 的 `work_type`,预印本不能当作已正式发表。
- 检查 `source` / `search_method`:CrossRef 结果属于独立来源的文献匹配,不应描述为 S2 的相关性排名。其作者 ID、arXiv 判断等不可用字段为 `null` / `unknown`,不要调用 `author_info.sh` 查询空 ID,也不要补造 H-index。引用量必须标注数据来源,不直接混用不同来源的计数。降级后的结果同样需要核实是否支持原文观点。
- ### Step 4: 评估文献质量
- ```bash
- # 查询期刊质量
- bash "${CITATION_ASSISTANT_ROOT}/scripts/venue_info.sh" "Nature Medicine"
- # 查询作者 H-index
- bash "${CITATION_ASSISTANT_ROOT}/scripts/author_info.sh" "AUTHOR_ID"
- ```
- ### Step 5: 生成 BibTeX
- ```bash
- bash "${CITATION_ASSISTANT_ROOT}/scripts/doi2bibtex.sh" "10.1038/s41591-020-0792-9"
- ```
- ### Step 6: 生成中文推荐报告
- 输出格式示例:
- ```markdown
- ## 引用推荐报告
- ### [CITE] 位置 1
- **原文上下文**:
- > In chest radiography---arguably the most widely used imaging test globally [CITE]---
- **推荐文献**:
- #### 推荐 1: Wu2020 - CheXpert: A large chest radiograph dataset...
- **质量指标**:
- | 维度 | 值 | 说明 |
- |------|-----|------|
- | CCF 分级 | N/A | 非CS领域期刊 |
- | JCR 分区 | Q1 | 顶级医学影像期刊 |
- | 影响因子 | 29.1 | 极高影响力 |
- | 引用量 | 3500+ | 高被引文献 |
- | arXiv 状态 | normal | 正式发表 |
- **推荐理由**:顶级期刊发表,直接支持原文论点。
- **BibTeX**:
- ```bibtex
- @article{Wu2020, ... }
- ```
- **建议用法**:将 `[CITE]` 替换为 `~\cite{Wu2020}`
- ```
- ---
- ## ⚙️ 配置
- ### Semantic Scholar API Key(强烈推荐)
- ```bash
- # 在 Skill 目录创建 .env 文件
- echo 'S2_API_KEY="your_key_here"' > "${CITATION_ASSISTANT_ROOT}/.env"
- # 获取 API Key: https://www.semanticscholar.org/product/api/api-key
- ```
- | 模式 | 速率限制 | 推荐场景 |
- |------|----------|----------|
- | 有 API Key | 1 次/秒 | 日常使用(推荐) |
- | 无 API Key | 共享限额 | 极易触发 429 |
- ### arXiv 引用阈值(可选)
- ```bash
- # 默认 100,可在 .env 中配置
- echo 'ARXIV_CITATION_THRESHOLD=100' >> "${CITATION_ASSISTANT_ROOT}/.env"
- ```
- ---
- ## 🚨 错误处理
- ### 429 Rate Limit
- 1. S2 脚本已自动进行有界重试(默认最多 2 次),优先遵守 `Retry-After`;不要连续重复调用或把 429 当作无效密钥
- 2. 仍失败时等待更长时间,并说明当前接口受限;带 Key 或切换 bulk 接口也不保证解除限流
- 3. 论文检索可使用 `crossref_search.sh` fallback;作者 H-index 无此替代,无法获取时明确标记未知
- ### 401 / 403
- 脚本不重试认证或权限错误。检查 Skill 目录的 `.env` / `S2_API_KEY` 及接口权限,不输出密钥。
- ### 无搜索结果
- 1. 简化关键词
- 2. 使用英文查询
- 3. 尝试 CrossRef fallback
- ---
- ## 📊 质量评估维度
- | 维度 | 权重 | 计算 |
- |------|------|------|
- | CCF 分级 | 基础分 | A=100, B=70, C=40 |
- | JCR 分区 | 基础分 | Q1=80, Q2=60, Q3=40, Q4=20 |
- | 中科院分区 | 基础分 | 1区=90, 2区=70, 3区=50, 4区=30 |
- | 影响因子 | 30% | IF × 5 (上限50) |
- | 引用量 | 20% | log₁₀(citations+1) × 10 (上限50) |
- | 年份 | 10% | (year-2015) × 2 (上限30) |
- | 作者 H-index | 10% | 第一作者 H-index × 2 (上限30) |
- **arXiv 处理**:
- - 引用 ≥ 100:正常评分
- - 引用 < 100:降低优先级 (-20 分)
- - 有正式发表版本优先
README.md · README · 335 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Citation Assistant
- English | [简体中文](README.zh-CN.md)
- > An academic citation assistant for Codex, Claude Code, and Cursor, designed for manuscript writing, BibTeX generation, and literature quality assessment.
- Search academic literature through the Semantic Scholar API, automatically fall back to CrossRef during persistent rate limiting, and keep the source of each result explicit. Combine CCF rankings, JCR quartiles, Chinese Academy of Sciences (CAS) journal tiers, impact factors, and author H-indices to assess candidates, generate BibTeX, and produce recommendations. The current Skill workflow produces recommendation reports in Chinese.
- This repository serves two audiences:
- - **GitHub users**: read `README.md` or `README.zh-CN.md` for features, installation, and examples.
- - **Skill runtimes (Codex / Claude Code / Cursor)**: read `SKILL.md` and follow its scripts and workflow.
- ---
- ## ✨ Features
- | Feature | Description |
- |---------|-------------|
- | 🔍 **Context-aware literature search** | Use Semantic Scholar to find papers relevant to the citation's context, with queries constructed by the assistant. |
- | 🛡️ **Reference verification** | Retrieve BibTeX through DOI resolution to verify references instead of inventing citation metadata. |
- | 📊 **Quality assessment** | Review venue metrics (CCF ranking, JCR quartile, CAS tier, impact factor) and author metrics (H-index, citation count). |
- | 📝 **BibTeX generation** | Generate BibTeX entries for use in LaTeX documents. |
- | 📋 **Recommendation reports** | Present structured results and explain why each candidate fits the manuscript. |
- ---
- ## 🚀 Installation
- Requires Bash, `curl` (7.55.0+), `jq`, and a version of `sqlite3` that supports `-json`. On Windows, install and run through WSL. Online searches require network access; local venue database queries do not require an API key.
- ### Codex
- Install for your user account to make the Skill available across projects:
- ```bash
- mkdir -p ~/.agents/skills
- git clone https://github.com/ZhangNy301/citation-assistant.git ~/.agents/skills/citation-assistant
- # Optional: create .env in the installation directory and enter your S2_API_KEY.
- # Do not overwrite an existing .env file.
- cp -n ~/.agents/skills/citation-assistant/.env.example ~/.agents/skills/citation-assistant/.env
- ```
- Alternatively, install only for a manuscript project by running the following from that project's root. Choose either this or the user-level installation:
- ```bash
- mkdir -p .agents/skills
- git clone https://github.com/ZhangNy301/citation-assistant.git .agents/skills/citation-assistant
- ```
- Invoke the Skill in Codex:
- ```text
- $citation-assistant Assess the quality of Nature Medicine and explain the sources of the metrics.
- ```
- Natural-language requests such as “Find references for this paragraph” can also trigger the Skill. Restart Codex if it does not appear after installation. See the [official Codex Skills documentation](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills) for discovery paths.
- Verify a user-level installation from any manuscript directory, without network access:
- ```bash
- bash "$HOME/.agents/skills/citation-assistant/scripts/venue_info.sh" "Nature Medicine"
- ```
- For a project-level installation, replace the path with the absolute path to that project's `.agents/skills/citation-assistant` directory. All clients share the same `SKILL.md`, scripts, and databases. There is no need to set `CLAUDE_SKILL_ROOT`.
- ### Claude Code
- ```bash
- # Clone the repository.
- git clone https://github.com/ZhangNy301/citation-assistant.git
- # Copy the Skill into Claude Code's skills directory.
- mkdir -p ~/.claude/skills/citation-assistant
- cp citation-assistant/SKILL.md ~/.claude/skills/citation-assistant/
- cp -r citation-assistant/scripts ~/.claude/skills/citation-assistant/
- cp -r citation-assistant/data ~/.claude/skills/citation-assistant/
- # Configure an API key (recommended).
- echo 'S2_API_KEY="your_key_here"' > ~/.claude/skills/citation-assistant/.env
- ```
- ### Cursor
- ```bash
- # Create the skills directory and clone the repository.
- mkdir -p ~/.cursor/skills
- cd ~/.cursor/skills
- git clone https://github.com/ZhangNy301/citation-assistant.git
- # Configure an API key (recommended).
- echo 'S2_API_KEY="your_key_here"' > ~/.cursor/skills/citation-assistant/.env
- ```
- Request an API key from [Semantic Scholar](https://www.semanticscholar.org/product/api).
- ---
- ## 📦 Available scripts
- | Script | Purpose | Usage |
- |--------|---------|-------|
- | `search_papers.sh` | Default search: S2 relevance search, then CrossRef after persistent HTTP 429 responses | `bash scripts/search_papers.sh "query" [limit]` |
- | `s2_search.sh` | Retrieve a small set of relevant S2 results, including arXiv status | `bash scripts/s2_search.sh "query" [limit]` |
- | `s2_bulk_search.sh` | Retrieve candidates from the S2 bulk endpoint and return the first N records using a local limit | `bash scripts/s2_bulk_search.sh "query" "year_range" limit` |
- | `author_info.sh` | Look up an author's H-index | `bash scripts/author_info.sh "author_id"` |
- | `venue_info.sh` | Query combined venue quality metrics | `bash scripts/venue_info.sh "venue_name"` |
- | `ccf_lookup.sh` | Look up CCF rankings | `bash scripts/ccf_lookup.sh "venue_name"` |
- | `if_lookup.sh` | Look up journal impact factors | `bash scripts/if_lookup.sh "journal_name"` |
- | `doi2bibtex.sh` | Convert a DOI to BibTeX | `bash scripts/doi2bibtex.sh "doi"` |
- | `crossref_search.sh` | Search CrossRef directly as a fallback | `bash scripts/crossref_search.sh "query" [limit]` |
- > Use `search_papers.sh` for everyday searches (limit: 1–100), or `s2_search.sh` when only S2 results are acceptable. Use `s2_bulk_search.sh` to retrieve a batch of candidates before filtering them locally.
- ---
- ## 🆕 Additional capabilities
- ### arXiv citation assessment
- S2 search results are labeled according to their arXiv status and citation count:
- | Status | Condition | Recommendation |
- |--------|-----------|----------------|
- | `recommended` | arXiv paper with ≥ 100 citations | ✅ Highly cited arXiv paper; consider citing. |
- | `caution` | arXiv paper with < 100 citations | ⚠️ Low citation count; assess carefully. |
- | `normal` | Not identified as arXiv by the venue check | Check the publication venue and version. |
- ### Author information
- S2 search results include IDs for the first three authors, which can be used to look up their H-indices:
- ```bash
- bash scripts/author_info.sh "18119920"
- ```
- Example response:
- ```json
- {
- "name": "Daquan Zhou",
- "hIndex": 25,
- "citations": 8500,
- "papers": 42
- }
- ```
- ---
- ## 📁 Repository structure
- ```text
- citation-assistant/
- ├── SKILL.md # Skill instructions
- ├── README.md # English documentation (this file)
- ├── README.zh-CN.md # Chinese documentation
- ├── CHANGELOG.md # Version history
- ├── .env.example # Configuration template
- ├── agents/openai.yaml # Codex display metadata and default prompt
- ├── tests/ # Offline installation and script regression tests
- ├── scripts/ # Shell scripts
- │ ├── init.sh
- │ ├── s2_request.sh # S2 requests, pacing, and bounded retries
- │ ├── search_papers.sh # Default search with labeled S2 → CrossRef fallback
- │ ├── s2_search.sh
- │ ├── s2_bulk_search.sh
- │ ├── author_info.sh
- │ ├── venue_info.sh
- │ ├── ccf_lookup.sh
- │ ├── if_lookup.sh
- │ ├── doi2bibtex.sh
- │ └── crossref_search.sh
- └── data/ # Databases
- ├── ccf_2026.sqlite
- ├── ccf_2026.jsonl
- └── impact_factor.sqlite3
- ```
- ---
- ## 🔧 Configuration
- ### Semantic Scholar API key
- Request a key from [Semantic Scholar](https://www.semanticscholar.org/product/api).
- | Mode | Rate limit |
- |------|------------|
- | With an API key | Initial allowance of 1 request/second across endpoints; throttling can still occur. |
- | Without an API key | Shared quota; HTTP 429 responses are common. |
- Place `.env` in the installed Skill's root directory. For a Codex user-level installation, this is `~/.agents/skills/citation-assistant/.env`; for a project installation, it is `<manuscript-project>/.agents/skills/citation-assistant/.env`. Claude Code and Cursor use their respective installation directories. Without `.env`, scripts also accept an exported `S2_API_KEY`. Values specified in `.env` take precedence over environment variables.
- ### Semantic Scholar rate limiting and retries
- The three S2 scripts share request handling. HTTP 429 responses are retried at most twice by default. The scripts honor `Retry-After` (seconds or an HTTP date); if it is missing or cannot be parsed, they wait 2 and then 4 seconds. If the requested wait exceeds the configured maximum, they stop rather than retry early. HTTP 401/403 responses are not retried and prompt a credentials or endpoint-permissions check. Diagnostics go to stderr; stdout contains only the final successful results.
- Configure these settings in the Skill's `.env`:
- ```bash
- S2_MIN_INTERVAL=1 # Minimum interval between local sequential requests (seconds).
- S2_MAX_RETRIES=2 # Retry count; 0 disables retries.
- S2_RETRY_DELAY=2 # Initial backoff without Retry-After (seconds).
- S2_MAX_RETRY_DELAY=60 # Maximum wait for a single retry (seconds).
- ```
- Values must be integers from 0 to 99999. Local pacing does not coordinate concurrent processes or devices, so avoid parallel requests when sharing a key. An authenticated author request returning 200 does not guarantee that search endpoints will avoid throttling, and 429 does not mean the key is invalid. If bounded retries fail, wait longer, check other applications using the key, or contact Semantic Scholar about its quota. Paper searches can use `crossref_search.sh` instead. See the [official API tutorial](https://www.semanticscholar.org/product/api/tutorial).
- ### Search during persistent HTTP 429 responses
- ```bash
- bash scripts/search_papers.sh "remote photoplethysmography" 2
- ```
- Automatic fallback searches only CrossRef journal articles, proceedings articles, and posted content such as preprints (`journal-article` / `proceedings-article` / `posted-content`). This excludes supplementary components from paper candidates. Results include `work_type`. Direct calls to `crossref_search.sh` still search all types by default; pass `papers` as the third argument to enable this filter.
- The entry point first runs S2 relevance search. It calls CrossRef only when the final error after retries is HTTP 429. Authentication errors, network errors, and empty results are not hidden by switching sources. If both sources fail, the script exits with a nonzero status and does not emit partial results.
- Each result includes `source`, `search_method`, and `fallback_reason`. S2 results retain author IDs, relevance ordering, and the existing quality fields. CrossRef results explicitly use `source: "crossref"` and `search_method: "bibliographic"`; author IDs, arXiv IDs, and arXiv detection are `null`, while `arxiv_status` is `unknown`. Citation counts belong to their respective sources and are not interchangeable; missing counts are `null`. CrossRef does not provide the S2 author's H-index, so it must not be invented. Candidates still need to be checked against the manuscript's claims, and BibTeX should still be verified using the DOI script.
- This entry point prevents persistent throttling of one source from blocking the whole search. It does not remove S2's server-side limits or guarantee CrossRef availability. The original `s2_search.sh`, `s2_bulk_search.sh`, and `author_info.sh` remain available independently and return failures on persistent HTTP 429 responses.
- ### arXiv citation threshold (optional)
- ```bash
- # Default: 100. Configure it in .env if needed.
- echo 'ARXIV_CITATION_THRESHOLD=100' >> ~/.agents/skills/citation-assistant/.env
- ```
- ---
- ## 📊 Quality assessment dimensions
- | Dimension | Weight | Calculation |
- |-----------|--------|-------------|
- | CCF ranking | Base score | A=100, B=70, C=40 |
- | JCR quartile | Base score | Q1=80, Q2=60, Q3=40, Q4=20 |
- | CAS journal tier | Base score | Tier 1=90, Tier 2=70, Tier 3=50, Tier 4=30 |
- | Impact factor | 30% | IF × 5 (maximum 50) |
- | Citation count | 20% | log₁₀(citations+1) × 10 (maximum 50) |
- | Publication year | 10% | (year−2015) × 2 (maximum 30) |
- | Author H-index | 10% | First author's H-index × 2 (maximum 30) |
- ---
- ## 📖 Usage examples
- These are requests you can make directly in Codex, Claude Code, or Cursor.
- ### Example 1: Find citations for a LaTeX paragraph
- ```text
- I'm writing a paper and need references for this paragraph:
- "Deep learning has achieved remarkable success in medical image analysis, particularly in radiology where chest X-rays are the most commonly performed imaging examination globally [CITE]. Recent advances in vision transformers have further improved performance on these tasks [CITE]."
- Find suitable references for each placeholder.
- ```
- ### Example 2: Assess a journal
- ```text
- I'm considering submitting to TMI (IEEE Transactions on Medical Imaging).
- What is its CCF ranking and impact factor?
- ```
- ### Example 3: Assess an author's academic impact
- ```text
- What is the H-index of this paper's first author? I'd like to assess their academic impact.
- ```
- ### Example 4: Generate BibTeX
- ```text
- Generate BibTeX for this paper:
- DOI: 10.1038/s41591-020-0792-9
- ```
- ### Example 5: Bulk search with a year filter
- ```text
- Find high-quality papers on remote photoplethysmography (rPPG) published from 2020 onward and recommend 10.
- ```
- Use `s2_bulk_search.sh` to retrieve candidates in a batch, then assess them using publication year, citation counts, and venue quality.
- ### Example 6: Review citations in a manuscript paragraph
- Ask the assistant to check the references and suggest better candidates where appropriate:
- ```text
- Remote photoplethysmography (rPPG) enables non-contact heart rate estimation from facial videos [1]. Traditional methods like CHROM and POS have been widely used [2], while recent deep learning approaches have shown superior performance [3].
- [1] Some arXiv paper with 5 citations
- [2] A conference paper from 2015
- [3] Another paper
- ```
- ---
- ## 🧪 Development and validation
- After installing the runtime dependencies, run the following from the repository root. Tests also require Python 3:
- ```bash
- python3 -m unittest discover -s tests -v
- ```
- Tests run in temporary installation directories. They cover paths containing spaces, calls from manuscript directories, configuration loading, local database queries, simulated API searches, author information, HTTP 429 recovery, CrossRef fallback and failures, source labels, and BibTeX. They do not consume real API quota. GitHub Actions runs the same tests on Linux and macOS.
- To reproduce live API validation, configure a key in your local `.env`, then explicitly run:
- ```bash
- python3 tests/live_search_smoke.py --rounds 2
- ```
- See the [S2 HTTP 429 diagnosis notes](docs/s2-rate-limit-diagnosis.md) (in Chinese) for the investigation and known limitations.
- The live test searches three fixed topics sequentially, checks source labels, publication types, and unknown fields, then retrieves BibTeX through DOI resolution. `--rounds` accepts 1–3. It consumes real API quota and can fail when external services are unavailable. CI does not run it, and no key needs to be uploaded.
- ## 🙏 Acknowledgments
- - [Semantic Scholar](https://www.semanticscholar.org/) — Academic paper search API
- - [impact_factor](https://github.com/suqingdong/impact_factor) — Journal impact factor database
- - [CrossRef](https://www.crossref.org/) — DOI metadata API
- ## 📖 Related links
- - [Xiaohongshu tutorial: automating literature citations (Chinese)](https://www.xiaohongshu.com/discovery/item/699eecff000000000d00ab7d?source=webshare&xhsshare=pc_web&xsec_token=ABlbc1XDsjw8TWj8fUipbvyaj7qoU9u73hL5ZmzK4n65c=&xsec_source=pc_share)
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.