| name | citations |
| description | Canonical rules and HTML/CSS contract for inline `[n]` citation references, end-of-document Citations blocks, and optional per-section citation recaps used across Moody's Agentic Solutions HTML report skills (earnings-brief, peer-analysis, issuer-brief, sector-brief, etc.). Parent skills must read BOTH this `SKILL.md` (rules, numbering, hyperlink behavior, source data shape) AND `assets/template.html` (canonical CSS block + literal HTML markup snippets) before emitting citations. The asset file is the single source of truth for the visual/markup implementation; this `SKILL.md` is the single source of truth for the authoring rules. Triggers when the user asks about citations, sources, references, footnotes, hyperlinking [n] markers, or the Sources/Citations block in any HTML report skill.
|
Citations Skill (shared)
This is the single source of truth for how citations are authored and rendered across the
HTML report skills. Parent skills (earnings-brief, peer-analysis,
issuer-brief, sector-brief, etc.) defer to this document for inline reference
markup, the Citations block, numbering, hyperlinking, source data shape, and CSS. Each parent
skill keeps only its own carve-outs (e.g. "no citations in .yoy-change cells", "no citations
in financial table cells").
The canonical CSS and the literal HTML markup contracts live in
assets/template.html. This SKILL.md describes the rules; the
asset file ships the verbatim implementation. Parent skills must read both files before
emitting citations.
Sibling skill. skills/shared/template/ owns the rest of the visual
chrome (cover, TOC, section, sources-section wrapper, footer, outlook-badge, design tokens)
and uses the same inlining pattern as this skill — parent templates reserve a CSS-comment
marker region (/* BEGIN shared-template-css ... */ / /* END shared-template-css */) and
copy the contents of <style id="shared-template-css"> from that skill's assets/template.html
at emit time. Read both shared skills together when authoring or modifying any HTML report
skill.
When to read this skill
Read this skill from a parent skill before emitting any [n] reference or the
end-of-document Citations block. Parent skills must contain a directive near the top of their
SKILL.md instructing the agent to read both this file and assets/template.html.
Output contract (single global rules)
- Every report contains exactly one Citations block at the end of the document.
- Numbering is a single global sequence
[1], [2], … per document. The number n in any
inline reference MUST equal the row position of the matching source inside
#{prefix}-sources (1-indexed, in document order).
- Internal MCP tool names are NEVER rendered in any citation row.
- Plain
[n] text in narrative content (not wrapped in <a class="cite-ref"> or
<span class="cite-ref">) is not allowed.
- Citations are not embedded inside numeric/data cells of financial, valuation, ratings,
risk, ESG, or YoY tables. Parent skills may extend this carve-out list.
1. Inline reference markup
The literal markup ships in assets/template.html (<template id="cite-ref-anchor"> and
<template id="cite-ref-span">). Rules:
- With URL: copy
cite-ref-anchor and substitute {source_url} and [n]. This is the
default form.
- Without URL: copy
cite-ref-span and substitute [n]. Use this fallback only when
the source has no URL — the span keeps the .cite-ref styling without an active link.
n MUST match the row position of that source inside #{prefix}-sources. The same n
may be reused multiple times throughout the document for repeat references to the same
source.
2. End-of-document Citations block
Every report renders exactly one Citations block at the end of the document. The container
markup ships in assets/template.html (<template id="sources-section">).
{prefix} is the parent skill's prefix (ecs, pa, pib, sa). The displayed heading is
always the literal string Citations. The container <div> keeps its existing
#{prefix}-sources id for backward continuity.
Three row variants ship in the asset; pick based on which fields are present:
| variant template id | when to use |
|---|
source-item-with-url | source has a URL and at least one of source / date. |
source-item-no-url | no URL but at least one of source / date. |
source-item-no-meta | source has a URL but no source and no date. |
If only one of source or date is present, render only that field inside the () of
.source-meta. If neither is present and a URL exists, drop the .source-meta span entirely
(use source-item-no-meta).
3. Optional per-section recap (opt-in)
Some skills (currently earnings-brief, peer-analysis, issuer-brief, etc.)
render a short recap of the citations referenced inside a given section, immediately below
that section's content. This component is opt-in. Parent skills decide whether to use it;
the canonical CSS in assets/template.html ships the styling unconditionally so the option
is always available.
The recap markup ships in assets/template.html (<template id="section-citations-recap">).
Parent skills that opt in also embed empty target placeholders inside each section using the
<template id="section-citations-target"> shape (<div id="{prefix}-cite-{slot}"></div>),
which the LLM later fills with a recap or leaves empty if the section has no citations.
The numbers inside a recap MUST be the same n values used inline and listed in the
end-of-document Citations block. A recap NEVER introduces a new numbering sequence. If a
section has no citations, omit the recap entirely (leave the target div empty).
4. Source data shape
Each source is described by:
| field | required | notes |
|---|
id | yes | 1-indexed integer matching the row's position in #{prefix}-sources. |
title | yes | Human-readable title. Rendered inside .source-title. |
source | no | Publisher / system (e.g. "Moody's Research Assistant Library"). |
date | no | Display-formatted date (e.g. 2026-02-24 or 12 Sep 2026). |
url | no | Absolute URL. If absent, use the URL-less row variant above. |
Never render internal MCP tool names (e.g. getEntityCreditOpinion) in .source-meta.
5. Canonical CSS
The canonical CSS lives only in assets/template.html inside the
<style id="shared-citations-css">…</style> block. Parent templates do not carry a
duplicate copy of these rules. Each parent template instead reserves a marker region inside
its own <style> tag bracketed by CSS comments (not HTML comments — the markers sit
inside <style>, where <!-- … --> would produce CSS parse errors):
At emit time, the agent copies the contents (not the <style> wrapper) of
<style id="shared-citations-css">…</style> from the shared asset and inserts them between
those two marker comments in the final emitted HTML. Treat the canonical CSS as a single
block — do not edit values per-skill. If a parent skill needs to restyle citations, change
assets/template.html and the next emit picks it up automatically.
CSS variable contract
The block above relies on these CSS custom properties being defined elsewhere in the parent
template's :root (they already are in every current template):
--accent — link / inline-cite color--navy — heading and source-num color--g100 — light background for .section-citations--g200 — border color for .source-item separator and .section-citations border--g400 — meta text color--g700 — body text color for source rows--gray-100, --gray-200, --gray-400, --gray-700 — legacy aliases used by ECS / peer-
analysis templates. Either set of names works; templates that already define --gray-* may
alias them to --g* (or vice-versa) so the canonical block renders without edits.
If a template defines only one naming scheme, add aliases at the top of the <style> block
so both name families resolve. Example alias snippet (add only the side you are missing):
:root {
--g100: var(--gray-100);
--g200: var(--gray-200);
--g400: var(--gray-400);
--g700: var(--gray-700);
}
6. Quick checklist (use before submitting a report)
