Skip to content

stark-ai-de/agent-skills / plugins/stark-ai-developer/skills/visual-reports

visual-reports

Verified

Create and update visual reports with optional native interaction, one guided topic at a time, useful diagrams, concise points, joint comparisons and complete offline HTML/Markdown/JSON exports. Use when richer output helps an authorized answer or the user asks for a visual report; keep small answers in chat. Not production application UI or clinical advice.

FileKindSize
SKILL.mdskill md11.5 KB
agents/openai.yamlconfig779 B
assets/completion-example.mdmarkdown3.2 KB
assets/graphite-grain/configurator.htmlother17.7 KB
assets/graphite-grain/configurator.mjsscript6.9 KB
assets/graphite-grain/relaxed.cssother4.2 KB
assets/openai-icon.pngbinary10.3 KB
assets/openai-icon.svgother318 B
assets/preview.jsscript3.4 KB
assets/report-recipes.mjsscript19.2 KB
assets/report-runtime.cssother16.4 KB
assets/report-runtime.jsscript23.9 KB
assets/report-shell.htmlother14.1 KB
references/comparisons.mdmarkdown4.8 KB
references/filesystem-handoff.mdmarkdown4.7 KB
references/managed-reports.mdmarkdown5.2 KB
references/markdown-input.mdmarkdown3.9 KB
references/model-v2.mdmarkdown10.1 KB
references/renderer.mdmarkdown24.5 KB
references/report-contract.mdmarkdown33.1 KB
references/selection.mdmarkdown4.8 KB
scripts/benchmark.mjsscript2.2 KB
scripts/cache_icon.pyscript9.2 KB
scripts/export-assets.mjsscript4.1 KB
scripts/lib/blocks-v2.mjsscript21.7 KB
scripts/lib/cli.mjsscript3.7 KB
scripts/lib/export-path.mjsscript1.6 KB
scripts/lib/generator-entry.mjsscript472 B
scripts/lib/markdown-input.mjsscript9.8 KB
scripts/lib/preview.mjsscript4.9 KB
scripts/lib/report-state.mjsscript13.4 KB
scripts/lib/report-store.mjsscript7.0 KB
scripts/lib/templates.mjsscript4.7 KB
scripts/render-report.mjsscript40.0 KB
tests/browser-delivery.mjsscript25.4 KB
tests/browser-smoke.pyscript15.5 KB
tests/browser-topics.mjsscript21.1 KB
tests/cache-icon.test.mjsscript5.0 KB
tests/export-assets.test.mjsscript5.5 KB
tests/render-report.test.mjsscript14.3 KB
tests/report-state.test.mjsscript11.7 KB
tests/topics.test.mjsscript6.4 KB
tests/v2.test.mjsscript21.1 KB
---
name: visual-reports
description: Create and update visual reports with optional native interaction, one guided topic at a time, useful diagrams, concise points, joint comparisons and complete offline HTML/Markdown/JSON exports. Use when richer output helps an authorized answer or the user asks for a visual report; keep small answers in chat. Not production application UI or clinical advice.
license: Apache-2.0
metadata:
  author: stark-ai-de
  category: engineering-workflows
  version: "1.3.1"
---

# Visual Reports

## Goal

Make the answer, decision or next action easy to find. Use the shared renderer,
clear hierarchy, short lists and meaningful visuals. Identify whether the reader
needs an action, a decision or a summary before choosing the format. Preserve facts, evidence
states, sources and decisive limitations. Do not invent quantities to fill charts.

Prefer a native interactive visualization as the primary view when the current host can invoke and display one that fully serves the report. Otherwise display the verified HTML report. Keep the same concise reader contract and complete HTML, Markdown and JSON exports from one validated snapshot in either case. Follow [presentation selection and fallback](references/report-contract.md#native-presentation-and-html-fallback).

For v2 reports, the shared renderer starts with one guided topic at a time. Group
related sections into topics; keep a meaningful diagram above concise points and
keep genuine comparisons together. The author explicitly selects `reading` or
`slides` when requested. Follow [the reading contract](references/report-contract.md#guided-reading-when-supported)
for layout, accessible navigation and source fidelity.

## When to use

Use reports for comparisons, multi-step plans, relationships and data-rich findings
within the authorized answer. Keep tiny answers in chat.

## When not to use

Do not use for production application UI, unrelated artwork, external service
operation or medical/clinical advice.

## Workflow

| Route                | Authorized outcome                                             | Read when selected                                                                                                                             |
| -------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Create or update     | Complete report from the same source snapshot                  | [Reader experience](references/report-contract.md#reader-experience), [selection](references/selection.md), [v2 model](references/model-v2.md) |
| Preview and continue | Stable local URL, version history, explicit revision switching | [Managed reports](references/managed-reports.md)                                                                                               |
| Present or prototype | Slides, opt-in motion or validated state simulation            | [Legacy blocks and 24 recipes](references/renderer.md)                                                                                         |
| Edit locally         | Board, flags or prompt draft with separate export              | [Editor contract](references/renderer.md#browser-state-exports-and-safety)                                                                     |
| Explore styles       | Current, balanced and calm previews with identical facts       | [Presentation](references/report-contract.md#presentation-and-styles)                                                                          |
| Adopt preference     | Persist an explicitly selected style in ignored local state    | [Preference contract](references/report-contract.md#local-preference)                                                                          |

For clear intent, announce the route and proceed. For a bare invocation or options
request, show the complete inventory; options alone authorize no execution.
Choose a report automatically when it improves the authorized answer, especially
comparisons, relationships, multi-step plans or data-rich findings. Keep one fact
or a short action in chat. Do not impose an interview or a chart-count quota.

## Inputs to inspect

Inspect the reader question, authoritative sources, current model/revision, evidence
gaps, reviewed assets, repository policy and explicitly selected preferences.

### Work quickly from existing context

1. Read [Reader experience](references/report-contract.md#reader-experience): distinguish information,
   completed work, required action and conditional action. A compact labeled status
   is enough; do not repeat it as a question, legend and introductory step.
   Use `--templates` to select one of eight
   purpose templates and five domain profiles. Read only the needed references,
   profile requirements and examples. Do not load an external catalog per report.
2. Inspect source authority and evidence gaps. For a continuation, read the current
   model/revision and reuse its IDs, reviewed assets and sources. Keep consumer
   source registers authoritative; do not replace them for a presentation change.
3. Set the topic sequence before selecting visuals. Follow [the guided reading form](references/report-contract.md#guided-reading-when-supported)
   on the first draft: group each topic's diagram and bullets in the documented
   `topics` model and place a useful graphic before its explanations. Use a chart
   only for actual quantitative data. Preserve explicitly requested layouts; `reading`
   and authored `slides` remain available. Follow [layout and navigation](references/report-contract.md#guided-layout-and-navigation).
   Lead with the result or a real next action; a summary needs no invented task.
   Apply the self-contained ADHD writing profile when requested.
4. Compose registered blocks freely. Use comparison matrices for common criteria,
   automatic diagrams for structure and data charts for quantities. Use labeled
   bundled icons and verified product logos when they clarify the content.
   Preserve units, scale, direction, nulls and status semantics.
5. Render with `scripts/render-report.mjs`. JSON v2 is canonical; v1 remains
   supported. Optional [Markdown input](references/markdown-input.md) compiles to
   the same model. Do not execute MDX or infer evidence from typography.
6. Produce HTML, full Markdown and JSON from one snapshot. Use an exclusive output
   directory or a managed store with expected-base updates. Use the host's
   session-local visualization directory when provided. HTML remains readable
   offline without JavaScript. No per-report dependency installation or network.
7. Select and verify the primary presentation using [native presentation and HTML fallback](references/report-contract.md#native-presentation-and-html-fallback). If native is unsuitable, unavailable or unverified, display the HTML report through an actually verified host opening route. For requested visual delivery/iteration, reuse the session-owned preview and browser tab where possible; start a loopback preview if needed. Verify the actual URL and honor host browser-tool restrictions. Offer the desktop browser tab and Microsoft Edge where available. New versions require Apply; unsaved drafts block replacement.
8. Keep exports, style and version controls in a closed, labeled footer toolbox,
   separate from report content. Check semantic duplication, fidelity, relevant
   interactions and delivery. Use the bounded owning tests
   when changing the renderer; ordinary report content changes need only the
   relevant validation/visual checks. Report measured speed separately from model
   generation, research, cold start and first asset retrieval.

## Scripts

From the skill directory, with Node.js:

```sh
node scripts/render-report.mjs --templates
node scripts/render-report.mjs --starter comparison --profile software --id options
node scripts/render-report.mjs --input /absolute/report.md --output /absolute/new-report
node scripts/render-report.mjs --create /absolute/report-store --input /absolute/report.json
node scripts/render-report.mjs --update /absolute/report-store --input /absolute/report.json --base REVISION
node scripts/render-report.mjs --preview /absolute/report-store
node scripts/render-report.mjs --extract /absolute/report.html --section comparison
node scripts/render-report.mjs --gallery /absolute/new-gallery
```

`--current` and `--history` read a managed store. `--help` prints the full CLI.
`node --test tests/*.test.mjs` validates the skill with temporary local fixtures.
`node scripts/benchmark.mjs` measures the mixed fixture and enforces warm p95 < 1 s.
`scripts/export-assets.mjs` exports only explicitly requested, committed,
digest-pinned consumer bundles; `--check` is read-only. It does not update pinned
consumers automatically.

`scripts/cache_icon.py` fetches only an explicitly selected reviewed public asset
into an already ignored cache, with identity, source, retrieval date and digest.
Inspect it before embedding. The renderer never fetches assets. Original code is
Apache-2.0; bundled dependencies retain their [notices](assets/vendor/NOTICE.txt).
No external skill text is copied.

## Safety rules

- Unknown is not zero or absent. Planned is not delivered; fictional is not measured.
  A healthy-sample fraction is not elapsed-time availability.
- Browser filters never alter source exports. Local editor drafts never mutate
  source files or external services. Export or explicitly discard before switching.
- Motion is opt-in, stoppable and suppressed for reduced-motion preferences.
- Generation and loopback preview do not authorize deployment, upload, production
  mutations or permanent preference changes.
- Treat markup and SVG as untrusted. Reject unsupported input with its field/line;
  never delete data or fabricate values just to pass validation.
- If a source or logo is unavailable, mark the gap and retain the readable name.
  If a stale update fails, inspect the new current model and reconcile deliberately.
- Keep caches, preferences, private sources and report stores out of commits.
  No clinical, WCAG-compliance or universal host-compatibility claims from fixtures.

## Output format

Deliver the verified native view when suitable, otherwise the verified HTML preview/opening route, plus standalone HTML and complete
exports. State significant source gaps and actual verification limits. If files
changed, include a concise verified affected-file tree with added/changed/moved/
deleted/context labels and maintained/generated/local ownership as described in
[filesystem handoff](references/filesystem-handoff.md).

## Completion criteria

Confirm source fidelity, visible caveats, full exports and the actual display or HTML opening route.
Record unrun gates without implying they passed.

## Failure modes

Reject invalid input with field/line diagnostics. Reconcile stale bases before
retrying. Preserve unsaved drafts and report blocked preview routes explicitly.

## References

[Reader experience](references/report-contract.md#reader-experience) owns intent, guided reading,
summary/action states, footer tooling and the ADHD writing profile. The same
contract owns the default topic sequence, optional tabbed presentation, shared
alignment and content-sized pages without internal scrolling.
The [general report contract](references/report-contract.md) governs source
fidelity and reader presentation. [Comparisons](references/comparisons.md) adds
shared-criteria and evidence rules; [selection provenance](references/selection.md)
records independent mdxcn-inspired choices and upstream references.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall