html-first-workflow

A Claude Code / Codex skill that switches the assistant from "default markdown" to single-file interactive HTML artifacts when you ask for a deliverable document — specs, PRDs, architecture designs, code review reports, weekly/monthly reports, competitive analysis, technical option comparisons, SOPs, meeting notes, prototypes.

Markdown stays the default for chat replies, code comments, API docs, and throwaway notes.

Demo

A real example generated by asking "画一个投标管理系统的业务流程图" — the assistant produced a single-file HTML artifact with Mermaid flowchart + sequence diagram + state machine, plus card grid, table, dark mode, and print-ready CSS.

Light	Dark

Open the file directly in any browser — no build, no server.

What you get

Each generated document is a single .html file with:

• Tailwind CSS via CDN (no build step)
• Dark mode toggle (darkMode: 'class')
• Print-optimized CSS (export to PDF cleanly)
• Mobile responsive
• Semantic HTML (<nav> / <main> / <section> / <footer>)
• Optional Mermaid diagrams, Alpine.js interactions, Chart.js

Drop it in a folder, double-click — works offline (except CDN scripts). Easy to share, archive, version.

Install

One-liner (recommended)

curl -fsSL https://raw.githubusercontent.com/ericforai/html-first-workflow/main/install.sh | bash

Installs to ~/.claude/skills/html-first-workflow/ (or $CLAUDE_CONFIG_DIR/skills/ if set).

Manual

git clone https://github.com/ericforai/html-first-workflow.git \
  ~/.claude/skills/html-first-workflow

For Codex, override the target:

SKILLS_INSTALL_DIR=~/.codex/skills bash install.sh

For project-local (only this repo):

SKILLS_INSTALL_DIR=./.claude/skills bash install.sh

Restart Claude Code after install.

Verify it works

Ask any of:

• "帮我出一份用户认证模块的 PRD"
• "/spec 支付流程"
• "做一个本周开发周报"
• "对比一下 Redis 和 Memcached"
• "画一下投标管理系统的业务流程图"

Expected: an HTML file under docs/artifacts/, not a markdown reply.

Counter-example (skill should NOT trigger):

• "解释一下这段代码" → still markdown ✓
• "帮我写个 README" → still markdown ✓

File structure

html-first-workflow/
├── SKILL.md              # Main entry — always loaded
├── examples.md           # 10 document type skeletons
├── mermaid-guide.md      # Diagram patterns (flowchart / sequence / state / ER / gantt / ...)
└── reference/            # Component library — loaded by section
    ├── _index.md         # Routing index
    ├── layout.md         # Page shell, nav, sidebar, hero, footer
    ├── feedback.md       # Info/warning/error/success boxes, toast, progress
    ├── cards.md          # Basic/icon/feature/stat cards
    ├── interactive.md    # Tabs, accordion, collapsible, toggle
    ├── data.md           # Tables, MoSCoW matrix, checklist, timeline
    ├── code.md           # Code block, diff, inline code
    ├── forms.md          # Inputs, selects
    ├── status.md         # Status & severity badges
    └── deps.md           # CDN imports

When it triggers

The skill's description field tells Claude when to load it. Triggers include:

• Symptoms: "出一份方案/文档", "正式一点", "给老板看", "存档", "对比方案", "周报/月报"
• Document types: spec, PRD, architecture, code review, weekly report, comparison, SOP, meeting notes, prototype
• NOT for: chat replies, code comments, API docs, single-paragraph answers

Customize

• Swap primary color in the Tailwind config in reference/layout.md
• Change save folder convention in SKILL.md → "Document Folders"
• Add your own document type by appending to examples.md

Uninstall

rm -rf ~/.claude/skills/html-first-workflow

License

MIT