image-auditor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Image Auditor Skill

图片审计Skill

Operator Context

操作者上下文

This skill operates as an operator for image validation and optimization, configuring Claude's behavior for comprehensive image auditing. It implements a Discovery-Validation architectural pattern — scan references, validate existence, assess quality, report findings — with Domain Intelligence embedded in web performance and accessibility standards.

本Skill作为图片验证与优化的操作组件，用于配置Claude的行为以实现全面的图片审计。它采用发现-验证架构模式——扫描引用、验证存在性、评估质量、报告结果——并内置了基于Web性能和可访问性标准的领域智能。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before auditing
Non-Destructive: NEVER modify, resize, convert, or delete images without explicit user request
Complete Output: Show all validation results with absolute file paths and line numbers
Reproduce First: Verify every reported issue by reading the actual file/reference
Evidence Required: Every FAIL or WARN must cite the file path, line number, and concrete evidence

CLAUDE.md合规性：审计前需阅读并遵循仓库中的CLAUDE.md文件
非破坏性：未获得用户明确请求时，绝不能修改、调整大小、转换或删除图片
完整输出：显示所有验证结果，并附带绝对文件路径和行号
先复现：通过读取实际文件/引用来验证每个报告的问题
需附证据：每个FAIL（失败）或WARN（警告）都必须标注文件路径、行号和具体证据

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

Full Audit: Run all check categories (alt text, existence, size, format, unused)
Unused Image Detection: Find images in static/ not referenced by any content
Size Thresholds: Flag images >500KB for web optimization
Format Suggestions: Recommend WebP conversion where beneficial
Page Weight Calculation: Sum image sizes per post and flag heavy pages

全面审计：运行所有检查类别（alt文本、存在性、大小、格式、未使用图片）
未使用图片检测：查找static/目录中未被任何内容引用的图片
大小阈值：标记大于500KB的图片以进行Web优化
格式建议：在合适的场景下推荐转换为WebP格式
页面权重计算：统计每篇文章的图片总大小，并标记过重的页面

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，需开启）

Deep Scan: Include theme images and assets/ directory
Auto-Optimize: Generate optimized versions (requires imagemagick, explicit consent only)
Strict Mode: Treat all suggestions as blockers

深度扫描：包含主题图片和assets/目录
自动优化：生成优化后的版本（需要imagemagick，仅在获得明确同意时使用）
严格模式：将所有建议视为阻塞项

What This Skill CAN Do

本Skill可执行的操作

Scan all content files for image references (Markdown, Hugo shortcodes, HTML)
Verify all referenced images exist at resolved paths
Analyze alt text quality (missing, generic, descriptive)
Measure file sizes and flag oversized images against thresholds
Detect format mismatches (photo as PNG, screenshot as JPEG)
Find unused images not referenced by any content
Calculate total page weight per post
Generate optimization recommendations with estimated savings
Report line numbers and absolute paths for all issues

扫描所有内容文件以查找图片引用（Markdown、Hugo短代码、HTML）
验证所有引用的图片是否存在于解析后的路径中
分析alt文本质量（缺失、通用化、描述性）
测量文件大小，并根据阈值标记过大的图片
检测格式不匹配问题（如照片使用PNG格式、截图使用JPEG格式）
查找未被任何内容引用的未使用图片
统计每篇文章的总页面权重
生成带有预估节省空间的优化建议
报告所有问题的行号和绝对路径

What This Skill CANNOT Do

本Skill不可执行的操作

Modify, resize, or convert images (destructive operations require explicit consent)
Access external image URLs (CDN-hosted, remote images)
Judge alt text semantic accuracy (only structural and heuristic checks)
Delete unused images without user confirmation
Skip any of the 4 phases

修改、调整大小或转换图片（破坏性操作需要明确同意）
访问外部图片URL（CDN托管、远程图片）
判断alt文本的语义准确性（仅进行结构性和启发式检查）
未获得用户确认时删除未使用图片
跳过四个阶段中的任何一个

Instructions

使用说明

Usage

使用方式

/image-audit                    # Audit entire site
/image-audit content/posts/     # Audit specific directory
/image-audit --post my-post.md  # Audit single post

/image-audit                    # Audit entire site
/image-audit content/posts/     # Audit specific directory
/image-audit --post my-post.md  # Audit single post

Phase 1: DISCOVER

阶段1：发现

Goal: Build a complete map of all images and all image references in the codebase.

Step 1: Find all image files

Use Glob to locate image files:

Pattern:
```
static/**/*.{png,jpg,jpeg,gif,webp,svg}
```
Record each file's absolute path and size (use
```
ls -la
```
or
```
stat
```
)

Step 2: Find all image references in content

Use Grep to search content files for these patterns:

Markdown images:
```
![alt](path)
```
-- regex:
```
!\[.*?\]$.*?$
```
Hugo figure shortcode:
```
{{< figure src="..." >}}
```
-- regex:
```
figure.*src=
```
HTML img tags:
```
<img src="..." alt="...">
```
-- regex:
```
<img.*src=
```
Raw path references:
```
.png)
```
,
```
.jpg)
```
,
```
.webp)
```
,
```
.svg)
```

Step 3: Build reference map

For each image reference, record:

Source file path (absolute)
Line number
Image path (as written in source)
Resolved path (in static/)
Alt text (if present)

Path Resolution Rules:

```
/images/foo.png
```
resolves to
```
static/images/foo.png
```
```
images/foo.png
```
resolves to
```
static/images/foo.png
```
```
../images/foo.png
```
resolves relative to the content file's location
Hugo shortcode
```
src=
```
values follow the same resolution rules

Gate: Reference map is complete with all images and all references catalogued. Proceed only when gate passes.

目标：构建代码库中所有图片及图片引用的完整映射。

步骤1：查找所有图片文件

使用Glob查找图片文件：

匹配模式:
```
static/**/*.{png,jpg,jpeg,gif,webp,svg}
```
记录每个文件的绝对路径和大小（使用
```
ls -la
```
或
```
stat
```
命令）

步骤2：查找内容中的所有图片引用

使用Grep在内容文件中搜索以下模式：

Markdown图片:
```
![alt](path)
```
-- 正则表达式:
```
!\[.*?\]$.*?$
```
Hugo figure短代码:
```
{{< figure src="..." >}}
```
-- 正则表达式:
```
figure.*src=
```
HTML img标签:
```
<img src="..." alt="...">
```
-- 正则表达式:
```
<img.*src=
```
原始路径引用:
```
.png)
```
,
```
.jpg)
```
,
```
.webp)
```
,
```
.svg)
```

步骤3：构建引用映射

对于每个图片引用，记录：

�源文件路径（绝对路径）
行号
图片路径（与源文件中一致）
解析后的路径（位于static/中）
Alt文本（如果存在）

路径解析规则:

```
/images/foo.png
```
解析为
```
static/images/foo.png
```
```
images/foo.png
```
解析为
```
static/images/foo.png
```
```
../images/foo.png
```
相对于内容文件的位置进行解析
Hugo短代码中的
```
src=
```
值遵循相同的解析规则

检查点：引用映射需包含所有图片及引用的完整记录。仅当检查点通过后才可进入下一阶段。

Phase 2: VALIDATE

阶段2：验证

Goal: Check every reference and every image against quality criteria.

Step 1: Alt text validation

Status	Condition
PASS	Alt text present, descriptive, 10-125 characters
WARN	Alt text too generic (single words: "image", "screenshot", "picture", "photo", "diagram", "figure", "img")
FAIL	Alt text missing or empty

See

references/alt-text-examples.md

for detailed quality guidelines.

Step 2: File existence validation

Status	Condition
PASS	Image file exists at resolved path
FAIL	Image file not found at resolved path

Step 3: File size validation

Status	Threshold
PASS	<200KB
WARN	200KB-500KB
FAIL	>500KB

See

references/size-guidelines.md

for type-specific thresholds.

Step 4: Format appropriateness

Image Type	Preferred Format	Detection Heuristic
Photos	WebP, JPEG	Filename: "photo", "hero", "banner"
Screenshots	WebP, PNG	Filename: "screenshot", "screen-", "capture"
Diagrams	SVG, WebP	Filename: "diagram", "chart", "graph", "flow"
Icons/Logos	SVG	Filename: "icon", "logo", "favicon"

See

references/format-selection.md

for the complete decision flowchart.

Step 5: Unused image detection

Compare all files in static/images/ against the reference map. Any file with zero references is reported as unused.

Gate: All references validated against all criteria. Every issue has a severity level, file path, and line number. Proceed only when gate passes.

目标：根据质量标准检查所有引用和图片。

步骤1：Alt文本验证

状态	条件
PASS	存在Alt文本，描述性强，长度在10-125字符之间
WARN	Alt文本过于通用（单字："image"、"screenshot"、"picture"、"photo"、"diagram"、"figure"、"img"）
FAIL	Alt文本缺失或为空

详细的质量指南请参考

references/alt-text-examples.md

。

步骤2：文件存在性验证

状态	条件
PASS	图片文件存在于解析后的路径中
FAIL	图片文件未在解析后的路径中找到

步骤3：文件大小验证

状态	阈值
PASS	<200KB
WARN	200KB-500KB
FAIL	>500KB

针对不同类型的阈值要求请参考

references/size-guidelines.md

。

步骤4：格式适用性

图片类型	推荐格式	检测启发式规则
照片	WebP、JPEG	文件名包含："photo"、"hero"、"banner"
截图	WebP、PNG	文件名包含："screenshot"、"screen-"、"capture"
图表	SVG、WebP	文件名包含："diagram"、"chart"、"graph"、"flow"
图标/Logo	SVG	文件名包含："icon"、"logo"、"favicon"

完整的决策流程图请参考

references/format-selection.md

。

步骤5：未使用图片检测

将static/images/中的所有文件与引用映射进行对比。任何没有引用的文件都将被标记为未使用。

检查点：所有引用均已根据所有标准完成验证。每个问题都已标记严重级别、文件路径和行号。仅当检查点通过后才可进入下一阶段。

Phase 3: ANALYZE

阶段3：分析

Goal: Compute aggregate metrics and optimization potential.

Step 1: Page weight per post

For each post containing images, sum total image bytes and count images.

Status	Total Images
Good	<1 MB
Warn	1-3 MB
Critical	>3 MB

Step 2: Optimization estimates

Calculate potential savings for each actionable item:

WebP conversion: ~30% for photos, ~25% for screenshots
Resize to max 1200px width: varies by original dimensions
Compression optimization: ~10-20% additional savings
Total estimated savings across all recommendations

Present estimates as concrete byte counts (e.g., "save ~340 KB"), never as vague percentages alone.

Step 3: Identify highest-impact fixes

Rank issues by potential impact:

Broken references (FAIL) -- content is visibly broken
Missing alt text (FAIL) -- accessibility violation
Oversized images on heavy pages -- worst page weight first
Format mismatches with largest savings potential

Gate: Metrics computed for all posts. Optimization estimates are concrete numbers. Priority ranking established. Proceed only when gate passes.

目标：计算聚合指标和优化潜力。

步骤1：单篇文章的页面权重

对于每篇包含图片的文章，统计图片的总字节数和图片数量。

状态	总图片大小
良好	<1 MB
警告	1-3 MB
严重	>3 MB

步骤2：优化预估

计算每个可操作项的潜在节省空间：

WebP转换：照片约节省30%，截图约节省25%
调整至最大1200px宽度：根据原始尺寸有所不同
压缩优化：额外节省10-20%
所有建议的总预估节省空间

预估结果需以具体字节数呈现（例如："节省约340 KB"），绝不能仅使用模糊的百分比。

步骤3：确定最高优先级的修复项

根据潜在影响对问题进行排序：

失效引用（FAIL）——内容已明显损坏
缺失Alt文本（FAIL）——违反可访问性要求
过重页面中的过大图片——先处理最影响页面权重的
格式不匹配且节省潜力最大的项

检查点：所有文章的指标均已计算完成。优化预估为具体数值。优先级排序已确立。仅当检查点通过后才可进入下一阶段。

Phase 4: REPORT

阶段4：报告

Goal: Generate a structured, actionable audit report.

Follow the report format in

references/report-templates.md

. The report must include:

Summary: Total images, total size, posts with images, averages
Alt Text Issues: Every FAIL and WARN with file path, line number, current alt text
File Size Issues: Every oversized image with size and recommendation
Missing Files: Every broken reference with source file and line number
Unused Images: Every orphaned file with size
Format Suggestions: Aggregated conversion recommendations with estimated savings
Page Weight: Per-post breakdown, heaviest posts first
Recommendations: Numbered, prioritized action items
Status Line: PASS, WARN, or FAIL with counts

Gate: Report is complete with all sections populated. Every issue is actionable (file path + line number + recommendation). Report ends with a status line.

目标：生成结构化、可执行的审计报告。

请遵循

references/report-templates.md

中的报告格式。报告必须包含：

摘要：图片总数、总大小、包含图片的文章数量、平均值
Alt文本问题：每个FAIL和WARN项的文件路径、行号及当前Alt文本
文件大小问题：每个过大图片的大小及优化建议
缺失文件：每个失效引用的源文件及行号
未使用图片：每个孤立文件的大小
格式建议：汇总转换建议及预估节省空间
页面权重：按文章拆分的详情，从重到轻排序
建议：编号的优先级修复项
状态行：PASS、WARN或FAIL及对应数量

检查点：报告所有部分均已填充完整。每个问题均具备可执行性（文件路径+行号+建议）。报告结尾需包含状态行。

Examples

示例

Example 1: Clean Site

示例1：无问题站点

User says: "Run an image audit" Actions:

Glob for all images in static/, Grep for all references in content/ (DISCOVER)
Validate alt text, existence, sizes, formats for each reference (VALIDATE)
Compute page weights and optimization potential (ANALYZE)
Generate report showing no critical issues, minor format suggestions (REPORT) Result: STATUS: PASS with optional WebP conversion suggestions

用户指令："运行图片审计" 操作步骤：

使用Glob查找static/中的所有图片，使用Grep查找内容中的所有引用（发现阶段）
验证每个引用的Alt文本、存在性、大小、格式（验证阶段）
计算页面权重和优化潜力（分析阶段）
生成无严重问题的报告，仅包含少量格式建议（报告阶段）结果：状态：PASS，附带可选的WebP转换建议

Example 2: Site with Multiple Issues

示例2：存在多个问题的站点

User says: "Check all images before we publish" Actions:

Build reference map of 24 images across 8 posts (DISCOVER)
Find 2 missing alt texts, 1 broken reference, 1 oversized image (VALIDATE)
Calculate 4.2 MB total weight, 2.1 MB on heaviest post (ANALYZE)
Generate report with 4 critical issues and 5 format suggestions (REPORT) Result: STATUS: FAIL with prioritized fix list

用户指令："发布前检查所有图片" 操作步骤：

构建包含8篇文章中24张图片的引用映射（发现阶段）
发现2处缺失Alt文本、1处失效引用、1张过大图片（验证阶段）
计算总权重为4.2 MB，最重的文章达2.1 MB（分析阶段）
生成包含4个严重问题和5个格式建议的报告（报告阶段）结果：状态：FAIL，附带优先级修复列表

Example 3: Single Post Audit

示例3：单篇文章审计

User says: "Audit images in content/posts/2024-12-theme.md" Actions:

Grep that specific file for image references (DISCOVER)
Validate the 4 images found: 3 pass, 1 missing alt text (VALIDATE)
Sum 890 KB total weight for this post (ANALYZE)
Generate focused report for single post (REPORT) Result: 1 issue to fix (missing alt text on line 45)

用户指令："审计content/posts/2024-12-theme.md中的图片" 操作步骤：

使用Grep查找该文件中的图片引用（发现阶段）
验证找到的4张图片：3张通过，1张缺失Alt文本（验证阶段）
统计该文章的总权重为890 KB（分析阶段）
生成针对该单篇文章的聚焦报告（报告阶段）结果：1个需修复的问题（第45行缺失Alt文本）

Error Handling

错误处理

Error: "No Images Found"

错误："未找到图片"

Cause: Wrong directory, no content files, or non-standard image paths Solution:

Verify static/images/ directory exists
Confirm content files use standard image reference patterns
Check for custom Hugo shortcodes that reference images differently

原因：目录错误、无内容文件或图片路径非标准解决方案：

验证static/images/目录是否存在
确认内容文件使用标准的图片引用模式
检查是否存在引用图片的自定义Hugo短代码

Error: "Cannot Determine Image Dimensions"

错误："无法确定图片尺寸"

Cause: imagemagick not installed or file permissions issue Solution:

Skip dimension checks and audit only file size
Report that dimension analysis was skipped
Note that
```
identify
```
command requires imagemagick package

原因：未安装imagemagick或存在文件权限问题解决方案：

跳过尺寸检查，仅审计文件大小
报告尺寸分析已被跳过
备注
```
identify
```
命令需要安装imagemagick包

Error: "Path Resolution Ambiguous"

错误："路径解析存在歧义"

Cause: Relative paths in content that could resolve to multiple locations Solution:

Try resolving relative to the content file's directory first
Fall back to resolving relative to static/
Report both possible resolutions if ambiguous

原因：内容中的相对路径可能解析到多个位置解决方案：

优先尝试相对于内容文件目录进行解析
回退到相对于static/目录进行解析
如果仍存在歧义，报告所有可能的解析结果

Error: "Permission Denied Reading Files"

错误："读取文件时权限被拒绝"

Cause: File permissions prevent reading image files or content directories Solution:

Check file permissions with
```
ls -la
```
on the failing path
Report which files are inaccessible and skip them
Note skipped files in the report summary so the user knows the audit is incomplete

原因：文件权限限制导致无法读取图片文件或内容目录解决方案：

使用
```
ls -la
```
命令检查失败路径的文件权限
报告哪些文件无法访问并跳过它们
在报告摘要中备注跳过的文件，让用户知晓审计不完整

Anti-Patterns

反模式

Anti-Pattern 1: Modifying Images Without Consent

反模式1：未经同意修改图片

What it looks like: Automatically resizing or converting images during audit Why wrong: User may have specific requirements. Destructive changes cannot be undone. Do instead: Report findings and recommendations. Only modify when user explicitly requests it.

表现：审计过程中自动调整大小或转换图片 错误原因：用户可能有特定需求。破坏性更改无法撤销。 正确做法：报告发现的问题和建议。仅在用户明确请求时才进行修改。

Anti-Pattern 2: Missing Line Numbers in Reports

反模式2：报告中缺失行号

What it looks like: Reporting "screenshot.png missing alt text" without file location Why wrong: User cannot find and fix the issue efficiently without location. Do instead: Always include absolute file path and line number for every issue.

表现：仅报告"screenshot.png缺失Alt文本"，未提供文件位置 错误原因：用户没有位置信息无法高效地找到并修复问题。 正确做法：始终为每个问题附带绝对文件路径和行号。

Anti-Pattern 3: Treating Suggestions as Blockers

反模式3：将建议视为阻塞项

What it looks like: Marking a post as "failed audit" because images are not WebP Why wrong: Format suggestions are optimizations, not requirements. Conflating severity levels undermines trust. Do instead: Clearly distinguish FAIL (broken), WARN (should fix), INFO (suggestion).

表现：因图片未使用WebP格式而标记文章为"审计失败" 错误原因：格式建议是优化项，而非强制要求。混淆严重级别会降低信任度。 正确做法：明确区分FAIL（损坏）、WARN（应修复）、INFO（建议）。

Anti-Pattern 4: Skipping Unused Image Detection

反模式4：跳过未使用图片检测

What it looks like: Only auditing referenced images, ignoring orphaned files in static/ Why wrong: Unused images bloat the repository and deployment size. Do instead: Always compare static/ files against the reference map and report orphans.

表现：仅审计被引用的图片，忽略static/中的孤立文件 错误原因：未使用图片会膨胀仓库和部署包大小。 正确做法：始终将static/中的文件与引用映射进行对比，并报告孤立文件。

Anti-Pattern 5: Not Resolving Relative Paths

反模式5：未解析相对路径

What it looks like: Checking for

../images/foo.png

literally in static/ Why wrong: Relative paths must be resolved from the content file's location to find the actual file. Do instead: Compute absolute path from content file location, then check static/.

表现：直接在static/中查找

../images/foo.png

字面路径 错误原因：相对路径必须相对于内容文件的位置进行解析才能找到实际文件。 正确做法：根据内容文件的位置计算绝对路径，然后检查static/目录。

References

参考资料

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations
Verification Checklist - Pre-completion checks

本Skill使用以下共享模式：

Anti-Rationalization - 避免找借口走捷径
Verification Checklist - 完成前检查

Domain-Specific Anti-Rationalization

领域特定的Anti-Rationalization

Rationalization	Why It's Wrong	Required Action
"Alt text looks fine to me"	Subjective assessment misses generic patterns	Check against generic term list
"File sizes are probably okay"	Estimation is not measurement	Measure actual bytes
"Nobody uses screen readers"	15% of users rely on assistive technology	Validate all alt text
"WebP is overkill for this site"	Format choice affects page load for every visitor	Report savings, let user decide

合理化借口	错误原因	要求操作
"我觉得Alt文本没问题"	主观评估会遗漏通用模式	根据通用术语列表进行检查
"文件大小应该没问题"	估算不等于实际测量	测量实际字节数
"没人用屏幕阅读器"	15%的用户依赖辅助技术	验证所有Alt文本
"这个站点用WebP没必要"	格式选择会影响每个访客的页面加载速度	报告节省空间，让用户决定

Integration Notes

集成说明

With pre-publish-checker: The pre-publish-checker skill performs basic image validation (existence, alt text presence). This skill provides deeper analysis including format optimization, page weight, and unused image detection. Use pre-publish for quick pass/fail; use image-auditor for comprehensive audits.

With Hugo build: Run image audit before

hugo --minify

to catch broken references and optimize assets before deployment.

Recommended cadence: Run full audit periodically (weekly or before releases). Address FAIL issues immediately. Schedule WARN issues for optimization sprints.

与pre-publish-checker集成：pre-publish-checker Skill执行基础的图片验证（存在性、Alt文本是否存在）。本Skill提供更深入的分析，包括格式优化、页面权重和未使用图片检测。快速检查使用pre-publish，全面审计使用image-auditor。

与Hugo构建集成：在运行

hugo --minify

前执行图片审计，以在部署前捕获失效引用并优化资源。

推荐执行频率：定期进行全面审计（每周或发布前）。立即处理FAIL级别的问题。将WARN级别的问题安排到优化迭代中。

Reference Files

参考文件

${CLAUDE_SKILL_DIR}/references/alt-text-examples.md

: Good and bad alt text examples by image type

```
${CLAUDE_SKILL_DIR}/references/size-guidelines.md
```
: Maximum file sizes, dimension limits, page weight budgets
```
${CLAUDE_SKILL_DIR}/references/format-selection.md
```
: Format decision flowchart and detection heuristics

${CLAUDE_SKILL_DIR}/references/report-templates.md

: Full audit and single-post report templates

${CLAUDE_SKILL_DIR}/references/alt-text-examples.md

: 按图片类型分类的Alt文本好坏示例

```
${CLAUDE_SKILL_DIR}/references/size-guidelines.md
```
: 最大文件大小、尺寸限制、页面权重预算

${CLAUDE_SKILL_DIR}/references/format-selection.md

: 格式决策流程图和检测启发式规则

${CLAUDE_SKILL_DIR}/references/report-templates.md

: 全面审计和单篇文章审计的报告模板