How to use the HTML Size Audit agent skill (html-size)

What the html-size skill makes the agent do

Googlebot has a documented parse limit of approximately 15MB per HTML document. The skill's guidance is that content beyond that point is not parsed or indexed, and that even smaller oversized HTML can slow crawling and use up crawl budget.

With the skill loaded, the agent checks the raw HTML size of a page, flags pages over 2MB for investigation and pages over 5MB as critical, and works through likely causes. Those causes are large inline JSON data blocks, inline SVG, base64-encoded images, inline CSS with large amounts of utility classes, and unminified scripts.

• Flags pages over 2MB (investigate) and over 5MB (critical)
• Identifies the likely cause of oversized HTML
• Suggests fixes such as moving data out of the page, enabling compression and minifying output

How do you install the html-size skill?

Download the ZIP for the skill from the page where you found this guide. Then unzip it into one of two places, depending on how you want to use it.

For a personal setup, put the skill folder in ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Single project: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the skill

How do you trigger the skill with natural requests?

You do not need a special command. The skill's description tells the agent when to use it, so ordinary requests about page weight or indexing should be enough. Name the page or paste its URL so the agent has something to measure.

Requests that fit the skill's stated use cases include auditing page weight for crawl efficiency, investigating why certain content is missing from Google's index, and reviewing a server-rendered page that embeds a large JSON payload.

• "Audit the page weight of https://example.com/products/shoes and tell me if it is near the Googlebot limit."
• "Some of our product descriptions are missing from Google's index. Check whether HTML size could be the cause."
• "This Next.js page embeds a lot of data in __NEXT_DATA__. Review it and suggest how to shrink it."

How does the size check work?

The skill's measurement step uses curl to download the page and awk to format the byte count. It measures the raw HTML response. The command in the skill is shown below. Replace the URL with your own page.

The skill also asks the agent to check for large script blocks such as application/json or __NEXT_DATA__ scripts, and to look for <svg> elements in the body. The skill notes that a single JSON block over 500KB is worth flagging.

How do you fix the causes the audit finds?

The fixes depend on the cause. For large inline JSON, pass only the data the page actually renders, and load more through client-side calls. For inline SVG, move the files out of the HTML and load them with img or use. For base64 images, serve them from a CDN and reference them by URL.

Two fixes apply to almost any site: turn on gzip or Brotli compression on the server, since Googlebot fetches the compressed response, and minify HTML in production by removing whitespace and comments.

• Reduce data passed to getServerSideProps or getStaticProps to what the page renders
• Move inline SVG to external files
• Serve base64 images from a CDN
• Enable gzip or Brotli compression
• Minify HTML output in production

What does the skill need, and what should you know about safety?

The skill needs curl and awk available in the shell for the measurement command, and access to the page URL or its HTML source. According to the skill's listing, it does not run scripts, but it does use the network, because the measurement command downloads the page.

The skill only reasons about the HTML and the commands it suggests. It does not query Google, and it is not a live Google Search Console check.

• Requires: curl and awk in the shell, and access to the page URL or HTML source
• Runs scripts: no
• Uses network: yes, to download the page for measurement
• Licence: MIT

When should you not use the html-size skill?

The skill is not useful for small static sites or blogs, where HTML is far below the thresholds and the advice adds little value. It also does not cover missing content caused by JavaScript rendering, robots rules, or noindex tags. If those are the cause, the skill will not find them.

• Small static sites or blogs with HTML far below the thresholds
• Missing content caused by JavaScript rendering, robots rules or noindex tags
• Anyone expecting a direct query to Google