manage-refs

Name: manage-refs
Author: Aperivue

40installs53forks

How to install manage-refs?

aperivue/medsci-skills/manage-refs

$npx -y skills add Aperivue/medsci-skills --skill manage-refs

Installs into the current project.

Summary

Cross-cutting reference manager for medical manuscripts. Single entry point for citation-key validation, journal-CSL pandoc rendering, manuscript ↔ DOCX cross-reference QC, marker conversion (`[N] ↔ [@key]`), and native Zotero CWYW field-code injection. Replaces the inline

Files · 1

View on GitHub

SKILL.md

1	# Manage-Refs Skill
2
3	> Canonical source (issue #16). This SKILL.md is the single canonical
4	> reference for the reference-workflow (validate keys → render CSL → convert
5	> markers → QC cross-references → inject Zotero CWYW). Audit-only bib
6	> verification is owned by `skills/verify-refs/SKILL.md`. Any user-scope rule or
7	> external note about reference handling should point here (workflow) or to
8	> verify-refs (audit) rather than restating the "how", to prevent drift.
9
10	You are routing reference-handling work for a medical manuscript. The user is
11	somewhere in the lifecycle — drafting, building a circulation DOCX, swapping
12	CSL after a journal rejection, fixing a cross-reference defect surfaced by
13	QC, or wiring up live Zotero field codes for a co-author Word workflow. Pick
14	the right tool from the decision table; do not invent a parallel pipeline.
15
16	## Why This Skill Exists
17
18	Reference handling spans every late-stage skill: `/write-paper` builds the
19	first DOCX, `/revise` rebuilds it after each reviewer round, `/peer-review`
20	emits a critique that quotes references back, `/sync-submission` packages the
21	final tarball, `/find-journal` informs CSL swaps on rejection cascade, and
22	`/verify-refs` audits the bibliography. Until 2026-05-01 these scripts lived
23	under `skills/write-paper/scripts/`, which made `/revise` and `/sync-submission`
24	silently depend on a sibling skill — a layering inversion that broke when
25	`/write-paper` was loaded into a non-research project. Moving the
26	lifecycle tools here turns reference handling into a first-class concern
27	with one decision tree, one set of CSL files, and one provenance file
28	(`NOTICE.md`) for the vendored Zotero CWYW writer.
29
30	Validated 2026-05-01 against a 21-reference meta-analysis manuscript
31	(a meta-analysis project's submission) for both pandoc-citeproc and Zotero-CWYW paths.
32
33	## Anti-Hallucination Guarantees
34
35	1. Citekey discipline (Phase 0): every in-text citation must be
36	`[@bibkey]` resolvable in `refs.bib`. `scripts/check_citation_keys.py` is
37	a hard gate — UNDEFINED keys exit non-zero and block the build.
38
39	`[@NEW:topic]` placeholder convention: while drafting, `/write-paper`
40	may emit `[@NEW:topic_slug]` markers for citations the author still needs
41	to source. `check_citation_keys.py` classifies these as `NEW_PLACEHOLDER`
42	(not UNDEFINED) and exits 0 — the build is allowed to proceed during
43	drafting. Phase 7.6 (DOCX render) is a hard gate: zero NEW_PLACEHOLDER
44	entries must remain. Resolve each by adding the citation to Zotero (then
45	`/lit-sync` refreshes refs.bib) and replacing the placeholder with the
46	real `[@bibkey]`. Never let a `[@NEW:...]` reach a rendered DOCX.
47	2. No hand-typed References list — references are always rendered by
48	pandoc citeproc + journal CSL or by the Zotero Word plugin (CWYW). See
49	`~/.claude/rules/manuscript-references.md`.
50	3. Zotero metadata is never invented — `inject_zotero_cwyw.py` fetches
51	item data live from `http://localhost:23119`. Any HTTP failure aborts
52	with a non-zero exit so partial bibliographies never reach the user.
53	4. Marker conversion is mapping-driven — `md_marker_convert.py` will
54	never guess a Zotero key for a number; unmapped markers stay as `[N]`
55	and are reported on stderr.
56	5. Cross-reference QC is a submission gate — `scripts/check_xref.py`
57	`--strict` exits 1 on any `MISSING_DOCX` / `MISSING_BODY` / `MISMATCH`,
58	blocking pipelines that try to ship a DOCX whose Table/Figure citations
59	don't match captions.
60	6. Audit boundary: this skill writes; bibliographic correctness against
61	PubMed/CrossRef stays in `/verify-refs`. Always invoke `/verify-refs`
62	after a render before signing off — one read-only audit, one writer.
63
64	## Decision Tree
65
66	\| Situation \| Tool \| Why \|
67	\|---\|---\|---\|
68	\| Validate `[@bibkey]` ↔ `refs.bib` (UNDEFINED / UNUSED keys) \| `scripts/check_citation_keys.py` \| Hard build gate, runs in seconds \|
69	\| Single-author submission lockdown, frozen output \| `scr

People who liked this also viewed

6 picks

Type

manage-refs

40installs53forks

View on GitHub

How to install manage-refs?

aperivue/medsci-skills/manage-refs

$npx -y skills add Aperivue/medsci-skills --skill manage-refs

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Manage-Refs Skill
2
3	> Canonical source (issue #16). This SKILL.md is the single canonical
4	> reference for the reference-workflow (validate keys → render CSL → convert
5	> markers → QC cross-references → inject Zotero CWYW). Audit-only bib
6	> verification is owned by `skills/verify-refs/SKILL.md`. Any user-scope rule or
7	> external note about reference handling should point here (workflow) or to
8	> verify-refs (audit) rather than restating the "how", to prevent drift.
9
10	You are routing reference-handling work for a medical manuscript. The user is
11	somewhere in the lifecycle — drafting, building a circulation DOCX, swapping
12	CSL after a journal rejection, fixing a cross-reference defect surfaced by
13	QC, or wiring up live Zotero field codes for a co-author Word workflow. Pick
14	the right tool from the decision table; do not invent a parallel pipeline.
15
16	## Why This Skill Exists
17
18	Reference handling spans every late-stage skill: `/write-paper` builds the
19	first DOCX, `/revise` rebuilds it after each reviewer round, `/peer-review`
20	emits a critique that quotes references back, `/sync-submission` packages the
21	final tarball, `/find-journal` informs CSL swaps on rejection cascade, and
22	`/verify-refs` audits the bibliography. Until 2026-05-01 these scripts lived
23	under `skills/write-paper/scripts/`, which made `/revise` and `/sync-submission`
24	silently depend on a sibling skill — a layering inversion that broke when
25	`/write-paper` was loaded into a non-research project. Moving the
26	lifecycle tools here turns reference handling into a first-class concern
27	with one decision tree, one set of CSL files, and one provenance file
28	(`NOTICE.md`) for the vendored Zotero CWYW writer.
29
30	Validated 2026-05-01 against a 21-reference meta-analysis manuscript
31	(a meta-analysis project's submission) for both pandoc-citeproc and Zotero-CWYW paths.
32
33	## Anti-Hallucination Guarantees
34
35	1. Citekey discipline (Phase 0): every in-text citation must be
36	`[@bibkey]` resolvable in `refs.bib`. `scripts/check_citation_keys.py` is
37	a hard gate — UNDEFINED keys exit non-zero and block the build.
38
39	`[@NEW:topic]` placeholder convention: while drafting, `/write-paper`
40	may emit `[@NEW:topic_slug]` markers for citations the author still needs
41	to source. `check_citation_keys.py` classifies these as `NEW_PLACEHOLDER`
42	(not UNDEFINED) and exits 0 — the build is allowed to proceed during
43	drafting. Phase 7.6 (DOCX render) is a hard gate: zero NEW_PLACEHOLDER
44	entries must remain. Resolve each by adding the citation to Zotero (then
45	`/lit-sync` refreshes refs.bib) and replacing the placeholder with the
46	real `[@bibkey]`. Never let a `[@NEW:...]` reach a rendered DOCX.
47	2. No hand-typed References list — references are always rendered by
48	pandoc citeproc + journal CSL or by the Zotero Word plugin (CWYW). See
49	`~/.claude/rules/manuscript-references.md`.
50	3. Zotero metadata is never invented — `inject_zotero_cwyw.py` fetches
51	item data live from `http://localhost:23119`. Any HTTP failure aborts
52	with a non-zero exit so partial bibliographies never reach the user.
53	4. Marker conversion is mapping-driven — `md_marker_convert.py` will
54	never guess a Zotero key for a number; unmapped markers stay as `[N]`
55	and are reported on stderr.
56	5. Cross-reference QC is a submission gate — `scripts/check_xref.py`
57	`--strict` exits 1 on any `MISSING_DOCX` / `MISSING_BODY` / `MISMATCH`,
58	blocking pipelines that try to ship a DOCX whose Table/Figure citations
59	don't match captions.
60	6. Audit boundary: this skill writes; bibliographic correctness against
61	PubMed/CrossRef stays in `/verify-refs`. Always invoke `/verify-refs`
62	after a render before signing off — one read-only audit, one writer.
63
64	## Decision Tree
65
66	\| Situation \| Tool \| Why \|
67	\|---\|---\|---\|
68	\| Validate `[@bibkey]` ↔ `refs.bib` (UNDEFINED / UNUSED keys) \| `scripts/check_citation_keys.py` \| Hard build gate, runs in seconds \|
69	\| Single-author submission lockdown, frozen output \| `scr

People who liked this also viewed

6 picks

Type