html-output

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: html-output
description: >-
  HTML output generator for output that would benefit from being presented in
  a visually rich document. Use when communicating architectural plans, design
  options, code review summaries, workflows, comparisons, novel concepts, color
  choices, or any information that benefits from visual illustration — inline
  SVG diagrams, color swatches, structured comparison grids, interactive
  controls. Not needed for simple lists, linear text, or straightforward data
  using well-understood terminology.
compatibility: Any agent harness supporting HTML output
author: Mike Scott
version: '1.1.0'
updated: '2026-08-04'
---

# HTML Output

Generate self-contained HTML documents instead of Markdown when the
information benefits from visual illustration. Read the supporting files
below as needed for the specific task.

## Output Location

Resolve the output directory in this order — **derive it from the task first;
only fall back to configuration when the destination is not obvious.**

1. **Task-derived destination** — when the workflow makes the destination
   explicit, use it and skip all configuration:
   - ADR creation → the project's ADR HTML directory (see the `adr-creation`
     skill; mirror where the project's existing ADR markdown lives, e.g.
     `wip/docs/adr/` → `wip/docs/adr/html/`).
   - The user names a destination → use exactly that.
   - The source document lives in the repo (e.g. `docs/mvp/`) → a sibling
     `html/` subdirectory next to it.
2. **Project settings** — `htmlOutputDir` in the project's `.pi/settings.json`
   (project-scoped custom convention).
3. **Global settings** — `htmlOutputDir` in `~/.pi/agent/settings.json`
   (machine-wide default; must be a general-purpose directory, never a
   project-specific path).
4. **Fallback** — use `~/.pi/agent/html-output/` (creates it if needed).

The configured directories are fallbacks for ambiguous output, not the
primary mechanism. Never write a project-specific path (e.g. a client repo's
`docs/adr/html`) into the global settings file — that leaks one project's
layout into every other project's sessions.

Name files descriptively, e.g. `oauth-flows-explainer.html`.

### Presenting the result

When the file is written, present the clickable link to the user on its own
line, prefixed with the pointing-finger emoji:

👉 **`file:///C:/Users/YourName/Documents/Pi%20Output/filename.html`**

- If `htmlOutputFileUri` is set, construct the link by replacing `{filename}`
  with the actual filename, then present it as above.
- If `htmlOutputFileUri` is not set, present the raw filesystem path instead:

👉 **`/home/user/output/filename.html`**

This format is mandatory — every agent invoking this skill must use the
👉 emoji before the file link in its response. This applies universally
across all users, platforms, and sessions.

### Windows / WSL file:// URIs

On Windows with WSL, the resolved path (e.g. `/mnt/c/Users/...`) is correct for
file operations but won't work as a clickable link. To produce a working
`file://` URI in the agent's response, use one of these settings in
`~/.pi/agent/settings.json`:

#### Option A: `htmlOutputFileUri` (filename template)

```json
"htmlOutputFileUri": "file:///C:/Users/YourName/Documents/Pi%20Output/{filename}"
```

The placeholder `{filename}` is replaced with the actual output filename. When
this setting is present, the agent reports a clickable link instead of the raw
filesystem path.

#### Option B: `htmlOutputFileUriPrefix` (WSL path prefix)

```json
"htmlOutputFileUriPrefix": "file://wsl.localhost/Ubuntu-24.04"
```

When this setting is present, the agent presents the link as:

👉 **`{prefix}/home/.../full/filesystem/path/to/filename.html`**

Where `{prefix}` is the value of `htmlOutputFileUriPrefix`. The agent appends
the full filesystem path (from `/home` onwards) to the prefix to form the
clickable WSL link.

Prefer this option when the project files live directly on the WSL filesystem
and don't