| 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
-
.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.
-
.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.
-
Rendered Author Contributions section — LaTeX or Markdown, inserted
into the manuscript at the section the venue requires.
-
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
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
- Determine the work directory. If the user invokes the skill from inside
a paper repo, that's the work root. Otherwise ask.
- Look for an existing
.tributors.credit.yaml — if present, this is an
update flow; jump to Step 4.
- Look for an existing
.tributors JSON — if present, use it as the
identity source.
- 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.
- 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
