html-artifact-report-skill

# HTML Report Skill for AI Agents

> Portable agent skill for creating warm editorial HTML artifacts for humans plus JSON manifests for agents.

This repository defines one strict dual-output contract:

- `artifact.html`: human-facing standalone report.
- `artifact.json`: agent-facing manifest with sections, components, claims, evidence, source hashes, verification, and limitations.

Use this skill when an agent is about to produce a substantial report, review, research summary, implementation plan, decision brief, audit artifact, Markdown-to-HTML report, or JSON-backed report manifest.

## Start Here

- [README](README.md): positioning, install, examples, public contract.
- [Agent installation guide](docs/agents.md): Claude Code, Codex, Cursor, Gemini CLI, DeepSeek-backed agents, and generic agents.
- [SKILL](SKILL.md): runtime instructions for coding agents.
- [SPEC](SPEC.md): complete artifact contract.
- [AGENTS](AGENTS.md): repository instructions for agents editing this repo.

## Install

- [Agent install](docs/agents.md#recommended-npx-skills): choose one client, for example `--agent claude-code` or `--agent codex`.
- [Claude Code](docs/agents.md#claude-code): install and first prompt.
- [Codex](docs/agents.md#codex): install and first prompt.
- [Cursor](docs/agents.md#cursor): install and fallback prompt.
- [Gemini CLI](docs/agents.md#gemini-cli): install and one-off prompt.
- [DeepSeek-backed agents](docs/agents.md#deepseek-backed-agents): use the host client; DeepSeek is the model provider.

## Contract Files

- [JSON schema](contract/artifact-report.schema.json): validates `artifact.json`.
- [Example manifest](contract/artifact-report.example.json): minimal valid manifest shape.
- [Desktop HTML template](templates/desktop-report-template.html): canonical warm editorial baseline.
- [Component catalog](components/report-components.md): allowed components.
- [Anti-slop rules](references/anti-slop.md): visual anti-patterns.
- [Style principles](references/style-principles.md): report profile rules.

## Examples

- [Executive decision brief](examples/executive-decision-brief/): compact decision memo.
- [Data-heavy report](examples/data-heavy-report/): folded evidence and tables.
- [Technical design review](examples/technical-design-review/): ID alignment example.
- [CJK report](examples/cjk-report/): Chinese report with stable machine IDs.

## Checkers

- [HTML checker](scripts/check_html_artifact.py): validates report structure and anti-slop rules.
- [JSON checker](scripts/check_artifact_json.py): validates schema, source hashes, and HTML/JSON alignment.
- [Example checker](scripts/check_examples.py): runs positive and negative fixtures.

## Multilingual Quickstarts

- [Chinese](README.zh-CN.md)
- [Spanish](docs/i18n/es.md)
- [Japanese](docs/i18n/ja.md)
- [French](docs/i18n/fr.md)