Reporting
Skill mohitjandwani/analyst-kit/plugins/analyst-kit/skills/reporting
Assemble charts, tables, and analyst text into a beautiful, branded PDF — either a multi-page portrait report (A4) or a 16:9 landscape presentation deck like Google Slides. Ships page templates (comparison matrix, industry breakdown, full-bleed price chart with technical commentary, data table with commentary) that consume output from the charting, thematic-investing, and sec-filings skills. Remembers your logo and brand colors after first use. Triggers: "generate a PDF report", "turn this analysis into a deck", "make a presentation of these charts", "client-ready report", "export to PDF", "slides comparing these companies", "branded research report", "investment memo PDF".From its SKILL.md
npx -y skills add mohitjandwani/analyst-kit --skill reportingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 18 stars18 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
19.6 KB, as published. Nobody here has run it
Preamble (run first)
PLAN MODE EXCEPTION — ALWAYS RUN: this block only reads state and writes to ~/.analyst-kit/.
_AK="$(cat ~/.analyst-kit/core-path 2>/dev/null)"
if [ ! -x "$_AK/bin/analyst-kit-preamble" ]; then
for d in ~/.claude/skills/analyst-kit-core .claude/skills/analyst-kit-core ~/.codex/skills/analyst-kit-core .codex/skills/analyst-kit-core; do
[ -x "$d/bin/analyst-kit-preamble" ] && _AK="$d" && break
done
[ -x "$_AK/bin/analyst-kit-preamble" ] || _AK="$(find ~/.claude/plugins -maxdepth 6 -type d -name analyst-kit-core 2>/dev/null | head -1)"
[ -n "$_AK" ] && { mkdir -p ~/.analyst-kit; printf '%s' "$_AK" > ~/.analyst-kit/core-path; } || true
fi
[ -x "$_AK/bin/analyst-kit-preamble" ] && "$_AK/bin/analyst-kit-preamble" --skill reporting 2>/dev/null || echo "AK_CORE: not found (continue without runtime)"
Read the echoed state and act. Skip ALL bullets below if DEDUP: yes or AK_CORE: not found:
DISABLED: yes→ this skill is turned off because a required API key isn't configured. Do not run it. Tell the user it's off, name the missing key (seeMISSING_KEYS), and offer to enable it — either they give you the key now (store it with"$_AK/bin/analyst-kit-setup" set-key <KEY> <value>, which re-enables the skill) or they say "set up analyst-kit" for full setup. Then stop; do not attempt the skill's work.- First run —
ONBOARDED: no→ orient the user once, then run"$_AK/bin/analyst-kit-setup" finish(this covers the telemetry notice, so skip theTEL_PROMPTEDbullet this turn):- Data home — tell the user Analyst Kit keeps config, API keys, local usage analytics, and
a learnings log together in one folder (default
~/.analyst-kit); offer to move it with"$_AK/bin/analyst-kit-setup" home <dir>. - Telemetry (a notice, not a question) — usage telemetry is on by default: only skill name, duration, outcome, and version, tagged with a per-machine device id derived from the hardware/OS, never repo names, paths, tickers, or content; opt out anytime by asking to turn Analyst Kit telemetry off.
- Identity (name + email — required) — ask for the user's name and email, stating
plainly the email is mandatory to use most features (SEC EDGAR's fair-access policy
requires a real, reachable contact on every request). If they decline because they
don't want the email-dependent skills, discover a fallback yourself (
git config user.email,gh api user, …) and pass it with--fallbackin step 5. - Offer full setup — ask if they'd like to configure API keys for all skills now.
If yes, Read
"$_AK/references/intro.md"and follow it. If no, continue — you'll ask for a key only when a skill needs one. - Run
"$_AK/bin/analyst-kit-setup" finish --name "<name>" --email "<email>"(add--fallbackfor a discovered email; run plainfinishonly if no email could be found at all). If it echoesINVALID_EMAIL, re-ask and run it again.
- Data home — tell the user Analyst Kit keeps config, API keys, local usage analytics, and
a learnings log together in one folder (default
- User asks to set up Analyst Kit at any time (e.g. "set up analyst-kit", "help me set up Analyst Kit", "configure all skills") → Read
"$_AK/references/intro.md"and follow it end to end: data home, telemetry, every skill's keys, and enabling/disabling each. TEL_PROMPTED: no(returning user) → give the telemetry notice once, then run"$_AK/bin/analyst-kit-setup" ack-telemetry.- If the user asks to turn telemetry off (now or anytime): before flipping it, make a
sincere case once — telemetry is what tells the maintainers which skills break, which
run slow, and where users get stuck, so keeping it on directly improves their
experience; it never includes their data. Offer
"$_AK/bin/analyst-kit-config" set telemetry anonymous(drops the device id) as a middle ground. If they still want out, run"$_AK/bin/analyst-kit-config" set telemetry offimmediately and without further argument. - Before running any script that needs an API key: source both the data home's
.envand the current directory's.envinto the shell so scripts can read stored keys:set -a; [ -f "$AK_HOME/.env" ] && . "$AK_HOME/.env"; [ -f "./.env" ] && . "./.env"; set +a(where$AK_HOMEis the path printed on theAK_HOME:line above). Full lookup order — always check these before concluding a key is missing or asking the user:- current shell environment
$AK_HOME/.env(keys stored byanalyst-kit-setup).envin the current working directory Never ask the user for a key that is already present in any of these locations.
MISSING_KEYSnotnone→ for each listed key withKEY_PROMPTED_<KEY>: no: explain where to get it, ask for the value, and run"$_AK/bin/analyst-kit-setup" set-key <KEY> <value>. If declined, run"$_AK/bin/analyst-kit-setup" skip-key <KEY>(this disables the skills that need it) and continue — never block the skill.UPGRADE: UPGRADE_AVAILABLE <old> <new>→ say "Analyst Kit skills <new> is available (you have <old>) — update?". If yes: Read"$_AK/references/upgrade.md"and follow it. If declined: run"$_AK/bin/analyst-kit-update-check" --snooze <new>.LEARNINGSentries shown → these are past mistakes/preferences for this user; respect them and do not repeat logged pitfalls.
Then proceed with the skill. At the very end, run the Completion block at the bottom of this file.
<!-- analyst-kit:preamble:end -->Reporting — storyline → branded PDF
This skill does exactly one job: take a storyline — an ordered set of pages, each with its point, plus the already-generated UI elements (chart contracts) and data (tables, text) — and turn it into a beautiful PDF. It does not decide what the report should say: the storyline arrives pre-decided (from the user, the orchestrating agent, or an upstream skill). Reporting owns only the layout and the rendering.
storyline (pages, each: point + modules + data)
─► report contract (JSON)
─► bun scripts/render.ts contract.json out/report.pdf
A JSON report contract encodes the storyline against shipped templates. One script assembles a self-contained HTML document (Highcharts vendored from the sibling charting skill, inlined once — no network at render time) and prints it to PDF with Playwright.
Designing a page — think in this order
For every page of the storyline, answer three questions in order:
- What is the main point of this page? One sentence. It goes in the page's
storyslot (required on every data page) and renders as a banner under the title — the reader gets the conclusion before the evidence. Put the headline numbers the user actually asked for (entry/exit price, latest YoY, the verdict) instatschips right below it. - Which modules does the point need? Chart, table, commentary, rating matrix, layer cards — pick the template whose modules match.
- How do the modules arrange? Pick the mode (
report= portrait A4 document,presentation= 16:9 deck) and let the template lay the modules out. One point per page — if a page is making two points, split it.
A page with lots of empty space or no story is a page whose point was never
decided — fix the storyline, not the CSS.
Style defaults
These are the house style. Apply them on every report unless the user explicitly overrides one for a given report — and a per-report override never changes the defaults themselves.
- Information-dense. Professional research layout: 10pt body, tight vertical rhythm, evidence (charts/tables) gets the reclaimed space. Never pad a page to fill it. The cover is the one deliberately airy page.
- Conclusion first. Every data page opens with the
storybanner, thenstatschips carrying the headline numbers the user asked for (entry/exit, latest YoY, the verdict). - Levels live on the chart. Any price level the commentary mentions
(support, resistance, entry, exit, moving averages) is also drawn on the chart
via
levels— green for support/entry, red for resistance/exit, gray otherwise. - References are always the last page. The renderer appends it automatically
from the required top-level
referencesarray; every data page cites into it withsources: [n], rendered as linked[n]footnote marks in the footer. - One point per page. Two points = two pages. Row caps (7 companies, 10 table rows per slide) are enforced.
- Modes.
report= portrait A4 multi-page document;presentation= 16:9 landscape deck (Google Slides geometry). Default toreportunless the user asks for a deck/presentation/slides. - Branding. Persisted
report-brand/brand.jsonapplies silently; built-in default theme otherwise. Page numbers on (skipped on cover);meta.footerrepeats on every page. - Charts are print-tuned. No navigator/range selector/animation; vendored Highcharts inlined so the PDF renders offline; chart contracts in, never pre-rendered chart HTML.
When the user overrides ("make it airy", "skip the references page", "no story
banners"), honor it for that report only and say so in your summary. The
renderer hard-enforces #4 and the story slot — for those, an override means
filling them minimally (e.g. a single reference), not skipping them.
Fast path
bun scripts/render.ts report.json out/report.pdf # the one command
bun scripts/render.ts report.json out/report.html --html-only # no Playwright needed
bun scripts/render.ts report.json out/report.pdf --keep-html # keep the HTML beside the PDF
bun scripts/render.ts report.json out/report.pdf --brand x.json # one-off brand override
Minimal contract (templates/examples/ has full ones for both modes):
{
"meta": { "mode": "report", "title": "Roblox (RBLX) — Bookings vs Revenue" },
"pages": [
{ "template": "cover", "slots": { "title": "Roblox (RBLX)", "kicker": "Equity Research" } },
{ "template": "price-chart-technicals", "slots": {
"title": "RBLX — price action",
"story": "Price is consolidating above the 200-day — the uptrend is intact.",
"chart": "./out/price-contract.json",
"levels": [ { "value": 42, "label": "Support $42", "kind": "support" } ],
"commentary": [ { "heading": "Trend", "body": "Uptrend intact above the 200-day." } ],
"sources": [1] } }
],
"references": [
{ "label": "Daily OHLC price data, RBLX", "detail": "Exchange consolidated tape" }
]
}
meta.mode:"report"= portrait A4 document ·"presentation"= 16:9 landscape deck.- Paths inside the contract (chart contracts, brand, logo) resolve relative to the contract file.
meta.footertext repeats on every page; page numbers are automatic (skipped on cover).references(top-level) is required — the renderer auto-appends a References page as the always-last page. Pages cite into it withsources: [1, 3](1-based); citations render as[n]links in the page footer, anchored to the reference entry.
One-time setup
cd <this skill's directory> && bun install && bunx playwright install chromium
render.ts tells you exactly this when Playwright is missing. Environments that
already provide browsers via PLAYWRIGHT_BROWSERS_PATH (e.g. the e2e container) skip
the browser download. If PDF printing is unavailable, fall back to --html-only and
convert with any HTML→PDF tool (the e2e container ships html2pdf).
Branding
Brand config lives in the project working directory at report-brand/brand.json
so it survives skill reinstalls and is reused across reports:
{
"company": "MK Capital",
"logo": "./logo.png",
"logoPlacement": "top-left",
"colors": { "primary": "#1a3c6e", "accent": "#e8a33d", "panel": "#f5f7fa" },
"footerText": "MK Capital — Confidential"
}
- First use: if
./report-brand/brand.jsondoesn't exist, ask the user once: "Want branded reports? Upload a logo and tell me your brand colors (or say skip)." On an answer, writereport-brand/brand.jsonand copy the logo file in yourself. On "skip", proceed with the default theme and don't ask again this session. - Present: use it silently; mention which brand was applied in your summary.
- Per-prompt override ("make this one red"): write a one-off brand JSON and pass
--brand; never mutate the persisted file unless the user says to update their brand. - Precedence:
--brandflag >brand(inline object) in contract >brand(path) in contract >./report-brand/brand.json> built-in default. - Logo formats: png / jpg / svg / webp; it's inlined as a data URI. Colors omitted from
colorsfall back to the default palette.
Templates
| Template | Required slots | Optional slots | Typical source |
|---|---|---|---|
cover | title | subtitle, kicker, date | — |
comparison | title, story, companies (2–7) | subtitle, stats, takeaway, source | thematic-investing sensitivity / exposure tables |
industry-breakdown | title, story, layers (2–9) | subtitle, stats, takeaway, source | thematic-investing value-chain map |
price-chart-technicals | title, story, chart, commentary (1–4 blocks) | subtitle, stats, levels, sources | charting price builder + technical-analysis levels |
table-commentary | title, story, table, commentary | subtitle, stats, sources | sec-filings KPIs, any tabular data |
(references is not a template you place — the renderer always appends it last.)
Slot shapes:
-
story — required on every data page. The one-sentence point of the page, conclusion-first (supports
**bold**). Renders as a banner under the title. -
stats —
[{ "label": "Entry", "value": "$215" }]key-number chips rendered under the story on any template. Put the numbers the user asked for here. -
levels —
[{ "value": 215, "label": "Support $215", "kind": "support" }]onprice-chart-technicals: horizontal lines drawn on the chart with colored labels.kind:support/entry= green,resistance/exit= red, omitted = gray. Always plot the levels the commentary talks about. -
sources —
[1, 3], 1-based indices into the top-levelreferencesarray; rendered as linked[n]citations in the page footer. -
chart — a path to a charting contract JSON (preferred), or
{ "image": "chart.png" }as an escape hatch. Never pass charting's pre-rendered HTML pages; reporting renders contracts itself, print-tuned (no navigator/range selector, fixed height, animations off). -
companies —
{ "name", "ticker", "mechanism", "ratings": { "narrative", "revenue", "profit", "purity" } }with each rating"high" | "medium" | "low"(rendered as colored pills). -
layers —
{ "name", "role", "scarcity": "scarce" | "contested" | "commoditized", "tickers": ["..."] }, ordered upstream → downstream. -
table —
{ "columns": ["..."], "rows": [["...", "..."]] }. Cells are pre-formatted strings — format numbers upstream (units,$/%, accounting negatives) per charting's data-unit conventions. -
commentary / takeaway —
{ "heading", "body" }; body supports**bold**,*italic*, and-bullet lines only.
Default skeleton when the storyline isn't fully specified: cover → one chart page →
table-commentary. For "make a deck/presentation", same storyline with
meta.mode: "presentation" and one point per slide.
Rules
- Storyline in, PDF out — nothing else. Don't gather data, build charts, or invent narrative here; that happens upstream. If the storyline is missing a page's point, push back upstream rather than padding the page.
- Every data page states its point.
storyis required; the renderer errors without it. Headline numbers go instats, not buried in prose. - Compute upstream, never in prose. Numbers come from the data pipelines (charting's Polars layer, sec-filings extracts) already formatted; this skill only lays them out.
- One point per page/slide. Respect the row caps (7 companies, 10 table rows per slide) — the renderer errors past them; split across pages.
- Information-dense, not airy. These are professional research documents — a half-empty page means the storyline gave that page too little to say.
- Always cite. Top-level
referencesis required (the renderer errors without it); every data page should carrysources: [n]pointing into it. Levels the commentary mentions must also be drawn on the chart vialevels. - Don't hand-write report HTML. If a layout doesn't exist, add a template function
to
scripts/render.tsand styles toassets/styles.css. - The renderer fails loudly: unknown templates, missing slots, missing chart contract files, and charts that produced no SVG all exit non-zero — read the message.
Files
scripts/render.ts— the whole pipeline: contract → HTML → PDF.assets/styles.css— page geometry (@page), template layouts, brand CSS variables.assets/default-brand.json— fallback brand.templates/examples/— a full report contract and a full presentation contract; copy one as your starting point.
Completion (run last)
Audit before you deliver. If this run produced a research deliverable carrying
quantitative or factual claims — a deep dive, thematic/value-chain map, technical
call, company wiki, or financial model — you MUST verify it before presenting it.
If a research-auditor subagent is available (the analyst-kit plugin ships one),
invoke it via the Task tool, handing it the draft and the data artifacts you used;
on a runtime without subagents, run the same checks yourself. Resolve every
CRITICAL finding and disclose any UNVERIFIED ones; never deliver on a FAIL
verdict without fixing it first. Skip this only for pure data-fetch/utility runs
with no analytical claims.
PLAN MODE EXCEPTION — ALWAYS RUN: writes only to ~/.analyst-kit/. Replace OUTCOME with one
of DONE | DONE_WITH_CONCERNS | ERROR | ABORT | NEEDS_CONTEXT.
_AK="$(cat ~/.analyst-kit/core-path 2>/dev/null)"
[ -x "$_AK/bin/analyst-kit-log" ] && "$_AK/bin/analyst-kit-log" end --skill reporting --outcome OUTCOME 2>/dev/null || true
If this session surfaced a durable pattern, pitfall, or user preference that would save 5+ minutes next time (not obvious, not a transient error), also log it:
"$_AK/bin/analyst-kit-learn" add '{"skill":"reporting","type":"pitfall|pattern|preference","ticker":"<optional>","insight":"<one line>","confidence":7,"ts":"<iso8601 utc>"}'
<!-- analyst-kit:epilogue:end -->