agentleFS
tansuasicitansuasici/claude-research-kit/.claude/skills/citation-audit/SKILL.md

citation-audit

Skill4 starsChanged 6 months agoMITView on GitHub

Deep manual bibliography health check — dangling \cite keys, orphan .bib entries, duplicates, malformed/placeholder DOIs, missing required fields, inconsistent author/journal formatting, and \ref↔\label integrity

10 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use figure-spec, comm-lit-review-claude-single and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • raja21068Skill

    figure-spec

    Generate deterministic publication-quality architecture, workflow, and pipeline diagrams from structured JSON (FigureSpec) into editable SVG. Use when user says \"架构图\", \"workflow 图\", \"pipeline 图\", \"确定性矢量图\", \"figure spec\", \"draw architecture\", or needs precise, editable, publication-ready vector diagrams. Preferred over AI illustration for formal architecture/workflow figures.

    Also in 4 projects that use this

  • raja21068Skill

    comm-lit-review-claude-single

    Communications-domain literature review with Claude-style knowledge-base-first retrieval. Use when the task is about communications, wireless, networking, satellite/NTN, Wi-Fi, cellular, transport protocols, congestion control, routing, scheduling, MAC/PHY, rate adaptation, channel estimation, beamforming, or communication-system research and the user wants papers, related work, a survey, or a landscape summary. Search Zotero, Obsidian, and local paper folders first when available, then search IEEE Xplore, ScienceDirect, ACM Digital Library, and broader web in that order.

    Also in 3 projects that use this

  • rongaredeSkill

    semantic-scholar

    使用 Semantic Scholar API 检索和验证学术论文。支持并发多关键词搜索、批量 ID/DOI 查询、引用分析、批量补全摘要、统一 Markdown 导出。覆盖 2.14 亿+ 学术论文,无需 API Key 即可使用。触发词:论文检索、论文验证、Semantic Scholar、S2 搜索、查论文、补全摘要、导出MD

    Also in 4 projects that use this

  • Yusong-EnceladusSkill

    feishu-notify

    Send notifications to Feishu/Lark. Internal utility used by other skills, or manually via /feishu-notify. Supports push-only (webhook) and interactive (bidirectional) modes. Use when user says \"发飞书\", \"notify feishu\", or other skills need to send status updates.

    Also in 3 projects that use this

  • +8 more from raja21068

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 10 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Do not silently rewrite all of these — reference style conversion is a deterministic job for a CSL processor / biber (CLAUDE.md → Model vs …

    line 87
  2. Distinctive:

    Never assert a DOI is valid because it is well-shaped — shape ≠ existence.

    line 143
  3. Very specific:

    When converting reference styles, route the mechanical work through biber/a CSL processor.

    line 144

“Common” is measured: kept by at least 6 in 10 of the 10 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Citation Audit

Core Rule

The bibliography is deterministic infrastructure: a \cite either resolves or it does not; a DOI is either well-formed or it is not. Per CLAUDE.md → Model vs Code, do not eyeball what a parser can decide. This skill is the deeper manual audit that complements the live hook — it catches the structural problems the gate does not (orphans, duplicates, malformed metadata, formatting drift) and reasons about fixes.

For the live \cite↔.bib and \ref↔\label check, the citation-gate.sh hook already runs after every .tex/.bib edit and writes its verdict to .hook-state/last_quality_gate.json. Tell the user to rely on that hook for continuous coverage; run /citation-audit for a thorough sweep before submission or when inheriting a messy .bib.

Never fix a dangling key by inventing a reference. A \cite{key} with no entry is resolved either by supplying verified metadata or by flagging [CITE] in the prose and removing the dead key — never by writing a plausible stub. block-fabrication.sh will block the stub anyway.

When to Use

Invoke with /citation-audit when:

  • Preparing to submit — a clean bibliography is a Reviewer 2 freebie you should not give away.
  • You merged a co-author's .bib and suspect duplicates or format drift.
  • The citation-gate verdict shows dangling keys and you want the full structural picture, not just the first 25.
  • Switching reference styles (ACS ↔ IEEE ↔ APA) and need to audit field completeness first.

Process

Phase 1: Inventory

Locate the manuscript root (nearest ancestor with a .bib, main.tex, or MANUSCRIPT_MAP.md) and inventory:

  1. All .bib files — there may be more than one; the gate scans all of them.
  2. All .tex/.ltx files — the sources of \cite and \ref.
  3. Reference style in force — from MANUSCRIPT_MAP.md → Target journal (ACS / IEEE / APA / Nature). This sets which fields are required and the expected author/journal format.

Strip TeX comments before counting: a commented-out % \cite{foo} is not a real citation. (The gate does this; match its behaviour.)

Phase 2: Resolution Integrity (\cite ↔ .bib)

The same check the hook runs, surfaced in full:

  1. Defined keys — parse @type{key, from every .bib (skip @string/@comment/@preamble).
  2. Cited keys — parse the full \cite family from every .tex: \cite \citep \citet \citeauthor \autocite \textcite \parencite \footcite and friends, including multi-key braces {a,b,c} and optional [..] arguments.
  3. Dangling cites — cited but not defined → ERROR. Each is a fabrication risk: resolve with verified metadata or flag [CITE] and remove the key. Do NOT invent the entry.
  4. Orphan entries — defined but never cited → WARNING. Dead weight; remove unless deliberately retained (e.g. a \nocite{*} data-availability list — note the exception).

Phase 3: Duplicate Detection

Duplicates produce double-counted references and inconsistent keys:

  1. Same key twice — a hard .bib error; biber/bibtex picks one silently. ERROR.
  2. Same work, different keys — match on DOI, then on (normalized title + year + first author). Two keys for one paper means the manuscript cites it inconsistently. WARNING — merge to one key and update all \cite sites.
  3. Near-duplicate titles — preprint vs published version of the same work. Flag for the author to pick the citeable version.

Phase 4: DOI and Identifier Validity

  1. Placeholder / fake-shaped DOIs — 10.xxxx, 10.0000, 10.nnnn, example.com, your-doi, TODO → ERROR. (block-fabrication.sh blocks these on write; catch any that predate the hook.) Flag, never "complete" them.
  2. Malformed DOIs — must match 10.<registrant>/<suffix>. A DOI that is not shaped like one is suspect.
  3. arXiv / ISSN shape — sanity-check format. Do not assert a DOI "resolves" unless you verified it against a real source — shape validity is not existence.

Phase 5: Required-Field Completeness (per entry type)

Each @type has required fields; a missing one is a malformed reference. Check against the style in force:

Entry typeRequired (BibTeX core)
@articleauthor, title, journal, year, (volume)
@bookauthor/editor, title, publisher, year
@incollectionauthor, title, booktitle, publisher, year
@inproceedingsauthor, title, booktitle, year
@phdthesisauthor, title, school, year
@techreportauthor, title, institution, year
@misctitle + (howpublished/url/year) for datasets, software, preprints

An empty required field (author = {}) is a stub masquerading as real → ERROR (the hook blocks writing these). A missing required field → WARNING. Supply the value only from the actual source.

Phase 6: Formatting Consistency

Drift here is what a copy-editor (and Reviewer 2) flags:

  1. Author name format — one convention throughout (Last, First vs First Last; initials with/without periods; and separators). List the outliers.
  2. Journal names — full vs abbreviated, consistently. ACS/IEEE expect ISO-4 abbreviations; APA/Nature expect full titles. Match the style.
  3. Title case — sentence case vs title case per style; brace-protection on proper nouns/acronyms ({LLM}, {API}) so they aren't down-cased.
  4. Page ranges — -- en-dash, consistent.
  5. Capitalization protection — model names, acronyms, proper nouns wrapped in {}.

Do not silently rewrite all of these — reference style conversion is a deterministic job for a CSL processor / biber (CLAUDE.md → Model vs Code). Report the inconsistencies and the rule; mechanical reformat belongs in tooling, not hand-retyping that injects errors.

Phase 7: Cross-Reference Integrity (\ref ↔ \label)

  1. Dangling refs — \ref \eqref \autoref \cref \Cref \pageref \nameref keys with no matching \label → ERROR.
  2. Orphan labels — \label never referenced → WARNING (often harmless, but flag stale ones).
  3. Display-item coverage — every figure/table is referenced in the text and vice versa (cross-check MANUSCRIPT_MAP.md → Figures & tables). An unreferenced figure or a "see Fig 3" with no Fig 3 is a defect.

Output Format

# Citation Audit — references.bib (+ 1 other .bib), 6 .tex files

> Live check: citation-gate.sh (runs on every .tex/.bib edit). This is the deep manual sweep.
> Reference style in force: ACL (numbered, ISO-4 abbreviations, sentence-case titles).

## ERRORS (block submission)
| Category | Item | Fix |
|---|---|---|
| Dangling \cite | `smith2022` cited in results.tex:88, not in any .bib | Supply verified entry OR flag [CITE] and remove key — do not invent |
| Duplicate key | `halluc2022` defined twice in references.bib | Merge; keep the complete entry |
| Placeholder DOI | `kumar2020`: doi = {10.xxxx/abcd} | Replace with real DOI from source, or drop the field |
| Empty field | `lee2018`: author = {} | Fill author from source or remove entry |
| Dangling \ref | `\ref{fig:horizon}` in discussion.tex:40, no \label | Add \label or fix the reference |

## WARNINGS (fix before submission)
| Category | Item | Fix |
|---|---|---|
| Orphan entry | `garcia2015` defined, never cited | Remove unless intentionally retained |
| Same work, 2 keys | `wang2021a` / `wang2021b` share DOI 10.18653/... | Merge to one key; update \cite sites |
| Author format | 3 entries use "First Last", rest "Last, First" | Normalize via biber, not by hand |
| Journal abbrev | `nguyen2020` uses full journal name; ACL wants ISO-4 | Abbreviate per ACL |
| Unreferenced figure | fig:appendixB has \label, never \ref'd | Reference it in text or move to appendix |

## Counts
- Cite keys: 47 cited / 52 defined → 5 orphans, 1 dangling
- DOIs: 41 present / 1 placeholder / 6 missing
- Cross-refs: 19 \ref / 19 \label → 1 dangling, 2 orphan labels

## Recommended fix order
1. Resolve the dangling \cite and \ref (blocks compile + the stop-gate).
2. Merge duplicate/same-work keys.
3. Replace placeholder DOI; fill empty required fields from sources.
4. Run biber/CSL to normalize author + journal formatting (deterministic — don't hand-edit).

Pairs With

  • citation-gate.sh — the live, every-edit check (Phases 2 + 7). This skill goes deeper (Phases 3–6) and explains fixes. Read its verdict at .hook-state/last_quality_gate.json.
  • stop-gate.sh — blocks turn completion while the last gate failed. A clean audit clears it. Bypass only with SKIP_QUALITY_GATE=1 for a pre-existing, unrelated dangling key.
  • block-fabrication.sh — blocks writing placeholder DOIs / empty .bib fields. If a "fix" trips it, the fix was a fabrication.
  • /claim-check — structural integrity here ≠ a cite licensing its claim. Run claim-check for the source-reading layer.

Notes

  • Counting and key-resolution are deterministic — prefer a quick python3 parse over reasoning about which keys match. Reserve judgment for "are these two entries the same work?" and "is this orphan intentional?"
  • Never assert a DOI is valid because it is well-shaped — shape ≠ existence. Verification against the real source is a separate, manual step.
  • When converting reference styles, route the mechanical work through biber/a CSL processor; this skill audits, it does not retype the bibliography.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.