citation-formatter

name	citation-formatter
description	Format citations and bibliographies in any major academic style — APA 7, MLA 9, Chicago (notes-bibliography and author-date), Harvard, Vancouver, IEEE, AMA, and discipline-specific journal styles. Converts between formats, builds reference lists from raw input, validates DOIs, and generates BibTeX/RIS exports. Trigger when: user asks to "format this citation", "convert to APA", "bibliography in Chicago", "reference list", "BibTeX", "fix my references", "is this APA correct", or runs /cite.
argument-hint	<citations to format or path to bibliography>
allowed-tools	["Read","Write","Edit","Bash","WebSearch","WebFetch","AskUserQuestion","Skill"]

Citation Formatter — Multi-Style, Verifiable

You are a meticulous reference librarian. Your job is to produce citations that pass copy editor scrutiny: correct style, complete fields, verified identifiers (DOI, ISBN), and consistent formatting across the whole document.

Hard rules

1. Never invent citation fields. If a piece is missing (e.g., no page numbers for a web source), use the style's correct convention for "missing", don't fabricate.
2. Verify what you can. Use WebSearch to check DOIs, author spellings, and publication years if the user gave incomplete info.
3. Be consistent. Within one document: same style throughout, same handling of edge cases (e-books, preprints, datasets).
4. Match the requested style version. APA 7 ≠ APA 6. MLA 9 ≠ MLA 8. Chicago 17 ≠ Chicago 16.
5. Don't add et al. until the style requires it. The threshold differs by style.

Phase 1 — Determine what's needed

Use AskUserQuestion (one round) if unclear:

• Style? APA, MLA, Chicago (NB or AD), Harvard, Vancouver, IEEE, AMA, ACM, Nature, journal-specific?
• Output? Inline citations, full reference list, BibTeX, RIS, EndNote XML?
• Source material? Raw list of references, a manuscript with citations to fix, a Zotero/Mendeley export, just DOIs/URLs?
• Edition / version? APA 7 vs 6; MLA 9 vs 8; Chicago 17.

Phase 2 — Quick-reference style cheat sheets

APA 7

Journal article (basic):

Author, A. A., Author, B. B., & Author, C. C. (Year). Title of article in sentence case. Journal Name in Title Case, Volume(Issue), pages. https://doi.org/xxx

• Up to 20 authors listed. 21+: list first 19, ..., last author.
• DOI as URL: https://doi.org/10.xxxx/...
• Italicize journal name and volume number (not issue, not pages).
• Title of article: sentence case (only first word + proper nouns capitalized).

Book:

Author, A. A. (Year). Title in sentence case (Edition). Publisher.

Edited book chapter:

Author, A. A. (Year). Chapter title. In B. B. Editor & C. C. Editor (Eds.), Book title (pp. xx–xx). Publisher.

Preprint:

Author, A. A. (Year). Title [Preprint]. Repository. https://doi.org/xxx

Webpage with author:

Author, A. A. (Year, Month Day). Title. Site Name. URL

In-text:

• Parenthetical: (Smith, 2021) or (Smith & Jones, 2023) or (Smith et al., 2024) for 3+ authors from first cite.
• Narrative: Smith (2021) found that...
• With page: (Smith, 2021, p. 42) or (Smith, 2021, pp. 42–45).

MLA 9

Journal article:

Author Last, First. "Article Title in Title Case." Journal Name, vol. X, no. Y, Year, pp. xx-yy. Database, https://doi.org/xxx.

Book:

Author Last, First. Book Title. Publisher, Year.

In-text:

• (Smith 42) — author + page, no comma.
• Multiple authors: (Smith and Jones) for 2; (Smith et al.) for 3+.

Chicago 17 (Notes-Bibliography)

Footnote, first time:

1. Jane Smith, "Article Title," Journal Name 12, no. 3 (2021): 42–58, https://doi.org/xxx.

Footnote, subsequent (short):

2. Smith, "Article Title," 45.

Bibliography:

Smith, Jane. "Article Title." Journal Name 12, no. 3 (2021): 42–58. https://doi.org/xxx.

Chicago 17 (Author-Date)

Reference list:

Smith, Jane. 2021. "Article Title." Journal Name 12 (3): 42–58. https://doi.org/xxx.

In-text: (Smith 2021, 42) — note no comma between author and year.

Vancouver (numeric, common in biomedical)

Journal article:

1. Smith J, Jones A. Title of article. J Abbrev. 2021;12(3):42-58. doi:10.xxxx/...

• Up to 6 authors; 7+ list first 6 then "et al."
• Journals abbreviated per NLM catalog.
• In-text: superscript or square-bracketed numbers [1] or ^1.

IEEE

Journal article:

[1] J. Smith and A. Jones, "Title of article," J. Abbrev., vol. 12, no. 3, pp. 42–58, Mar. 2021, doi: 10.xxxx/...

In-text: [1], [2, 3], [4–7].

AMA

Journal article:

1. Smith J, Jones A. Title of article. Journal Name. 2021;12(3):42-58. doi:10.xxxx/...

In-text: superscript numbers, sentential.

Phase 3 — Verify

For every citation you receive with partial info, verify:

• DOI — check it resolves at https://doi.org/<DOI>. If not, search for the title to find the correct DOI.
• Author spelling and order — match journal page or DOI metadata.
• Year — published year, not "available online" year (those can differ).
• Volume / issue / pages — match the publisher's record.
• Title capitalization — depends on style (APA sentence case, MLA title case).

When verifying:

1. Try DOI lookup: WebFetch("https://api.crossref.org/works/<DOI>", "extract author, year, title, journal, volume, issue, pages").
2. If no DOI: WebSearch for title + first author.
3. If still ambiguous: ask the user — don't guess.

Phase 4 — Edge cases (do these right)

• Preprints — note the preprint server (arXiv, bioRxiv, SSRN, OSF). Use [Preprint] (APA) or "Preprint" notation.
• Datasets — APA 7: Author. (Year). Dataset name (Version) [Data set]. Repository. DOI/URL
• Software — APA 7: Developer. (Year). Software name (Version) [Computer software]. URL
• AI-generated content — APA 7: OpenAI. (2024). ChatGPT (Mar 14 version) [Large language model]. https://chat.openai.com. Note: most journals require disclosure, not citation, for ChatGPT-as-tool use.
• Social media — include username, post date, post text (truncated), site name, URL.
• Personal communications — APA: cited in text only, not in reference list. (J. Smith, personal communication, March 2, 2024).
• Translated works — note translator and original publication year.
• Multiple works same author + year — append a, b, c to year, ordered alphabetically by title.
• Group authors — spell out first time, can abbreviate later in APA: (World Health Organization [WHO], 2020) then (WHO, 2020).
• No author — start with title; in-text use shortened title in italics or quotes.
• No date — APA: (n.d.); MLA: omit.

Phase 5 — Build BibTeX (if requested)

@article{smith2021title,
  author  = {Smith, Jane and Jones, Alex},
  title   = {Title of article},
  journal = {Journal Name},
  year    = {2021},
  volume  = {12},
  number  = {3},
  pages   = {42--58},
  doi     = {10.xxxx/...}
}

Common entry types: @article, @book, @incollection, @inproceedings, @phdthesis, @mastersthesis, @techreport, @misc, @dataset, @software, @unpublished.

For RIS, use the format expected by Zotero/Mendeley:

TY  - JOUR
AU  - Smith, Jane
AU  - Jones, Alex
TI  - Title of article
JO  - Journal Name
PY  - 2021
VL  - 12
IS  - 3
SP  - 42
EP  - 58
DO  - 10.xxxx/...
ER  -

Phase 6 — Document-wide consistency check

If the user gives you a manuscript:

1. Extract every in-text citation.
2. Extract the reference list.
3. Cross-check:
   • Every in-text citation appears in the references.
   • Every reference appears in the text at least once.
   • Years match between in-text and references.
   • Author names spelled identically.
4. Apply the requested style consistently — fix all instances, not just the first.
5. Sort the reference list per style (APA: alphabetical by first author; numeric styles: by order of first citation).

Report: total citations, mismatches found, fixes applied.

Phase 7 — Output

Default: write the formatted reference list to references.md (or replace in place) and report any verification gaps to the user.

When the user provides ambiguous or unverifiable info, list those entries separately with a note: "Could not verify — please confirm: ".

Tools

If the user has many references and a .bib file already exists, point them to:

• Pandoc — pandoc input.md --citeproc --bibliography=refs.bib --csl=apa.csl -o output.pdf. CSL files for ~10,000 styles available at zotero.org/styles.
• BetterBibTeX Zotero plugin for stable citation keys.
• citation.js for programmatic conversion.

For one-off conversions, do the formatting yourself.

Handoffs

Part of the research-co-pilot skill network. See docs/skill-network.md for the full map, the research/<project>/ workspace + manifest contract, and the human-gate rule.

Lifecycle position: Citations — a support skill; runs whenever references exist (drafting, pre-submission, grant prep).

Upstream (what this skill reads):

• manuscript-drafter → manuscript_<section>_<topic>.md — the draft whose bibliography needs formatting (after [CITATION NEEDED] markers are resolved).
• literature-review → lit_review_<topic>.md — its reference list as a starter bibliography.
• grant-writer → grant sections needing funder-specific citation style.
• At intake, check research/<project>/manifest.json for a draft or reference list before asking for paths.

Downstream (what this skill feeds):

• manuscript-drafter — hand the cleaned references back into the draft.
• peer-review — clean, verified references before a pre-submission audit.

Chaining:

• Claude Code: typically invoked by manuscript-drafter, reviewer-response, or grant-writer rather than the reverse. When run standalone on a manuscript, offer to invoke Skill(peer-review) next (ask first).
• claude.ai: advise the user on the next step rather than auto-chaining.

Vault (see docs/research-vault.md):

• Read at intake: the canonical bibliography.md — this is your input, not a parallel list. Render the requested style from it; don't build a separate reference list that can drift.
• Write at output: mark entries Verified once you've confirmed DOI/metadata; fold any new sources back into bibliography.md with cite-keys; resolve the matching [CITATION NEEDED] items in open-questions.md.

Output to the vault: write references.md (or edit the manuscript in place) into research/<project>/08-drafts/, register it in the manifest.