Birch HTML Agent Skill

> Use this skill when the user wants a polished, shareable, source-grounded, self-contained HTML artifact in the Birch visual system for engineering, product, planning, review, status, incident, process, codebase, data, or benchmark communication. Trigger for one-pagers, visual summaries, reports, dashboards, module/process explainers, implementation plans, design-direction comparisons, PR/change writeups, findings-first code reviews, incident/status reports, briefing decks, flow diagrams, numeric/data briefs, model/run/token/ time/cost reports, and design-system references. Do not use it for editing production web apps, React/Vue components, or ordinary chat answers.

50k tokens

context cost

the whole folder, loaded on every use

files

ships runnable scripts

copies elsewhere

how many repositories repackaged it

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/huggingface/research-agent --skill birch-html

What comes with it

189 554 bytes besides the instruction

assets/birch-system.css

recipes/benchmark-comparison.md

recipes/code-review.md

recipes/design-directions.md

recipes/design-system-reference.md

recipes/flow-diagram.md

recipes/implementation-plan.md

recipes/module-explainer.md

recipes/numeric-data.md

recipes/pr-change-writeup.md

recipes/process-explainer.md

recipes/slide-deck.md

recipes/status-incident-report.md

resources/template.html

scripts/birch-copy.js

scripts/birch_mpl.py

scripts/check_birch_renderings.py

scripts/finish_birch_html.py

styles/birch-system.css

The instruction itself

15 sections, as written by the author

Birch HTML

Create one complete, locally opening Birch HTML artifact. Optimize for complete

HTML, preserved Birch CSS placeholder, source-grounded claims, 390px mobile

safety, strict component contracts, and minimal page-local CSS.

Output contract

Return a full HTML document only: no prose, Markdown fences, or partial HTML.
If writing to disk, validate and return only the artifact path.
Keep the placeholder exactly until postprocessing:

<style data-birch-system>__BIRCH_SYSTEM_CSS__</style>.

Do not paste bundled Birch CSS or modify canonical CSS/scripts/resources.
No network assets: no remote URLs, CDNs, fonts, iframes, images, scripts, or styles.
Use <main class="page stack" data-gap="lg"> as the outer visible shell.
Do not replace the Birch shell with a custom app/dashboard shell. Do not make

body, .container, .report, or .dashboard the visible page shell.

Do not invent Birch classes/CSS variables or use Birchline-only classes. In

particular, avoid custom path/helper classes such as .file-path and avoid

variables such as --color-*, --size-*, --s-*, --bg-alt, or

--fg-muted unless they are already defined by Birch.

Use flat token surfaces only: no gradients, glassmorphism, glow backgrounds,

decorative background images, or custom dashboard skins.

Birch style forbids gradients for card, panel, page, and callout backgrounds

and for body/page backgrounds (for example linear-gradient,

radial-gradient, or conic-gradient). Use flat Birch token surfaces instead.

For diffs, never paste raw unified-diff text into <pre> or code blocks.

Represent patch lines with .diff-row; the only literal +/- marker should

be inside <span class="mark">.

Workflow

Read sources first: files, diffs, data, logs, commands, screenshots, session

notes, and local links before writing claims.

Make a terse brief: audience, purpose, exact paths/values, caveats, unknowns,

sections, and chart intent.

Ask only if missing audience, scope, sources, or output path would materially

change the result; otherwise proceed and label assumptions.

Load only needed recipes: numeric-data, code-review, pr-change-writeup,

implementation-plan, module-explainer, process-explainer,

design-directions, status-incident-report, flow-diagram, slide-deck,

benchmark-comparison, or design-system-reference.

If no path is specified and filesystem access exists, write a descriptive

kebab-case .html file in the current directory.

Prefer copying skill/resources/template.html; replace body content only.

Then run uv run skill/scripts/finish_birch_html.py <output.html>.

Validate before returning: doctype, html/head/body, viewport, title, .page,

Birch CSS placeholder/embedded CSS, closing </html>, no network assets, no

unknown classes/variables, strict children, wrapped long content, no 390px

overflow, and no raw patch marker lines. If available run:

uv run --with pillow python skill/scripts/check_birch_renderings.py --artifact <output.html>.

Required shell

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Clear artifact title</title>
  <style data-birch-system>__BIRCH_SYSTEM_CSS__</style>
  <style>/* Optional tiny wrapping/SVG fixes only. Prefer deleted. */</style>
</head>
<body>
  <main class="page stack" data-gap="lg">
    <header class="stack" data-gap="sm">
      <div class="eyebrow">Review artifact</div>
      <h1>Clear artifact title</h1>
      <p class="lede">One or two source-grounded sentences.</p>
    </header>
    <section class="section stack" data-gap="lg">...</section>
  </main>
</body>
</html>

Grounding

Put exact values, file paths, commands, caveats, and verification evidence near

the claim they support.

Use neutral uncertainty language: “observed”, “suggests”, “not verified”,

“source not present”.

Do not claim performance, risk, ownership, intent, or causality without source

support. Label assumptions.

Prefer captions citing paths/functions over broad narrative.

Birch primitives and local CSS

Build with primitives, not custom boxes: .section, .section-head, .stack,

.cluster, .card, .panel, .auto-grid, .section-rail,

.reference-panel, .chart-panel, .chart-svg, .chart-caption,

.stat-card, .stat-value, .metric-list, .metric-row,

.numeric-table-wrap, .numeric-table, .flow-list, .flow-step,

.code-block, .diff, .checklist, .plain-list, .insight-list,

.takeaway-list, .chip, .caption, .lede, .scroll-x.

Use semantic primitives in every artifact: sections plus cards, lists, tables,

flow steps, diff rows, metric lists, or chart panels as relevant.

Page-local CSS: ideally none; hard target under 30 lines / 1.5 KB. Use it only

for page-specific SVG sizing, chart sizing, tiny gaps, or wrapping. Do not

recreate shells/cards/grids/rails/tables/typography/badges/meters, redefine

Birch primitives, or use linear-gradient, radial-gradient, or

conic-gradient. Put local CSS after the Birch placeholder/link. Use only

Birch variables (--bg, --surface, --text, --border-color, --accent,

--success, --danger, --info, --space-1…--space-8, and documented

color tokens).

Mobile safety

Design for 390px. Rows, chips, stat values, code, tables, and SVGs must wrap or

scroll inside their own container without page-level horizontal overflow.

If prose/list text wraps to one or two words per line in a wide card, remove

custom grid/flex and stack it.

Long paths, commands, hashes, identifiers, URLs, diff lines, numeric notes, and

symbols must wrap or live inside .scroll-x.

Use data-wrap="true" on every long .code-block and .diff.
Do not use long paths/identifiers as headings; put them in captions, prose,

<code>, wrapped blocks, or short chips.

Keep chips and <h1> short; move long nouns to lede/captions.
Numeric tables always use

<div class="numeric-table-wrap"><table class="numeric-table">...</table></div>.

Keep numeric tables to 3–5 columns. Split wide data into smaller tables plus

KPI cards. Avoid all-in-one tables with long prose cells.

If table cells contain paths, notes, code, commands, or long labels, add:

.numeric-table code, .numeric-table .note { white-space: normal; overflow-wrap: anywhere; word-break: break-word; }

Never put long paths, excerpts, or prose-heavy evidence in narrow table

columns unless the table is wrapped and those cells can break anywhere; prefer

stacked cards, lists, or .code-block data-wrap="true" for code-review

evidence.

Use .scroll-x only for truly wide comparisons; otherwise reduce columns.
In side rails, avoid long .metric-row values; prefer KPI cards, lists, or

compact metric CSS vars.

Layout rules

Prefer .section-rail: main content first, then <aside class="reference-panel">.
Avoid .split for plans, source-vs-assumption blocks, or columns with headings

on both sides; use .section-rail or stacked cards.

KPI strips use .auto-grid with style="--grid-min: 160px".
Keep side rails short: caveats, sources, compact KPIs only.
Numeric/data artifacts must show evidence in the first desktop viewport:

compact hero, KPI strip, and chart/ranking/table start.

Numeric/data and benchmark pages need KPI cards or valid metric rows, a chart

or ranking, a numeric table, and source/caveat captions.

Strict components

Diff rows

Never put raw patch text directly in HTML source or code blocks. No generated

source line may begin with +, -, or @@ to represent a patch. Use

.diff-row with exactly three direct children: .ln, .mark, .code; mark

text is +, -, or one space; added rows use .add/data-kind="add",

deleted rows use .del/data-kind="del".

<div class="diff" data-wrap="true">
  <div class="diff-row add"><span class="ln">12</span><span class="mark">+</span><span class="code">added code</span></div>
</div>

Flow steps

Every .flow-step has exactly two direct children: .flow-num, then one

content wrapper. Put titles, paragraphs, lists, and code inside the wrapper.

<li class="flow-step"><span class="flow-num">1</span><div class="stack" data-gap="sm"><h3 class="flow-title">Read inputs</h3><p class="flow-detail">Detail.</p></div></li>

Metric rows

Use .metric-row only for label + meter + short value; not for metadata,

timelines, work items, prose, or key/value rows. It has exactly three direct

children: .caption, .meter, code. Do not add extra children or .metric

inside .metric-row. Long labels/values belong in cards, lists, or tables.

<div class="metric-row"><span class="caption">Pass rate</span><div class="meter"><span style="--value: 98%"></span></div><code>0.98</code></div>

Lists and tables

.checklist: pass/done/validated items only; .plain-list: neutral bullets;

.insight-list/.takeaway-list: key observations.

In insight/takeaway lists, each <li> has exactly one direct wrapper child.
Numeric <th> and <td> cells need class="metric" so headers and values align.
Use short table headers; explain long meanings in captions.

SVG, charts, and reports

Put inline SVG inside .panel.chart-panel.stack; usually wrap the SVG with

.chart-svg and add .chart-caption.

Keep SVG text short, away from right edges; leave viewBox margin or move labels

to captions/lists.

Tiny hand-written SVG: 5–8 nodes max. Every data path/polyline sets

fill="none", a Birch-colored stroke, and restrained stroke-width.

If SVG labels risk 390px overflow, stack vertically or use numbered nodes plus

a following .flow-list.

For real plotted data, prefer Python-generated inline SVG using

scripts/birch_mpl.py; run a temporary driver as needed, inline SVG in a

chart panel, and pair with exact values in narrow .numeric-tables.

Artifact patterns

Module/runtime explainers: short transformation title, caveat paragraph, SVG

flow of 5–8 nodes, caption citing source files/functions, then ordered

.flow-list file tour or runtime walkthrough. Prefer flow steps, cards, and

captions over dense tables.

Numeric/benchmark reports: inspect schema and rows; use KPI cards for headline

counts/totals/best/worst/pass/fail/cost/time; use valid .metric-list only for

true progress/ranking values; include charts when they clarify tradeoffs; pair

charts with exact values and source/caveat captions.

How to use it

Copy the folder

Take huggingface/birch-html from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.