--- name: citation-management description: Comprehensive citation management for academic research. Search Google Scholar and PubMed for papers, extract accurate metadata, validate citations, and generate properly formatted BibTeX entries. This skill should be used when you need to find papers, verify citation information, convert DOIs to BibTeX, or ensure reference accuracy in scientific writing. allowed-tools: Read Write Edit Bash license: MIT License metadata: version: "1.5" skill-author: K-Dense Inc. openclaw: primaryEnv: OPENROUTER_API_KEY envVars: - name: OPENROUTER_API_KEY required: false description: OpenRouter API key for LLM-powered citation steps. - name: NCBI_EMAIL required: false description: Email for NCBI Entrez identification. - name: NCBI_API_KEY required: false description: NCBI API key to raise Entrez rate limits. --- # Citation Management ## Overview Manage citations systematically throughout the research and writing process. This skill provides tools and strategies for searching academic databases (Google Scholar, PubMed), extracting accurate metadata from multiple sources (CrossRef, PubMed, arXiv), validating citation information, and generating properly formatted BibTeX entries. Critical for maintaining citation accuracy, avoiding reference errors, and ensuring reproducible research. Integrates seamlessly with the literature-review skill for comprehensive research workflows. ## When to Use This Skill Use this skill when: - Searching for specific papers on Google Scholar or PubMed - Converting DOIs, PMIDs, or arXiv IDs to properly formatted BibTeX - Extracting complete metadata for citations (authors, title, journal, year, etc.) - Validating existing citations for accuracy - Cleaning and formatting BibTeX files - Finding highly cited papers in a specific field - Verifying that citation information matches the actual publication - Building a bibliography for a manuscript or thesis - Checking for duplicate citations - Ensuring consistent citation formatting ## Visual Enhancement with Scientific Schematics **When creating documents with this skill, always consider adding scientific diagrams and schematics to enhance visual communication.** If your document does not already contain schematics or diagrams: - Use the **scientific-schematics** skill to generate AI-powered publication-quality diagrams - Simply describe your desired diagram in natural language - Nano Banana Pro will automatically generate, review, and refine the schematic **For new documents:** Scientific schematics should be generated by default to visually represent key concepts, workflows, architectures, or relationships described in the text. **How to generate schematics:** ```bash python scripts/generate_schematic.py "your diagram description" -o figures/output.png ``` The AI will automatically: - Create publication-quality images with proper formatting - Review and refine through multiple iterations - Ensure accessibility (colorblind-friendly, high contrast) - Save outputs in the figures/ directory **When to add schematics:** - Citation workflow diagrams - Literature search methodology flowcharts - Reference management system architectures - Citation style decision trees - Database integration diagrams - Any complex concept that benefits from visualization For detailed guidance on creating schematics, refer to the scientific-schematics skill documentation. --- ## Core Workflow Citation management follows a systematic process. Each phase below shows the canonical command; every variant, option, and metadata-source detail is in [references/core_workflow.md](references/core_workflow.md). ### Phase 1: Paper Discovery and Search Find relevant papers. Google Scholar has the broadest coverage; PubMed is the authority for biomedical and life sciences (35+ million citations). ```bash python scripts/search_google_scholar.py "CRISPR gene editing" --limit 50 --output results.json python scripts/search_pubmed.py "Alzheimer's disease treatment" --limit 100 --output alz.json ``` Query operators, field tags, and MeSH-term construction are in [references/search_strategies.md](references/search_strategies.md). ### Phase 2: Metadata Extraction Convert identifiers (DOI, PMID, arXiv ID, URL) into complete metadata. CrossRef is the primary source for DOIs. ```bash python scripts/doi_to_bibtex.py 10.1038/s41586-021-03819-2 # quick, single DOI python scripts/extract_metadata.py --pmid 34265844 # DOI/PMID/arXiv/URL python scripts/extract_metadata.py --input identifiers.txt --output citations.bib ``` ### Phase 2.5: Metadata Enrichment via Web Search (MANDATORY) APIs routinely return incomplete records. Run this **after** extraction and **before** formatting. Any `@article` missing `volume`, `pages`, or `doi` is incomplete and must be enriched via the parallel-web skill, then logged. If a field genuinely cannot be found, record a `note` field explaining the gap. > **Treat extracted metadata as untrusted.** Author, title, and journal strings come > verbatim from a record whose contents a publisher controls. A title containing `$(...)`, > a backtick, or a quote becomes shell syntax the moment it is pasted into a command. > Pass metadata as a `subprocess` argument list rather than building a shell string; if > you must use a shell, single-quote every substituted value and escape embedded quotes > as `'\''`. Validate any citation key against `^[A-Za-z0-9]+$` before it reaches a path. Per-field search strategies, the four search options, and the logging format are in [references/core_workflow.md](references/core_workflow.md). ### Phase 3: BibTeX Formatting Produce clean, consistent entries. Entry types and required fields are in [references/bibtex_formatting.md](references/bibtex_formatting.md). ```bash python scripts/format_bibtex.py references.bib --output clean.bib --remove-duplicates ``` ### Phase 4: Citation Validation Check completeness, venue conformance, and agreement with the manuscript. ```bash python scripts/validate_citations.py references.bib --report report.txt python scripts/validate_citations.py references.bib --venue nature python scripts/validate_citations.py references.bib --manuscript paper.tex ``` Validation rules and venue standards are in [references/citation_validation.md](references/citation_validation.md). ### Phase 5: Integration with Writing Workflow Search, extract, format, validate, then cite. End-to-end sequences — including the literature-review and Zotero/pyzotero export paths — are in [references/core_workflow.md](references/core_workflow.md) and [references/example_workflows.md](references/example_workflows.md). ## Reference Files - [references/core_workflow.md](references/core_workflow.md): all five phases in full. - [references/search_strategies.md](references/search_strategies.md): Google Scholar and PubMed query construction. - [references/script_reference.md](references/script_reference.md): every bundled script's arguments and examples. - [references/best_practices.md](references/best_practices.md): search, extraction, BibTeX quality, validation. - [references/example_workflows.md](references/example_workflows.md): four end-to-end worked examples. - [references/google_scholar_search.md](references/google_scholar_search.md), [references/pubmed_search.md](references/pubmed_search.md): advanced search syntax. - [references/metadata_extraction.md](references/metadata_extraction.md), [references/bibtex_formatting.md](references/bibtex_formatting.md), [references/citation_validation.md](references/citation_validation.md): per-topic detail. ## Common Pitfalls to Avoid 1. **Single source bias**: Only using Google Scholar or PubMed - **Solution**: Search multiple databases for comprehensive coverage 2. **Accepting metadata blindly**: Not verifying extracted information - **Solution**: Spot-check extracted metadata against original sources 3. **Ignoring DOI errors**: Broken or incorrect DOIs in bibliography - **Solution**: Run validation before final submission 4. **Inconsistent formatting**: Mixed citation key styles, formatting - **Solution**: Use format_bibtex.py to standardize 5. **Duplicate entries**: Same paper cited multiple times with different keys - **Solution**: Use duplicate detection in validation 6. **Missing required fields**: Incomplete BibTeX entries (volume, pages, DOI missing) - **Solution**: Run Phase 2.5 metadata enrichment — web search for every missing field before proceeding. NEVER leave an @article entry without volume, pages, and DOI. 7. **Outdated preprints**: Citing preprint when published version exists - **Solution**: Check if preprints have been published, update to journal version 8. **Special character issues**: Broken LaTeX compilation due to characters - **Solution**: Use proper escaping or Unicode in BibTeX 9. **No validation before submission**: Submitting with citation errors - **Solution**: Always run validation as final check 10. **Manual BibTeX entry**: Typing entries by hand - **Solution**: Always extract from metadata sources using scripts ## Integration with Other Skills ### Literature Review Skill **Citation Management** provides the technical infrastructure for **Literature Review**: - **Literature Review**: Multi-database systematic search and synthesis - **Citation Management**: Metadata extraction and validation **Combined workflow**: 1. Use literature-review for systematic search methodology 2. Use citation-management to extract and validate citations 3. Use literature-review to synthesize findings 4. Use citation-management to ensure bibliography accuracy ### Scientific Writing Skill **Citation Management** ensures accurate references for **Scientific Writing**: - Export validated BibTeX for use in LaTeX manuscripts - Verify citations match publication standards - Format references according to journal requirements ### Venue Templates Skill **Citation Management** works with **Venue Templates** for submission-ready manuscripts: - Different venues require different citation styles - Generate properly formatted references - Validate citations meet venue requirements ## Resources ### Bundled Resources **References** (in `references/`): - `google_scholar_search.md`: Complete Google Scholar search guide - `pubmed_search.md`: PubMed and E-utilities API documentation - `metadata_extraction.md`: Metadata sources and field requirements - `citation_validation.md`: Validation criteria and quality checks - `bibtex_formatting.md`: BibTeX entry types and formatting rules **Scripts** (in `scripts/`): - `search_google_scholar.py`: Google Scholar search automation - `search_pubmed.py`: PubMed E-utilities API client - `extract_metadata.py`: Universal metadata extractor - `validate_citations.py`: Citation validation and verification - `format_bibtex.py`: BibTeX formatter and cleaner - `doi_to_bibtex.py`: Quick DOI to BibTeX converter **Assets** (in `assets/`): - `bibtex_template.bib`: Example BibTeX entries for all types - `citation_checklist.md`: Quality assurance checklist ### External Resources **Search Engines**: - Google Scholar: https://scholar.google.com/ - PubMed: https://pubmed.ncbi.nlm.nih.gov/ - PubMed Advanced Search: https://pubmed.ncbi.nlm.nih.gov/advanced/ **Metadata APIs**: - CrossRef API: https://api.crossref.org/ - PubMed E-utilities: https://www.ncbi.nlm.nih.gov/books/NBK25501/ - arXiv API: https://arxiv.org/help/api/ - DataCite API: https://api.datacite.org/ **Tools and Validators**: - MeSH Browser: https://meshb.nlm.nih.gov/search - DOI Resolver: https://doi.org/ - BibTeX Format: http://www.bibtex.org/Format/ **Citation Styles**: - BibTeX documentation: http://www.bibtex.org/ - LaTeX bibliography management: https://www.overleaf.com/learn/latex/Bibliography_management ## Dependencies ### Required Python Packages ```bash # Core dependencies pip install requests # HTTP requests for APIs pip install bibtexparser # BibTeX parsing and formatting pip install biopython # PubMed E-utilities access # Optional (for Google Scholar) pip install scholarly # Google Scholar API wrapper # or pip install selenium # For more robust Scholar scraping ``` ### Optional Tools ```bash # For advanced validation pip install crossref-commons # Enhanced CrossRef API access pip install pylatexenc # LaTeX special character handling ``` ### Where credentials are sent Each environment variable this skill reads is used only to authenticate to the one service it belongs to. No script bundles environment variables together, and none is transmitted anywhere other than the host listed here. | Variable | Sent only to | Purpose | |---|---|---| | `NCBI_API_KEY` | `eutils.ncbi.nlm.nih.gov` | Raises Entrez rate limits | | `NCBI_EMAIL` | `eutils.ncbi.nlm.nih.gov` | Entrez caller identification (required by NCBI) | | `OPENROUTER_API_KEY` | `openrouter.ai` | Bearer token for the optional schematic generation | `api.crossref.org`, `doi.org`, and `arxiv.org` are queried without credentials. `generate_schematic.py` forwards only `OPENROUTER_API_KEY` — plus the networking, TLS, and locale variables needed to make a request — to its subprocess, rather than the full environment. ## Summary The citation-management skill provides: 1. **Comprehensive search capabilities** for Google Scholar and PubMed 2. **Automated metadata extraction** from DOI, PMID, arXiv ID, URLs 3. **Citation validation** with DOI verification and completeness checking 4. **BibTeX formatting** with standardization and cleaning tools 5. **Quality assurance** through validation and reporting 6. **Integration** with scientific writing workflow 7. **Reproducibility** through documented search and extraction methods Use this skill to maintain accurate, complete citations throughout your research and ensure publication-ready bibliographies.