credit-contributions

name	credit-contributions
description	Annotate a paper or work with CRediT (Contributor Roles Taxonomy) author contributions and render the LaTeX byline. Creates a `.tributors.credit.yaml` overlay (single source of truth, compatible with con/tributors), seeds it from sibling repos' git history when present, renders the "Author Contributions" section into LaTeX or Markdown for the target venue, emits JATS XML for publisher metadata, and (via render_authors.py) renders the `\author{}` block with affiliation references. Use when a paper needs a CRediT statement, when standardising contributor attribution across a multi-repo work, when authors need an auto-generated byline + affiliation block, or when the user mentions CRediT / NISO Z39.104 / contributor roles / author contribution section.
allowed-tools	Bash, Read, Edit, Write, Glob, Grep, AskUserQuestion
user-invocable	true

CRediT Contributor Roles for a Work

Implement the CRediT taxonomy (ANSI/NISO Z39.104-2022) for a paper, dataset, or software release. Maintains one machine-readable source of truth and renders all formats (in-paper section, JATS XML, contribution matrix) from it.

When to Use

• A paper needs an "Author Contributions" section using CRediT roles.
• Editor or venue requires CRediT metadata (Scientific Data, eLife, PLOS, …).
• User asks to "add CRediT", "list contributor roles", "do author contributions for this paper".
• A multi-repo work needs contributions attributed across sibling repos.

What This Skill Produces

1. .tributors.credit.yaml — YAML overlay at the work's root, indexed by GitHub username (same key as .tributors). Holds byline order, per-author roles, optional degree-of-contribution, and render style. Authoritative — every other artifact derives from it.

2. .tributors (JSON, only if missing) — minimal identity cache following the con/tributors convention. Holds name / email / ORCID / affiliation per username. Once created, tributors update can refresh from GitHub / ORCID.

3. Rendered Author Contributions section — LaTeX or Markdown, inserted into the manuscript at the section the venue requires.

4. JATS XML (<contrib-group>) — when the venue accepts machine-readable submission, emitted to *.jats.xml or similar.

Why YAML overlay + JSON identity (not CITATION.cff)

The Citation File Format does not encode CRediT roles — confirmed at the schema-guide level; the spec authors recommend capturing role attribution out-of-band (e.g. in Zenodo records). .tributors likewise carries identity but no CRediT today. Rather than invent a third standard, this skill keeps identity in .tributors and layers CRediT in .tributors.credit.yaml. When con/tributors gains native CRediT support, the overlay folds back in.

Renderers

Two single-file Python tools (PyYAML-only):

render_credit.py — Author Contributions section / JATS XML / matrix:

python3 ~/.claude/skills/credit-contributions/render_credit.py \
    --format latex .tributors.credit.yaml -o author-contributions.tex

python3 ~/.claude/skills/credit-contributions/render_credit.py \
    --format jats .tributors.credit.yaml -o author-contributions.jats.xml

# Validation only — no output, non-zero on bad role name / malformed entry:
python3 ~/.claude/skills/credit-contributions/render_credit.py \
    --validate-only .tributors.credit.yaml

Other formats: markdown, text, matrix-md, matrix-tex. The renderer normalises common role-name variants (ASCII hyphen for the en-dash, "and" for "&") and rejects unknown roles. The canonical 14 roles + URIs are listed in CREDIT_ROLES.md next to this file.

render_authors.py — LaTeX \author{} block with affiliation references:

python3 ~/.claude/skills/credit-contributions/render_authors.py \
    .tributors.credit.yaml --tributors .tributors -o authors.tex

Reads byline order from .tributors.credit.yaml (byline: list) and names + affiliations from .tributors. Deduplicates affiliations across the byline (first-appearance order = id 1, 2, ...) and tags each author with \textsuperscript{<ids>}. Affiliation in .tributors may be a single string or a list of strings (multi-affiliation authors).

The affiliation footer is wrapped in a width-limited (0.85\textwidth), small-font minipage so long affiliation strings wrap cleanly and don't drag \maketitle's centring wide. Width and font size are configurable via style.affiliations_width (fraction in (0, 1]) and style.affiliations_size (LaTeX size keyword).

ORCID marker. When .tributors carries an orcid for an author, render_authors.py adds a hyperlinked iD marker after the author name. Driven by style.orcid_marker:

• text-id (default) — plain superscript iD link, packed into the affiliation superscript (no preamble change required).
• orcidlink — \orcidlink{<id>} from the orcidlink package (requires \usepackage{orcidlink} in the manuscript preamble); draws the proper green ORCID iD icon.
• none — no ORCID marker.

The orcid value in .tributors may be either the bare 16-digit id (0000-0002-1234-5678) or the full https://orcid.org/... URL; both forms are normalised.

Affiliation hyperlinks. A top-level affiliation_links: map in .tributors.credit.yaml lets you hyperlink institution names inside affiliation strings, e.g.:

affiliation_links:
  Center for Open Neuroscience: https://centerforopenneuroscience.org/
  Department of Psychological and Brain Sciences: https://pbs.dartmouth.edu/
  Dartmouth College: https://dartmouth.edu/

Each key is matched literally inside every affiliation string; the longest match wins when keys overlap (e.g. "Dartmouth College" before "Dartmouth"). The substring is wrapped in \href{url}{substring} — hyperref's existing urlcolor setting handles styling.

Output is meant to be \input{authors}'d from main.tex in place of a hand-written \author{...} line.

Workflow

Step 1 — Discover the work and its contributors

1. Determine the work directory. If the user invokes the skill from inside a paper repo, that's the work root. Otherwise ask.
2. Look for an existing .tributors.credit.yaml — if present, this is an update flow; jump to Step 4.
3. Look for an existing .tributors JSON — if present, use it as the identity source.
4. If the work spans multiple sibling repos (common for a paper + companion code/data repos), enumerate them. Default heuristic: the work's parent directory contains sibling <prefix>-* clones of the same GitHub org. Ask the user to confirm which sibling repos count as "the work" for attribution purposes.
5. Identify the byline (author list, in order) — usually already in \author{...} (LaTeX) or front-matter (Markdown). Confirm with user before proceeding.

Step 2 — Seed identity (.tributors) if missing

For each byline author, populate at minimum: name, email (or GitHub noreply), orcid (if known), affiliation. Keyed by GitHub username. If con/tributors is installed, prefer running tributors update --resource github to seed; otherwise hand-build a minimal JSON.

Step 3 — Infer initial CRediT roles from git activity

The user's intent for this skill is to infer plausible roles from work across the relevant repos, not to leave blanks. For each byline author, sample:

• git -C <repo> log --author=<author> --pretty=format:%s -- <area> for each repo and each meaningful subtree (code/, figures/, .github/workflows/, proposals/, containers/, main.tex, …).
• git -C <repo> log --author=<author> --shortstat for volume.
• git -C <repo> shortlog -sne for relative ranking among byline.

Map activity → roles using the abridged definitions in CREDIT_ROLES.md. Conservative defaults:

Observed activity	Suggested role(s)
Heavy main.tex authoring	Writing – original draft
Copy-edit / review commits on main.tex	Writing – review & editing
code/, containers/, CI workflow commits	Software
Figures / logos / visualisations	Visualization
Schema, methodology proposals, normative spec	Methodology, Conceptualization
Reference / example implementations	Resources, Methodology
Cross-repo coordination, project planning	Project administration
Funded PI on grants listed in Funding section	Funding acquisition, Supervision

Annotate each inferred role with a # DRAFT comment in the YAML so the human authors can confirm. Do not silently fabricate attribution.

If the user explicitly stated a role for someone, mark it without DRAFT.

Step 4 — Generate the in-paper section

Identify the section anchor in the manuscript (typically an empty Author Contributions heading or a placeholder). Render with the format matching the manuscript:

• LaTeX: --format latex, content goes between the heading and the next section. The renderer prefixes a comment marking the output as auto-generated — keep that comment so future editors know not to hand-edit.
• Markdown: --format markdown.

Two integration patterns are acceptable:

• Inline — paste the rendered prose directly into main.tex. Simple, no build-time dependency. Re-run the renderer and replace the block when the YAML changes.
• Built — write the renderer output to a file (e.g. author-contributions.tex) and \input{} it from main.tex. Wire the render call into Makefile so it stays in sync. Prefer this pattern when the project already has a Makefile.

Step 5 — Emit JATS XML (when relevant)

If the venue accepts JATS XML submission (most Nature, eLife, PLOS, Frontiers do), also emit the machine-readable form:

python3 ~/.claude/skills/credit-contributions/render_credit.py \
    --format jats .tributors.credit.yaml \
    -o submission/author-contributions.jats.xml

Per JATS4R, each <role> carries vocab="credit", vocab-identifier, vocab-term, and vocab-term-identifier (the stable per-role URI on credit.niso.org). The renderer also emits ORCID as a <contrib-id contrib-id-type="orcid"> element when present in .tributors.

Step 6 — Validate and integrate

python3 ~/.claude/skills/credit-contributions/render_credit.py \
    --validate-only .tributors.credit.yaml

If the project uses REUSE / SPDX licensing, ensure .tributors and .tributors.credit.yaml are covered by the appropriate annotation block (CC-BY-4.0 is appropriate as authorship metadata; CC0-1.0 also fits).

Commit message: lead with meta: or doc: and reference the source of truth in the body, e.g.

meta: introduce CRediT contributor-role overlay (.tributors.credit.yaml)

Render the Author Contributions section from this single source of truth:
  render_credit.py --format latex .tributors.credit.yaml

Inferred role assignments are marked `# DRAFT` and need author confirmation
before submission.

Choosing initials style vs. fullname

Many venues — Nature family, JAMA, BMJ — render contributions as "A.P.M. contributed Y and Z; B.T.R. contributed Y." — authors_as: initials. Elsevier and PLOS use the full-name form — authors_as: fullname. The Scientific Data submission guidelines explicitly show the initials form for this section. Set the venue's preference in style: and the renderer follows.

Watch for initials collisions. If two authors yield the same initials (e.g. two J.S.'s), append a middle initial or include a footnote. The renderer derives initials from the name field unless initials: is explicitly set per contributor — set it when collisions or unusual name forms (de la Cruz, Müller, hyphenated) arise.

Related tools

• con/tributors — the JSON identity cache this overlay sits next to. Generates all-contributors / Zenodo / CodeMeta files. CRediT export is the natural next extension.
• tenzing — R package
  • web app, spreadsheet-driven, emits papaja YAML + JATS XML.
• latex-credits — inline \credit{author}{roles} LaTeX commands; no single source of truth.
• CRediT Statement Generator — web UI.

This skill differs in keeping a YAML single source of truth that's both human-editable and machine-readable, and in deriving identity from the existing .tributors convention.

References

• https://credit.niso.org/
• https://credit.niso.org/implementing-credit/
• https://jats4r.niso.org/credit-taxonomy/
• https://zenodo.org/records/18421449 — CRediT example research tasks
• ANSI/NISO Z39.104-2022