# Agentic Reporting > Create and finalize task-appropriate, evidence-calibrated agent reports, research ideas, experiment readouts, academic presentations, and handoffs. Use for substantive progress or final reports, implementation handoffs, investigations, experiment analysis, decisions, risks, incidents, postmortems, reviews, academic synthesis, research proposals, and reports that must present figures, tables, HTML/PPT-style slides, or multiple artifacts. Also use near the start of likely long, multi-session, or multi-agent work to save a tiny reporting checkpoint, and at its final reporting boundary. Do not use for casual conversation, exact-format transformations, raw code-only output, or trivial direct answers. - Skill: `asimfish/agentic-reporting` (Agent Skill, multi-file: 61 files) - Install (CLI): `npx skillmds@latest add asimfish/agentic-reporting` - Raw SKILL.md: https://api.skillmd.com/api/skills/asimfish/agentic-reporting/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: asimfish (https://skillmd.com/u/asimfish) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/asimfish/agentic-reporting --- # Agentic Reporting Present the latest task state in the shortest structure that lets the reader find the outcome, evidence, boundary, and useful next action. This skill governs presentation; it never changes task facts or replaces domain-specific verification. ## Non-negotiable priority Follow the user's requested surface, schema, length, and ordering when explicit. Then follow host instructions. Use this framework only to fill unspecified choices. Never invent evidence, tests, citations, metrics, files, owners, dates, or completion. ## Bookend workflow 1. Classify the handoff by audience, surface, evidence boundary, and exactly one primary mode. For research work, select at most one domain profile. Use `list` or `route` when uncertain. 2. Scale ceremony to the task. For a short, single-session answer, do not create a checkpoint, a draft file, or a script audit: apply the routed mode's structure directly, self-check its required semantics, and deliver; the file-backed ceremony in steps 4-6 is for long, multi-session, multi-agent, or durable-artifact work. For a long, multi-agent, or multi-session task, save a compact checkpoint near the start; for a short task, defer routing until the reporting boundary. 3. Complete and verify the actual task. Keep task execution independent of report styling. 4. Immediately before a substantive update or final answer, retrieve one bounded bundle. Prefer one display module; add a second only for a distinct need that the primary mode and first module do not already cover. Never load a module merely because the requested output names a semantic that the selected mode already specifies: Resolve `` to the directory containing this `SKILL.md`; do not assume the caller's working directory is the skill directory. ```bash python3 /scripts/reportctl.py bundle \ --task "" --mode --surface \ [--profile ] [--module ] [--module ] \ --max-chars 16000 ``` If resuming a long task, pass `--checkpoint ` instead of reconstructing the route from memory. `--max-chars` is an independent context budget: a valid checkpoint with two large modules can require an explicitly larger value. Do not read every mode, module, or template. 5. Draft natively for the selected surface. When the route recommends an exact asset, inspect the cheap registry and retrieve one asset only: ```bash python3 /scripts/reportctl.py template --list python3 /scripts/reportctl.py template \ --output ``` Use one primary delivery artifact; do not create parallel Markdown, HTML, PPTX, and PDF versions unless requested. A copied template is a starting artifact, not evidence that its placeholders, visuals, or claims are correct. After the content is complete, give the prose a de-AI tone pass: cut sycophantic openers, performative summaries, inflated jargon, and template rhetoric under the `natural-tone` module's fidelity contract. Tone edits never change facts, relations, scope, or numbers; the audit's `ai-tone-boilerplate` warnings catch only the highest-precision residue. In the research modes (experiment-report, academic-synthesis, research-idea), also check that every success rate carries `k/n` and a binomial interval, every `significant` carries its test and effect size in the same sentence, and no verb attributes understanding or intent to a system. The audit's `success-rate-without-denominator`, `significance-without-statistic`, and `anthropomorphic-claim` warnings catch the mechanical residue; the profiles and the conclusions module carry the full rules. Number presentation has its own residue checks in the same modes: `unlabeled-uncertainty` (a `±` that never says SD, SEM, or CI), `threshold-p-value` (`p < 0.05`, `n.s.`), `p-value-without-effect-size`, `null-result-without-interval`, `significance-euphemism` (`approached significance`), `up-to-without-central-tendency`, and `best-of-n-runs`. 6. Before a long-task or durable-artifact final, audit a file-backed draft. A long task must use the same checkpoint; a durable artifact without one uses its selected mode: ```bash python3 /scripts/reportctl.py audit \ --file --checkpoint # Short, non-checkpointed path: python3 /scripts/reportctl.py audit --file --mode ``` The checkpoint derives the mode. Supplying the same explicit mode is allowed; a conflicting mode is an input error. Fix audit errors. Resolve warnings with judgment; never add unsupported filler merely to satisfy a heuristic. The repository's `docs/AUDIT-CODES.md` lists every code with its trigger and fix. With `--json`, the audit payload includes the exact report byte count/SHA-256 and the parsed checkpoint intent fingerprint for controller binding. 7. For a durable artifact, or any report that carries figures, derived numbers, or threshold judgments, run a cross-model semantic review before delivery. The audit checks form; this step checks meaning, and it must be done by a model other than the one that drafted the report (same-model review shares the author's blind spots): ```bash python3 /scripts/reportctl.py review-prompt \ --file --mode [--facts ] # Hand the printed prompt to a second model; fix every confirmed # blocker/major finding; re-run the audit on the revised draft. ``` The prompt asks for claim-versus-visual consistency, derived-number premises, reasoning validity, unsurfaced source contradictions, fidelity to the facts, the reader contract, and domain-term correctness, and returns a fixed `FINDINGS / VERDICT` structure. Treat `revise` as blocking. 8. Manually verify the latest state, scientific or technical claims, numbers, evidence links, uncertainty, visual interpretation, and user-specified format. ## Final delivery The user-visible final response must contain the report itself. A path, link, or pointer to a saved draft, checkpoint, or audit receipt is not a deliverable: after a checkpoint-backed audit passes, deliver the audited draft content as the response. When the user explicitly requested a file, still lead with the outcome inline. Never expose local absolute paths, scratch directories, or checkpoint locations in the reader-facing response. ## Mode and module selection Use `python3 /scripts/reportctl.py list` for identifiers. Choose the primary narrative spine, not every applicable label. For a mixed task, select the mode that answers the user's main decision or question and embed secondary facts inside it. - Use `concise-answer` for direct answers with little supporting structure. - Use `implementation-handoff` for built or changed artifacts. - Use `status-update` for project progress that is not an active incident. - Use `investigation-report` for diagnosis or source-backed inquiry. - Use `experiment-report` for controlled evaluations and empirical comparisons. - Use `decision-brief` or `risk-report` when a choice or exposure is primary. - Use `academic-synthesis` for paper or literature presentation. - Use `research-idea` for a paper idea or proposal whose hypotheses, novelty, decisive experiment, risks, and kill criteria must remain explicit. - Use `review-report` for findings against an artifact or standard. - Use `incident-update` while impact is active; use `postmortem` after recovery. Figures, tables, conclusions, evidence detail, and academic display are orthogonal modules, not reasons to merge multiple modes. A visual must make a relationship or artifact materially easier to understand; decoration is not a valid reason. `experiment-report` already contains result interpretation, uncertainty boundaries, and a calibrated conclusion. Do not add `conclusions` to that mode merely because the request asks for a conclusion; add it explicitly only when a separate decision or recommendation policy is genuinely needed. ## Research profiles and presentation surfaces Profiles are one bounded domain overlay, not additional primary modes: - `reinforcement-learning`: run accounting, tuning parity, learning curves, interval estimates, and multi-task aggregate evaluation. - `embodied-ai`: embodiment, sensors/actions, simulation versus real protocols, success rules, interventions, generalization, and failures. - `world-models`: model/data cards and separate open-loop, closed-loop, scaling, and transfer evidence. - `vla`: data mixtures, morphology and action interfaces, adaptation regimes, rollout accounting, latency, generalization, and safety. Automatic selection is available only for research-oriented modes. A schema-v2 checkpoint does not store a new profile field; the profile is re-derived from its fingerprinted task text. Therefore, when explicitly selecting a profile for a long task, name the domain in the checkpoint task so final retrieval is reproducible. For `--surface slide`, read the routed slide guide. It provides paper-talk, research-progress, experiment-review, and idea-pitch narratives. Retrieve either the dependency-free HTML/PPT-style deck or the Quarto Reveal.js source, not both, unless the user requests multiple formats. ## Long-context persistence Do not keep the full reporting bundle in working context. Save only a checkpoint: ```bash python3 /scripts/reportctl.py checkpoint \ --task "" --mode --surface \ --must-show "" \ --output /agent-report.json ``` Schema-v2 `--must-show` values are normalized literal anchors, not semantic requirements: the audit applies NFC normalization, case folding, and whitespace collapse, then checks literal substring presence only in blank-line-bounded, column-zero, plain top-level Markdown prose paragraphs. A paragraph containing a heading, quote, list, table, link/reference, image, code, or raw HTML is ineligible. After the first unmasked raw HTML tag, no later paragraph receives credit because the proxy does not model cross-paragraph DOM or CSS state; raw HTML is also a structural audit error. Each anchor must match within one eligible paragraph. Soft line breaks inside that paragraph collapse to spaces, but blank-line paragraph boundaries never do. Before normalization the report proxy decodes one round of the shared scanner's supported, semicolon-terminated CommonMark entity subset, but only when the entity's `&` is not escaped by an odd-length backslash run. A resulting control or Unicode non-rendering character makes the gate fail. V2 anchors must use exact rendered plain text and reject Markdown delimiter forms. Put each short anchor in a standalone ordinary conclusion sentence before any raw HTML. This proxy does not verify what the text means, who asserted it, or whether it is true. Each anchor is at most 120 characters and their escaped receipt, including separators, is at most 240 characters. Checkpoint-backed audit accepts reports up to 1 MiB so the prose proxy stays resource-bounded. Any eligible plain-prose paragraph above 4,096 characters or with more than 64 consecutive Unicode mark characters is an error and is skipped before NFC and anchor matching. The legacy mode-only audit remains capped at 4 MiB; this larger limit does not apply when `--checkpoint` is present. Bounded JSON inputs reject integer or floating-point tokens above 128 characters before conversion. The checkpoint stores the objective, audience, surface, modules, and anchors verbatim, plus routing metadata and unkeyed checksums. The checksums detect accidental drift; they do not authenticate the file. Do not put secrets or unnecessary private data in any field. Use a private scratch path outside version control, remember that `route`/`bundle` can replay checkpoint text to stdout, and remove the file when resume is no longer needed. Atomic creation uses restrictive file permissions on POSIX, but cannot protect a permissive parent directory, logs, backups, or a committed file. At the final boundary, reload it with `bundle --checkpoint ` and run `audit --file --checkpoint `. Schema-v1 checkpoints remain readable by `route` and `bundle`, but cannot drive this final gate; recreate or upgrade a valid v1 file with `checkpoint --checkpoint --output `. The host-recognized micro-contract is intended to prompt both bookends; neither it nor the checkpoint can force an arbitrary agent to comply. ## Strict mode for durable reports When a wrapper, batch workflow, or formal report needs stronger structural consistency, start from `assets/templates/report-spec.json`, validate it with `validate-spec`, and render Markdown deterministically with `render`. Treat the JSON as the single presentation source, but verify all facts against original evidence. Every claim declares one or more semantic `roles`; validation derives the remaining coverage from evidence, metrics, uncertainty, actions, and limitations, then enforces the selected mode's current `required_semantics` from the protocol catalog. The bundled JSON Schema is a portable structural preflight, not a replacement for `validate-spec`; only the CLI enforces ID uniqueness, cross-record references, and the current protocol catalog together. ```bash python3 /scripts/reportctl.py validate-spec --file report.json python3 /scripts/reportctl.py render --file report.json --output report.md python3 /scripts/reportctl.py audit \ --file report.md --checkpoint --strict ``` Use `--mode ` instead when this is a short task with no checkpoint. Do not require the structured path for a normal short chat response. ## Fallback when scripts are unavailable Within an installed skill, read `references/core-contract.md`, one matching file under `references/modes/`, at most one matching file under `references/profiles/`, at most two matching files under `references/modules/`, and one surface guide only when needed. Retrieve one exact asset separately. For link-only repository use, open `dist/agent-index.md` at the repository root. If only a URL was supplied, treat adherence as best effort: a link does not install or elevate repository instructions.