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)

```bibtex
@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: <fields>".

## 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`](../../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`](../../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.