Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zhangny301--citation-assistant/badge.svg)](/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

i

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)

  1. ---
  2. name: citation-assistant
  3. description: Use when the user needs academic citations, BibTeX, venue/author quality checks, or help filling [CITE] placeholders. Triggers include 文献引用、找引用、citation、bib、参考文献、替换不规范引用、查询作者 H-index、判断期刊/会议质量。
  4. ---
  5. # Citation Assistant 学术文献引用助手
  6. ## ⚠️ 核心原则
  7. 1. **必须通过 `scripts/` 目录中的脚本执行**,禁止手动编写 curl 命令
  8. 2. **禁止使用 Tavily、WebSearch 等非学术搜索工具**进行文献检索
  9. 3. **语义优先**:理解引用意图,避免仅用关键词检索
  10. 4. **不自动修改文稿**:所有推荐需用户确认后再应用
  11. ---
  12. ## 运行路径(Codex / Claude Code / Cursor)
  13. 以本次加载的 `SKILL.md` 所在目录为 Skill 根目录,**不要使用论文项目的当前工作目录来定位脚本**,也不要假设客户端会注入 `CLAUDE_SKILL_ROOT` 等环境变量。
  14. 下面示例中的 `CITATION_ASSISTANT_ROOT` 是自行设置的 shell 变量:将其设为本次加载的 Skill 的绝对路径(包含 `SKILL.md`、`scripts/` 和 `data/`)。每次新的 shell 调用都需重新设置它,或直接使用脚本的完整绝对路径;路径始终加双引号。
  15. ```bash
  16. # 将此路径替换为本次加载的 SKILL.md 所在目录
  17. CITATION_ASSISTANT_ROOT="/absolute/path/to/citation-assistant"
  18. bash "${CITATION_ASSISTANT_ROOT}/scripts/venue_info.sh" "Nature Medicine"
  19. ```
  20. 脚本从自身位置读取同一安装目录内的 `.env` 和 `data/`,可以在任意论文目录运行。在 Codex 中可通过 `$citation-assistant` 显式调用,也可用自然语言请求引用检索、BibTeX 或期刊质量查询。
  21. ## 📦 可用脚本
  22. 依赖:Bash、`curl`、`jq`、支持 `-json` 的 `sqlite3`。搜索、作者查询和 DOI 转换需要网络;CCF / IF 查询只读本地数据库。
  23. 下表中的相对路径以 Skill 根目录为基准;从论文目录调用时使用上述绝对路径。
  24. | 脚本 | 用途 | 用法 |
  25. |------|------|------|
  26. | `search_papers.sh` | 默认文献检索:S2 搜索持续 429 后自动转 CrossRef,结果带来源 | `bash scripts/search_papers.sh "query" [limit]` |
  27. | `s2_search.sh` | 少量高相关结果检索(含 arXiv 判断) | `bash scripts/s2_search.sh "query" [limit]` |
  28. | `s2_bulk_search.sh` | 批量拉取候选结果并按本地 limit 输出(含 arXiv 判断) | `bash scripts/s2_bulk_search.sh "query" "year_range" limit` |
  29. | `author_info.sh` | 作者信息查询(H-index) | `bash scripts/author_info.sh "author_id"` |
  30. | `venue_info.sh` | 期刊综合查询 | `bash scripts/venue_info.sh "venue_name"` |
  31. | `ccf_lookup.sh` | CCF 分级查询 | `bash scripts/ccf_lookup.sh "venue_name"` |
  32. | `if_lookup.sh` | 影响因子查询 | `bash scripts/if_lookup.sh "journal_name"` |
  33. | `doi2bibtex.sh` | DOI 转 BibTeX | `bash scripts/doi2bibtex.sh "doi"` |
  34. | `crossref_search.sh` | CrossRef 搜索(fallback) | `bash scripts/crossref_search.sh "query" [limit]` |
  35. ---
  36. ## 🆕 增强功能
  37. ### arXiv 文章智能判断
  38. 搜索结果会自动标记 arXiv 文章的引用状态:
  39. | 状态 | 条件 | 推荐建议 |
  40. |------|------|----------|
  41. | `recommended` | arXiv + 引用 ≥ 100 | ✅ 高影响力 arXiv,可引用 |
  42. | `caution` | arXiv + 引用 < 100 | ⚠️ 低引用 arXiv,谨慎引用 |
  43. | `normal` | 正式发表 | ✅ 正式发表 |
  44. **配置引用阈值**(默认 100):
  45. ```bash
  46. export ARXIV_CITATION_THRESHOLD=100
  47. ```
  48. ### 作者信息查询
  49. 搜索结果包含前 3 位作者的 ID,可用于查询 H-index:
  50. ```bash
  51. # 查询作者 H-index、总引用量、论文数
  52. bash "${CITATION_ASSISTANT_ROOT}/scripts/author_info.sh" "18119920"
  53. ```
  54. 返回示例:
  55. ```json
  56. {
  57. "name": "Daquan Zhou",
  58. "hIndex": 25,
  59. "citations": 8500,
  60. "papers": 42
  61. }
  62. ```
  63. ---
  64. ## 🔄 工作流程
  65. ### Step 1: 解析需求
  66. 识别用户需求类型:
  67. - **[CITE] 占位符**:提取上下文,构造语义查询
  68. - **替换不规范引用**:分析原文引用的语义意图
  69. - **期刊查询**:直接查询 CCF/IF 数据库
  70. - **作者质量评估**:查询第一/通讯作者的 H-index
  71. ### Step 2: 语义化查询构造
  72. | 引用目的 | 查询策略示例 |
  73. |----------|--------------|
  74. | 事实背书 | "chest radiography most widely used imaging test globally statistics" |
  75. | 方法引用 | "attention mechanism transformer neural machine translation" |
  76. | 背景介绍 | "deep learning medical image analysis survey review" |
  77. ### Step 3: 执行搜索
  78. - 日常文献检索优先使用 `search_papers.sh`:S2 相关性搜索,持续 429 时自动转 CrossRef;若用户明确只接受 S2 数据,则使用 `s2_search.sh`
  79. - 需要减少请求次数、批量拉取候选结果并再做筛选时,使用 `s2_bulk_search.sh`
  80. ```bash
  81. # 默认检索入口(自动处理 S2 持续限流)
  82. bash "${CITATION_ASSISTANT_ROOT}/scripts/search_papers.sh" "YOUR_QUERY" 10
  83. # 批量候选结果(bulk endpoint),再由脚本按 limit 输出前 N 条
  84. bash "${CITATION_ASSISTANT_ROOT}/scripts/s2_bulk_search.sh" "YOUR_QUERY" "2020-" 20
  85. ```
  86. **直接使用原始 S2 脚本且返回 429 错误时**,可显式使用 CrossRef fallback(`search_papers.sh` 已自动处理):
  87. ```bash
  88. bash "${CITATION_ASSISTANT_ROOT}/scripts/crossref_search.sh" "YOUR_QUERY" 20
  89. ```
  90. 自动降级限定期刊论文、会议论文与预印本类记录;检查 CrossRef 的 `work_type`,预印本不能当作已正式发表。
  91. 检查 `source` / `search_method`:CrossRef 结果属于独立来源的文献匹配,不应描述为 S2 的相关性排名。其作者 ID、arXiv 判断等不可用字段为 `null` / `unknown`,不要调用 `author_info.sh` 查询空 ID,也不要补造 H-index。引用量必须标注数据来源,不直接混用不同来源的计数。降级后的结果同样需要核实是否支持原文观点。
  92. ### Step 4: 评估文献质量
  93. ```bash
  94. # 查询期刊质量
  95. bash "${CITATION_ASSISTANT_ROOT}/scripts/venue_info.sh" "Nature Medicine"
  96. # 查询作者 H-index
  97. bash "${CITATION_ASSISTANT_ROOT}/scripts/author_info.sh" "AUTHOR_ID"
  98. ```
  99. ### Step 5: 生成 BibTeX
  100. ```bash
  101. bash "${CITATION_ASSISTANT_ROOT}/scripts/doi2bibtex.sh" "10.1038/s41591-020-0792-9"
  102. ```
  103. ### Step 6: 生成中文推荐报告
  104. 输出格式示例:
  105. ```markdown
  106. ## 引用推荐报告
  107. ### [CITE] 位置 1
  108. **原文上下文**:
  109. > In chest radiography---arguably the most widely used imaging test globally [CITE]---
  110. **推荐文献**:
  111. #### 推荐 1: Wu2020 - CheXpert: A large chest radiograph dataset...
  112. **质量指标**:
  113. | 维度 | 值 | 说明 |
  114. |------|-----|------|
  115. | CCF 分级 | N/A | 非CS领域期刊 |
  116. | JCR 分区 | Q1 | 顶级医学影像期刊 |
  117. | 影响因子 | 29.1 | 极高影响力 |
  118. | 引用量 | 3500+ | 高被引文献 |
  119. | arXiv 状态 | normal | 正式发表 |
  120. **推荐理由**:顶级期刊发表,直接支持原文论点。
  121. **BibTeX**:
  122. ```bibtex
  123. @article{Wu2020, ... }
  124. ```
  125. **建议用法**:将 `[CITE]` 替换为 `~\cite{Wu2020}`
  126. ```
  127. ---
  128. ## ⚙️ 配置
  129. ### Semantic Scholar API Key(强烈推荐)
  130. ```bash
  131. # 在 Skill 目录创建 .env 文件
  132. echo 'S2_API_KEY="your_key_here"' > "${CITATION_ASSISTANT_ROOT}/.env"
  133. # 获取 API Key: https://www.semanticscholar.org/product/api/api-key
  134. ```
  135. | 模式 | 速率限制 | 推荐场景 |
  136. |------|----------|----------|
  137. | 有 API Key | 1 次/秒 | 日常使用(推荐) |
  138. | 无 API Key | 共享限额 | 极易触发 429 |
  139. ### arXiv 引用阈值(可选)
  140. ```bash
  141. # 默认 100,可在 .env 中配置
  142. echo 'ARXIV_CITATION_THRESHOLD=100' >> "${CITATION_ASSISTANT_ROOT}/.env"
  143. ```
  144. ---
  145. ## 🚨 错误处理
  146. ### 429 Rate Limit
  147. 1. S2 脚本已自动进行有界重试(默认最多 2 次),优先遵守 `Retry-After`;不要连续重复调用或把 429 当作无效密钥
  148. 2. 仍失败时等待更长时间,并说明当前接口受限;带 Key 或切换 bulk 接口也不保证解除限流
  149. 3. 论文检索可使用 `crossref_search.sh` fallback;作者 H-index 无此替代,无法获取时明确标记未知
  150. ### 401 / 403
  151. 脚本不重试认证或权限错误。检查 Skill 目录的 `.env` / `S2_API_KEY` 及接口权限,不输出密钥。
  152. ### 无搜索结果
  153. 1. 简化关键词
  154. 2. 使用英文查询
  155. 3. 尝试 CrossRef fallback
  156. ---
  157. ## 📊 质量评估维度
  158. | 维度 | 权重 | 计算 |
  159. |------|------|------|
  160. | CCF 分级 | 基础分 | A=100, B=70, C=40 |
  161. | JCR 分区 | 基础分 | Q1=80, Q2=60, Q3=40, Q4=20 |
  162. | 中科院分区 | 基础分 | 1区=90, 2区=70, 3区=50, 4区=30 |
  163. | 影响因子 | 30% | IF × 5 (上限50) |
  164. | 引用量 | 20% | log₁₀(citations+1) × 10 (上限50) |
  165. | 年份 | 10% | (year-2015) × 2 (上限30) |
  166. | 作者 H-index | 10% | 第一作者 H-index × 2 (上限30) |
  167. **arXiv 处理**:
  168. - 引用 ≥ 100:正常评分
  169. - 引用 < 100:降低优先级 (-20 分)
  170. - 有正式发表版本优先
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)

  1. # Citation Assistant
  2. English | [简体中文](README.zh-CN.md)
  3. > An academic citation assistant for Codex, Claude Code, and Cursor, designed for manuscript writing, BibTeX generation, and literature quality assessment.
  4. 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.
  5. This repository serves two audiences:
  6. - **GitHub users**: read `README.md` or `README.zh-CN.md` for features, installation, and examples.
  7. - **Skill runtimes (Codex / Claude Code / Cursor)**: read `SKILL.md` and follow its scripts and workflow.
  8. ---
  9. ## ✨ Features
  10. | Feature | Description |
  11. |---------|-------------|
  12. | 🔍 **Context-aware literature search** | Use Semantic Scholar to find papers relevant to the citation's context, with queries constructed by the assistant. |
  13. | 🛡️ **Reference verification** | Retrieve BibTeX through DOI resolution to verify references instead of inventing citation metadata. |
  14. | 📊 **Quality assessment** | Review venue metrics (CCF ranking, JCR quartile, CAS tier, impact factor) and author metrics (H-index, citation count). |
  15. | 📝 **BibTeX generation** | Generate BibTeX entries for use in LaTeX documents. |
  16. | 📋 **Recommendation reports** | Present structured results and explain why each candidate fits the manuscript. |
  17. ---
  18. ## 🚀 Installation
  19. 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.
  20. ### Codex
  21. Install for your user account to make the Skill available across projects:
  22. ```bash
  23. mkdir -p ~/.agents/skills
  24. git clone https://github.com/ZhangNy301/citation-assistant.git ~/.agents/skills/citation-assistant
  25. # Optional: create .env in the installation directory and enter your S2_API_KEY.
  26. # Do not overwrite an existing .env file.
  27. cp -n ~/.agents/skills/citation-assistant/.env.example ~/.agents/skills/citation-assistant/.env
  28. ```
  29. Alternatively, install only for a manuscript project by running the following from that project's root. Choose either this or the user-level installation:
  30. ```bash
  31. mkdir -p .agents/skills
  32. git clone https://github.com/ZhangNy301/citation-assistant.git .agents/skills/citation-assistant
  33. ```
  34. Invoke the Skill in Codex:
  35. ```text
  36. $citation-assistant Assess the quality of Nature Medicine and explain the sources of the metrics.
  37. ```
  38. 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.
  39. Verify a user-level installation from any manuscript directory, without network access:
  40. ```bash
  41. bash "$HOME/.agents/skills/citation-assistant/scripts/venue_info.sh" "Nature Medicine"
  42. ```
  43. 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`.
  44. ### Claude Code
  45. ```bash
  46. # Clone the repository.
  47. git clone https://github.com/ZhangNy301/citation-assistant.git
  48. # Copy the Skill into Claude Code's skills directory.
  49. mkdir -p ~/.claude/skills/citation-assistant
  50. cp citation-assistant/SKILL.md ~/.claude/skills/citation-assistant/
  51. cp -r citation-assistant/scripts ~/.claude/skills/citation-assistant/
  52. cp -r citation-assistant/data ~/.claude/skills/citation-assistant/
  53. # Configure an API key (recommended).
  54. echo 'S2_API_KEY="your_key_here"' > ~/.claude/skills/citation-assistant/.env
  55. ```
  56. ### Cursor
  57. ```bash
  58. # Create the skills directory and clone the repository.
  59. mkdir -p ~/.cursor/skills
  60. cd ~/.cursor/skills
  61. git clone https://github.com/ZhangNy301/citation-assistant.git
  62. # Configure an API key (recommended).
  63. echo 'S2_API_KEY="your_key_here"' > ~/.cursor/skills/citation-assistant/.env
  64. ```
  65. Request an API key from [Semantic Scholar](https://www.semanticscholar.org/product/api).
  66. ---
  67. ## 📦 Available scripts
  68. | Script | Purpose | Usage |
  69. |--------|---------|-------|
  70. | `search_papers.sh` | Default search: S2 relevance search, then CrossRef after persistent HTTP 429 responses | `bash scripts/search_papers.sh "query" [limit]` |
  71. | `s2_search.sh` | Retrieve a small set of relevant S2 results, including arXiv status | `bash scripts/s2_search.sh "query" [limit]` |
  72. | `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` |
  73. | `author_info.sh` | Look up an author's H-index | `bash scripts/author_info.sh "author_id"` |
  74. | `venue_info.sh` | Query combined venue quality metrics | `bash scripts/venue_info.sh "venue_name"` |
  75. | `ccf_lookup.sh` | Look up CCF rankings | `bash scripts/ccf_lookup.sh "venue_name"` |
  76. | `if_lookup.sh` | Look up journal impact factors | `bash scripts/if_lookup.sh "journal_name"` |
  77. | `doi2bibtex.sh` | Convert a DOI to BibTeX | `bash scripts/doi2bibtex.sh "doi"` |
  78. | `crossref_search.sh` | Search CrossRef directly as a fallback | `bash scripts/crossref_search.sh "query" [limit]` |
  79. > 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.
  80. ---
  81. ## 🆕 Additional capabilities
  82. ### arXiv citation assessment
  83. S2 search results are labeled according to their arXiv status and citation count:
  84. | Status | Condition | Recommendation |
  85. |--------|-----------|----------------|
  86. | `recommended` | arXiv paper with ≥ 100 citations | ✅ Highly cited arXiv paper; consider citing. |
  87. | `caution` | arXiv paper with < 100 citations | ⚠️ Low citation count; assess carefully. |
  88. | `normal` | Not identified as arXiv by the venue check | Check the publication venue and version. |
  89. ### Author information
  90. S2 search results include IDs for the first three authors, which can be used to look up their H-indices:
  91. ```bash
  92. bash scripts/author_info.sh "18119920"
  93. ```
  94. Example response:
  95. ```json
  96. {
  97. "name": "Daquan Zhou",
  98. "hIndex": 25,
  99. "citations": 8500,
  100. "papers": 42
  101. }
  102. ```
  103. ---
  104. ## 📁 Repository structure
  105. ```text
  106. citation-assistant/
  107. ├── SKILL.md # Skill instructions
  108. ├── README.md # English documentation (this file)
  109. ├── README.zh-CN.md # Chinese documentation
  110. ├── CHANGELOG.md # Version history
  111. ├── .env.example # Configuration template
  112. ├── agents/openai.yaml # Codex display metadata and default prompt
  113. ├── tests/ # Offline installation and script regression tests
  114. ├── scripts/ # Shell scripts
  115. │ ├── init.sh
  116. │ ├── s2_request.sh # S2 requests, pacing, and bounded retries
  117. │ ├── search_papers.sh # Default search with labeled S2 → CrossRef fallback
  118. │ ├── s2_search.sh
  119. │ ├── s2_bulk_search.sh
  120. │ ├── author_info.sh
  121. │ ├── venue_info.sh
  122. │ ├── ccf_lookup.sh
  123. │ ├── if_lookup.sh
  124. │ ├── doi2bibtex.sh
  125. │ └── crossref_search.sh
  126. └── data/ # Databases
  127. ├── ccf_2026.sqlite
  128. ├── ccf_2026.jsonl
  129. └── impact_factor.sqlite3
  130. ```
  131. ---
  132. ## 🔧 Configuration
  133. ### Semantic Scholar API key
  134. Request a key from [Semantic Scholar](https://www.semanticscholar.org/product/api).
  135. | Mode | Rate limit |
  136. |------|------------|
  137. | With an API key | Initial allowance of 1 request/second across endpoints; throttling can still occur. |
  138. | Without an API key | Shared quota; HTTP 429 responses are common. |
  139. 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.
  140. ### Semantic Scholar rate limiting and retries
  141. 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.
  142. Configure these settings in the Skill's `.env`:
  143. ```bash
  144. S2_MIN_INTERVAL=1 # Minimum interval between local sequential requests (seconds).
  145. S2_MAX_RETRIES=2 # Retry count; 0 disables retries.
  146. S2_RETRY_DELAY=2 # Initial backoff without Retry-After (seconds).
  147. S2_MAX_RETRY_DELAY=60 # Maximum wait for a single retry (seconds).
  148. ```
  149. 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).
  150. ### Search during persistent HTTP 429 responses
  151. ```bash
  152. bash scripts/search_papers.sh "remote photoplethysmography" 2
  153. ```
  154. 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.
  155. 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.
  156. 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.
  157. 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.
  158. ### arXiv citation threshold (optional)
  159. ```bash
  160. # Default: 100. Configure it in .env if needed.
  161. echo 'ARXIV_CITATION_THRESHOLD=100' >> ~/.agents/skills/citation-assistant/.env
  162. ```
  163. ---
  164. ## 📊 Quality assessment dimensions
  165. | Dimension | Weight | Calculation |
  166. |-----------|--------|-------------|
  167. | CCF ranking | Base score | A=100, B=70, C=40 |
  168. | JCR quartile | Base score | Q1=80, Q2=60, Q3=40, Q4=20 |
  169. | CAS journal tier | Base score | Tier 1=90, Tier 2=70, Tier 3=50, Tier 4=30 |
  170. | Impact factor | 30% | IF × 5 (maximum 50) |
  171. | Citation count | 20% | log₁₀(citations+1) × 10 (maximum 50) |
  172. | Publication year | 10% | (year−2015) × 2 (maximum 30) |
  173. | Author H-index | 10% | First author's H-index × 2 (maximum 30) |
  174. ---
  175. ## 📖 Usage examples
  176. These are requests you can make directly in Codex, Claude Code, or Cursor.
  177. ### Example 1: Find citations for a LaTeX paragraph
  178. ```text
  179. I'm writing a paper and need references for this paragraph:
  180. "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]."
  181. Find suitable references for each placeholder.
  182. ```
  183. ### Example 2: Assess a journal
  184. ```text
  185. I'm considering submitting to TMI (IEEE Transactions on Medical Imaging).
  186. What is its CCF ranking and impact factor?
  187. ```
  188. ### Example 3: Assess an author's academic impact
  189. ```text
  190. What is the H-index of this paper's first author? I'd like to assess their academic impact.
  191. ```
  192. ### Example 4: Generate BibTeX
  193. ```text
  194. Generate BibTeX for this paper:
  195. DOI: 10.1038/s41591-020-0792-9
  196. ```
  197. ### Example 5: Bulk search with a year filter
  198. ```text
  199. Find high-quality papers on remote photoplethysmography (rPPG) published from 2020 onward and recommend 10.
  200. ```
  201. Use `s2_bulk_search.sh` to retrieve candidates in a batch, then assess them using publication year, citation counts, and venue quality.
  202. ### Example 6: Review citations in a manuscript paragraph
  203. Ask the assistant to check the references and suggest better candidates where appropriate:
  204. ```text
  205. 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].
  206. [1] Some arXiv paper with 5 citations
  207. [2] A conference paper from 2015
  208. [3] Another paper
  209. ```
  210. ---
  211. ## 🧪 Development and validation
  212. After installing the runtime dependencies, run the following from the repository root. Tests also require Python 3:
  213. ```bash
  214. python3 -m unittest discover -s tests -v
  215. ```
  216. 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.
  217. To reproduce live API validation, configure a key in your local `.env`, then explicitly run:
  218. ```bash
  219. python3 tests/live_search_smoke.py --rounds 2
  220. ```
  221. See the [S2 HTTP 429 diagnosis notes](docs/s2-rate-limit-diagnosis.md) (in Chinese) for the investigation and known limitations.
  222. 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.
  223. ## 🙏 Acknowledgments
  224. - [Semantic Scholar](https://www.semanticscholar.org/) — Academic paper search API
  225. - [impact_factor](https://github.com/suqingdong/impact_factor) — Journal impact factor database
  226. - [CrossRef](https://www.crossref.org/) — DOI metadata API
  227. ## 📖 Related links
  228. - [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)
  229. ## License
  230. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.