# Agent Integrations

The htmlify repository ships two skills — `skills/htmlify` (documents) and `skills/deckify` (presentation decks) — plus three integration styles:

- Invokable skill: the user asks for `$htmlify` / `$deckify` or names the skill when they want a browser-ready artifact.
- Automatic hook: the agent's lifecycle hook detects a long final answer and writes an HTML export.
- CLI: pipe text through `htmlify-answer`, or validate any artifact with `htmlify-answer --validate`.

Prefer the invokable skills for production use. Hooks are useful when the user repeatedly wants long final answers archived as HTML, but hooks are agent-specific and should be installed deliberately.

> Each skill folder is self-contained (SKILL.md + references/). Install the folders, not the repo root — the repo root is the runtime, docs, and gallery.

## Claude Code (plugin — recommended)

```text
/plugin marketplace add zakelfassi/htmlify
/plugin install htmlify@htmlify
```

The plugin ships both skills. The optional Stop hook is NOT auto-enabled; to archive long answers automatically, add to `~/.claude/settings.json` (all projects), `.claude/settings.json` (committed project hook), or `.claude/settings.local.json` (project-local):

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node \"$HOME/path/to/htmlify/hooks/claude-code-stop-htmlify.js\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
```

The hook reads Claude Code's `Stop` event JSON from stdin, checks `last_assistant_message`, and writes an HTML artifact only when the answer length is at least `HTMLIFY_MIN_CHARS` characters. Defaults:

```bash
export HTMLIFY_MIN_CHARS=2500
export HTMLIFY_EXPORT_ROOT="$HOME/htmlify-exports"
```

### Claude Code (bare skills, no plugin)

```bash
git clone https://github.com/zakelfassi/htmlify.git ~/.htmlify
mkdir -p ~/.claude/skills
cp -R ~/.htmlify/skills/htmlify ~/.claude/skills/htmlify
cp -R ~/.htmlify/skills/deckify ~/.claude/skills/deckify
```

## Codex

```bash
git clone https://github.com/zakelfassi/htmlify.git ~/.htmlify
mkdir -p ~/.codex/skills
ln -sfn ~/.htmlify/skills/htmlify ~/.codex/skills/htmlify
ln -sfn ~/.htmlify/skills/deckify ~/.codex/skills/deckify
```

Invoke in a prompt:

```text
$htmlify turn this implementation summary into an operator brief
$deckify turn this design doc into a talk deck with speaker notes
```

Project-level opt-in via `AGENTS.md`:

```md
For long operator handoffs, build plans, PR/release packets, incident timelines,
or status reports, use `$htmlify` and write a self-contained HTML file instead
of returning a long markdown-only answer. For presentations, use `$deckify`.
```

Codex does not need a hook for the normal skill path. If you want automatic behavior, keep it as an instruction in `AGENTS.md` so the agent can choose HTML only when the answer actually benefits from it.

## Cursor, Windsurf, Aider, And Other Agents

Use the portable skill folders when the agent supports Agent Skills:

```bash
git clone https://github.com/zakelfassi/htmlify.git ~/.agent-skills/htmlify
```

Then point the agent at `skills/htmlify/SKILL.md` / `skills/deckify/SKILL.md` or add this project rule:

```md
When the user asks for a long report, review packet, implementation plan,
incident timeline, or decision brief, use the local htmlify skill at
~/.agent-skills/htmlify/skills/htmlify/SKILL.md and produce a self-contained
HTML artifact. For presentation decks, use skills/deckify/SKILL.md.
```

For agents without native skills, use the CLI as a local hook target:

```bash
printf '%s' "$LONG_ANSWER_TEXT" | npx -y @zakelfassi/htmlify htmlify-answer --title "Agent Answer"
```

From a checked-out repo:

```bash
printf '%s' "$LONG_ANSWER_TEXT" | node /path/to/htmlify/bin/htmlify-answer.js --title "Agent Answer"
```

## Pi / Oh-My-Pi

```bash
pi install npm:@zakelfassi/htmlify
```

The runtime registers `/htmlify`, `/html-last`, `/html-comments`, and `/htmlify-version`. See the repository README for command details and render modes.

## Validating artifacts from any agent

Every artifact — skill-authored or hand-written — can be checked against the safety/structure profiles:

```bash
npx -y @zakelfassi/htmlify htmlify-answer --validate artifact.html --profile auto
```

Profiles: `rich` (no scripts), `app` (inline scripts allowed; external scripts/handlers banned), `deck` (app plus the deckify slide contract), `auto` (detect per file). Exit codes: 0 valid, 1 errors, 2 usage/IO.

## Hook Safety

- Keep hooks local unless the whole team wants the behavior.
- Do not force every long answer into HTML; small terminal answers should stay in the terminal.
- Set `HTMLIFY_EXPORT_ROOT` to a predictable folder if artifacts should be archived.
- Use `HTMLIFY_MIN_CHARS` to tune threshold by team. Start with `2500`.
- Generated rich HTML is still validated before writing when it comes through the Pi/OMP runtime, and any artifact can be re-checked with `--validate`.