hermes-agent/skills/research/grounded-citations/references/citation-formats.md
Teknium c49fa88b80
refactor(skills): shipped-set slim — 15 to optional, github 6-way merge, pdf absorbs OCR, channel-gated teams pipeline (index −26%) (#98539)
* refactor(skills): shipped-set slim — 15 skills to optional, github six-way merge, pdf absorbs OCR+nano-pdf, channel-gated teams pipeline

Maintainer-directed shipped-skills curation (skills index 1,900 -> ~1,400
tok/call on desktop; every session pays the index, so this is a per-call
diet on all installs):

- optional-skills moves (installable via skills hub, history preserved):
  creative comfyui/ascii-art/excalidraw/pretext/sketch/touchdesigner-mcp;
  ALL of mlops (huggingface-hub, llama-cpp, serving-llms-vllm,
  weights-and-biases, evaluating-llms-harness — subcategory structure
  kept); research-paper-writing (55 supporting files, 17.3K-tok load);
  openhue; blogwatcher (first taught the cronjob monitor-field watch
  pattern + web_extract instead of pre-cron manual workflows)
- DELETED session-librarian (Aug-12 'inspired by Perplexity Computer'
  port, never maintainer-intended; session_search covers discovery)
- github: six skills (auth, issues, pr-workflow, issue-to-pr,
  code-review, repo-management) merged into ONE software-development/
  github skill — routing body + complete per-workflow references;
  benbarclay authorship credited; codebase-inspection rides along;
  discipline pins from test_github_issue_to_pr_skill.py preserved
  against the reference body in the new test_github_skill.py
- pdf absorbs ocr-and-documents + nano-pdf as references/ + scripts
  (extract_pymupdf, extract_marker converted to the argparse house
  standard its contract test enforces)
- NEW session_platforms frontmatter gate (metadata.hermes): hides a
  skill from the index on gateway channels it is not for; fail-open on
  unknown platform; teams-meeting-pipeline gated to [teams, cron]
- blocked-page-recovery: research -> new web category; trigger-first
  description ('Use when a fetch fails: 403/429, paywall, WAF, bot
  wall.') so the model actually reaches for it on blocked fetches
- docs regenerated via generate-skill-docs.py (195 pages); related_skills
  swept repo-wide; tests: 1672 passed (2 openclaw failures pre-existing
  on clean main, Windows-local)

* chore: ignore .skills_prompt_snapshot.json (local index cache, accidentally committed)
2026-08-30 04:53:39 -07:00

2.4 KiB

Citation formats per output target

The ledger is format-agnostic: sources.py render --style ... emits the block, this file says where it goes and what the inline marker looks like.

Markdown / chat answers

Inline [n] immediately after the sentence. Block at the end:

## Sources

[1] https://example.com/a — Page title
[2] https://example.com/b

--style plain gives a bare Sources: header for chat replies where a markdown heading would be noise.

PDF via LaTeX (latex-pdf-report skill)

Use --style footnotes and map each id to \footnote{} at first use, or keep numeric markers and emit an endnotes section. For a bibliography-shaped report, --style bibtex writes @misc entries keyed source<N>; cite them with \cite{source3} and let BibTeX render the list.

Do not mix: either numeric [n] + a Sources section, or \cite{} + BibTeX. Two numbering systems in one document is worse than none.

Word (.docx, docx skill)

Real footnotes are preferred over inline brackets in prose documents intended for human editing — reviewers expect Word footnotes. Keep the ledger ids as the footnote numbers so verify still works on a markdown source-of-truth, and generate the .docx from that markdown.

Slides (.pptx, powerpoint skill)

Inline [n] in the bullet, one "Sources" slide at the end rendered with --style plain. Never put a URL in a body bullet — it wrecks the layout and can't be clicked in a projected deck.

Spreadsheets (.xlsx)

Add a source column holding the id, plus a Sources sheet built from render --style plain. Do not paste URLs into data cells.

Wiki / multi-page output (llm-wiki, Obsidian)

Per-page Sources block, ids shared across pages from one ledger. Because ids are ledger identities, [7] means the same page everywhere in the wiki — that consistency is the reason not to reset the ledger between pages of one build.

Research papers

Hand off to the grounded-citations skill. Export with --style bibtex into references.bib, then follow that skill's citation verification (it greps \cite{...} against the .bib). The ledger's job ends at producing verified URL entries; venue formatting is that skill's domain.

Code and config artifacts

No citations inside generated code. If provenance matters, put it in the commit message, the PR body, or a doc header — not in comments scattered through source.