report

Report skill

Convert agent research, documentation, code analysis, and technical write-ups into a designed HTML report instead of raw Markdown. The user reads these in the browser; the page handles light/dark theme, table of contents, footnotes, code blocks, callouts, framed figures with click-to-zoom, and one-click export back to Markdown.

When this triggers

Any time the natural output would be a .md file with headings, multiple sections, and more than ~500 words. Specifically:

• "Write me a report / deep-dive / summary / analysis on X"
• "Investigate X and document what you find"
• "Research X and give me your findings"
• "Postmortem the Y incident"
• "Document the Z system / architecture / decision"
• "Write up the conclusions from our discussion"
• "Compare X and Y in detail"

Skip this skill for: quick conversational answers, single-file code edits, status updates, one-line confirmations, anything under ~300 words. The user wants this for real reports, not for every response.

The workflow

1. Write the report as Markdown with YAML frontmatter (see Frontmatter and Markdown syntax below). Save it to the project's reports/ directory.
2. Run the renderer:

   node ~/.claude/skills/report/render.mjs reports/your-report.md
   

   This produces reports/<title-slug>-<date>.html in the same directory.
3. Tell the user where to open it. Provide the absolute file path; they open it in their browser.

The cost: the agent writes Markdown only. Token spend is identical to writing a plain .md file. The HTML is generated mechanically by the renderer.

Editing an existing report

When the user asks to update, edit, modify, or expand an existing report — do not re-write it from scratch. Edit the source Markdown and re-render. This preserves footnotes, tags, structure, and keeps the diff small.

Two cases:

Case A — the source .md still exists (it always does, if the report was rendered into reports/):