skills/development-workflows/html-artifact/SKILL.md
Create self-contained HTML artifacts, single-file by default and split into offline per-page bundles when oversized, for complex, visual, comparison-heavy, reviewable, or shareable work outputs. Use this skill when the user asks for an HTML artifact, browser-viewable report, implementation plan, PR/code review report, architecture explainer, design comparison, research briefing, incident report, status dashboard, temporary structured-data editor, mini deck, or design-system specimen. Prefer this skill for long Markdown-like outputs that benefit from navigation, cards, diagrams, filters, copy/export buttons, or annotated diffs. Do not use it for short answers, simple commands, commit messages, tiny patch summaries, or production UI implementation unless the user explicitly asks for a review artifact.
npx skillsauth add bahayonghang/my-claude-code-settings html-artifactInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
Create a browser-viewable HTML artifact when complex work needs a richer review surface than a wall of Markdown. Default to one self-contained file; use a split bundle when the planned content is too large for a reviewable single page.
Use HTML artifacts for complex, visual, comparison-heavy, reviewable, or shareable outputs. Keep ordinary Markdown for short answers, simple commands, commit messages, tiny summaries, and routine implementation reports unless the user explicitly asks for an artifact.
Every artifact must be:
.html or .htm file unless the pre-build size gate says to split. When split, create docs/artifacts/<slug>/index.html plus self-contained part pages such as part-01-overview.html.fetch, XHR, beacons, WebSockets, or automatic network requests.<!doctype html>, <html>, <head>, <meta charset="utf-8">, <meta name="viewport">, <title>, <main id="main">, and one clear <h1>.prefers-reduced-motion support.When the artifact is report-like, decision-making, comparison-heavy, deck-like, likely to be screenshotted/shared, or intended for senior review, make the design pass explicit before writing HTML. Use the $frontend-design method as an upstream thinking step, then translate it into offline artifact constraints.
Make these four decisions:
editorial, dashboard, dossier, deck, or workbench.spacious presentation, medium-density report, or high-density cockpit.table-first, card-first, inline-SVG-first, HTML-lane-first, swimlane-first, or chart-first. Pick chart-first when the artifact's core argument is trend, distribution, or proportion; pick swimlane-first when responsibility / handoff between roles is the key story.Translate frontend-design principles into this skill's hard constraints:
auto-fit grids when the item count is known. Explicitly compose 5 cards as 3+2 and 7 cards as 4+3 at desktop widths.repeat(auto-fit, ...) and producing orphan rows such as 4+1.Load references/template-selection.md when choosing a template. Use the first matching primary goal, then combine secondary sections if needed.
When the user asks to deeply analyze a codebase architecture, call mechanism, enum/selection strategy, module boundaries, redundancy, trainer/worker dispatch, or model-trainer organization, default to an Architecture Atlas + Review Workbench + Strategy Blueprint report rather than a generic polished page. Treat this as an evidence-driven architecture audit artifact, not production UI and not a code-editing skill.
Use this fixed report contract unless the user gives a narrower structure:
Enum recommendations must include a table with these columns: current entrypoint, recommended enum type, recommended member names, naming basis, caller impact, and documentation update point. Keep long code identifiers in HTML tables/lists; use short SVG labels only.
| User goal | Start with | | -------------------------------------------------------- | ------------------------ | | Implementation plan, PRD, roadmap, migration plan | Strategy Blueprint | | Code review, PR explainer, diff audit | Review Workbench | | Architecture, data flow, interface boundary | Architecture Atlas | | Option comparison, buy/build, design choice | Decision Matrix Studio | | Research report, learning brief, source-backed synthesis | Evidence Dossier | | Weekly/project status, release readiness, QA report | Status Brief | | Incident report, RCA, postmortem | Incident Timeline | | JSON/YAML/prompt/config editing or local triage tool | Interactive Editor | | Meeting readout, mini deck, slide-like walkthrough | Narrative Deck | | Design tokens, component states, visual audit | Component Specimen Sheet |
references/templates/ plus references/accessibility-and-security.md when relevant. Load references/diagram-cookbook.md for roadmaps, flows, dependency lanes, or architecture diagrams. Load references/size-and-splitting.md when the size gate is near or above the split threshold.docs/artifacts/<slug>.html for single-page artifacts. For split bundles, prefer docs/artifacts/<slug>/index.html plus part-NN-topic.html pages.assets/starter-template.html as the copyable baseline, not as a remote dependency.python skills/development-workflows/html-artifact/scripts/check_html_artifact.py <artifact.html>
references/design-review-checklist.md.Before writing HTML, make a short size plan. Do not wait for the validator's post-build large-file warning to discover that the artifact should have been split.
estimated_total_bytes using the method in references/size-and-splitting.md.<900 KB: single page by default.900 KB–1.2 MB: single page is allowed, but compress content first by summarizing repeated rows, moving raw evidence into collapsible summaries, and shortening excerpts.1.2 MB–1.5 MB: prefer a split bundle unless the artifact has one tightly coupled reading flow.>1.5 MB: split bundle is required unless the user explicitly asks for one file.Size plan: estimated_total_bytes=1.34 MB from 9 sections, 4 tables (~180 rows), 3 SVG diagrams, and 40 short evidence excerpts. Decision: split bundle with index + 3 parts.
For split bundles, keep each page offline self-contained. Do not create a site that depends on shared CSS, shared JS, JSON files, images, or fetch.
The starter template includes reusable primitives. Prefer these over ad-hoc CSS for common artifact problems:
hero--compact.hero--split for left conclusion plus right thesis board/meta cluster; hero--compact when no right-side material exists; hero--deck for executive readouts.grid-2, grid-3, grid-4, grid-5-balanced (3+2 desktop), and grid-7-balanced (4+3 desktop). All grid children should tolerate long mixed-language text.table--matrix, table--evidence, and table--decision; use is-recommended, key-row, verdict-column, or evidence-column to make conclusions scannable.figure.diagram-frame with inline SVG, timeline/phase lanes, or structured HTML diagrams; always include figcaption and a text equivalent list or table.architecture-map, boundary-band, evidence-rail, edge-legend, and risk-heat for codebase audit pages that need C4-lite boundaries, traceable evidence, call edges, and risk density.Mermaid can be an input sketch, but static SVG or clear HTML must be the final artifact output.
Preferred order:
Do not leave raw Mermaid syntax as the main visual expression. Even when the user provides Mermaid, convert the idea into static SVG or a readable HTML diagram with text equivalents.
Inline SVG labels must stay crisp and short:
<text> only for short node/edge labels. Put long code identifiers, file paths, mixed Chinese/English explanations, and nuanced prose in the adjacent ordered list, table, or card text equivalent.stroke, stroke-width, paint-order: stroke, text-shadow, filter, or drop-shadow; these commonly blur screenshots and exported images..svg-label or .diagram-frame text with fill-only text, moderate font size, and moderate weight. Emphasize the surrounding node shape, border, fill, or nearby HTML annotation instead of outlining the letters.<tspan> and keep each line scannable. If it needs more than two short lines, use an HTML lane/card instead of SVG text.For generated artifacts, run python skills/development-workflows/html-artifact/scripts/check_html_artifact.py <artifact.html>.
For changes to this skill, run node --test skills/development-workflows/html-artifact/tests/check-html-artifact.test.mjs, then project gates.
Keep this entrypoint small. Load detailed references only as needed:
references/template-selection.md — template selection and combination rules.references/size-and-splitting.md — pre-build byte estimation, split thresholds, naming, navigation, and compression strategies.references/accessibility-and-security.md — offline, accessibility, privacy, and validation rules, including the color / mode / theme layering.references/design-review-checklist.md — manual visual QA covering the six dimensions (composition, tables, diagrams/SVG, charts, interactive controls, modes/offline).references/tables-cookbook.md — eight table recipes plus responsive strategy and non-decorative emphasis. Load when an artifact has decision matrices, evidence tables, risks, trends, heatmaps, or summaries.references/charts-cookbook.md — eight inline-SVG/CSS-only chart recipes plus a decision tree. Load when a metric, distribution, or trend needs visualization beyond a number with a status pill.references/svg-cookbook.md — icons, decorative motifs, and spot illustrations using currentColor and tokens.references/diagram-cookbook.md — inline SVG and HTML diagram recipes (phase roadmap, decision flow, swimlane, state machine, tree, before/after, gantt, dependency, evidence-to-claim) and shape/connector conventions.references/interaction-cookbook.md — ten native-first interaction recipes (filter chip, search, sortable table, tabs, disclosure, dialog, scroll-spy, theme toggle, copy with feedback, keyboard shortcuts) with progressive-enhancement baselines.references/templates/strategy-blueprint.md — implementation plans and PRDs.references/templates/review-workbench.md — code review and PR reports.references/templates/architecture-atlas.md — architecture and data-flow explainers.references/templates/decision-matrix-studio.md — option comparison and ADR-style decisions.references/templates/evidence-dossier.md — research and source-backed reports.references/templates/status-brief.md — project/release/QA status dashboards.references/templates/incident-timeline.md — incident reviews and postmortems.references/templates/interactive-editor.md — local structured-data editors.references/templates/narrative-deck.md — browser mini decks.references/templates/component-specimen-sheet.md — design-system and component review sheets.tools
文献深度解读助手,像研究生导师一样交互式解读 Zotero 库中的学术论文,面向计算机科学、深度学习、自动化等方向(个人向)。当用户提供文献题目、DOI、PDF 或要求解读某篇论文时触发,通过 Zotero MCP 优先获取全文,并根据用户意图自动选择快速筛选、导师深读或研究复盘模式。完整深读时先完成叙事类型判断、阅读前预检、novelty 校准和作者思考路径重建,再整体概览,并基于图例、正文和表格逐图详细解读(Zotero MCP 无法提取 PDF 图片,解读基于文字信息,必要时提醒上传图片)。适用于:(1)快速判断文献是否值得深读 (2)深入理解某篇论文 (3)学习文章中的方法和技术 (4)批判性分析研究设计 (5)寻找研究灵感。需要多篇论文综合、对比或找研究空白,或 arXiv/DOI 批量规范化时,改用 paper-workbench。
development
Review Codex, Claude, OpenAI, or other agent skill directories as reusable capability packages. Use when asked to audit, review, improve, score, rewrite, debrand, package, or document a SKILL.md, skill package, marketplace skill, or agent skill directory, especially when the user wants a comprehensive findings-first report with concrete patch recommendations and validation steps.
development
Turn vague or complex Codex tasks into strong `/goal` commands with outcome, verification, constraints, boundaries, iteration policy, completion evidence, and pause/block conditions. Use when the user asks for Codex goal instructions, Goal 指令, 目标指令, `/goal` prompts, 中文 Goal 模板, plan-to-goal interviews, success criteria, verification commands, or bounded agent work definitions.
tools
Write, debug, and validate ast-grep structural code search rules. Use this skill when the user needs syntax-aware code search, AST pattern matching, structural refactor discovery, language-construct queries, or searches that plain text tools like rg can miss, such as finding functions with particular descendants, calls inside specific contexts, missing error handling, React hook shapes, decorators, or other Tree-sitter-backed code structures.