seo-optimizer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SEO Optimizer Skill

SEO优化器Skill

Operator Context

运行背景

This skill operates as an operator for SEO optimization workflows, configuring Claude's behavior for search visibility improvements without compromising content quality. It implements a 4-phase ASSESS-DECIDE-APPLY-VERIFY workflow with evidence-based analysis at each step.

本Skill作为SEO优化工作流的执行器，配置Claude的行为以提升搜索可见性，同时不损害内容质量。它采用评估-决策-应用-验证四阶段工作流，每个阶段均基于证据开展分析。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before execution
Voice Preservation: Never suggest changes that compromise the author's authentic tone
No Keyword Stuffing: Never recommend keyword density above 2.5%
Honest Descriptions: Meta descriptions must accurately reflect content — no clickbait
Preview Before Modify: Always show current vs suggested changes before applying modifications
Over-Engineering Prevention: Focus on high-impact SEO changes only; skip marginal optimizations

遵循CLAUDE.md规范执行前阅读并遵循仓库中的CLAUDE.md文件
保留作者语气：绝不建议会破坏作者真实语气的修改
禁止关键词堆砌：绝不建议关键词密度超过2.5%
真实描述：元描述必须准确反映内容，不得使用标题党
修改前预览：在应用修改前，始终展示当前内容与建议修改的对比
避免过度优化：仅关注高影响力的SEO修改，忽略边际优化

Default Behaviors (ON unless disabled)

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

Complete Analysis: Show all findings with data, never summarize without evidence
Alternative Generation: Provide 3 title alternatives using different title patterns
Internal Link Discovery: Scan related posts for linking opportunities
Confirmation Required: Require explicit user confirmation before modifying any file

完整分析：展示所有带数据的分析结果，绝不无依据地总结
生成替代方案：使用不同标题格式提供3个标题备选
内部链接发现：扫描相关文章以寻找链接机会
需要确认：修改任何文件前需获得用户明确确认

Optional Behaviors (OFF unless enabled)

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

Auto-Apply: Apply changes without confirmation (requires explicit --apply flag)
Batch Mode: Analyze multiple posts at once (requires explicit --batch flag)
Generate Missing: Create meta descriptions for posts that lack them

自动应用：无需确认即可应用修改（需显式添加--apply参数）
批量模式：同时分析多篇文章（需显式添加--batch参数）
生成缺失内容：为缺少元描述的文章创建元描述

What This Skill CAN Do

本Skill可执行的操作

Analyze keyword placement across title, headers, first paragraph, and body
Calculate keyword density and flag over-optimization
Evaluate title length, specificity, and click potential
Generate or improve meta descriptions within 150-160 character targets
Audit header hierarchy (H1/H2/H3 structure and nesting)
Identify internal linking opportunities to related posts
Show before/after comparisons for all proposed changes

分析关键词在标题、标题层级、首段和正文中的分布
计算关键词密度并标记过度优化情况
评估标题长度、具体性和点击潜力
生成或优化元描述，使其长度控制在150-160字符范围内
审核标题层级（H1/H2/H3结构与嵌套）
识别指向相关文章的内部链接机会
展示所有建议修改的前后对比

What This Skill CANNOT Do

本Skill不可执行的操作

Modify post body content beyond front matter and headers — voice belongs to the author
Guarantee search rankings — SEO is one factor among many
Replace human judgment on content quality or brand fit
Auto-publish changes without explicit user review and confirmation
Handle site-wide technical SEO (robots.txt, sitemap, redirects)

除前置元数据和标题层级外，不得修改文章正文内容——作者语气需保留
无法保证搜索排名——SEO只是众多影响因素之一
无法替代人类对内容质量或品牌契合度的判断
未经用户明确审核和确认，不得自动发布修改
不处理全站技术SEO（如robots.txt、站点地图、重定向）

Instructions

操作说明

Phase 1: ASSESS — Analyze Current SEO State

阶段1：评估——分析当前SEO状态

Goal: Build a complete picture of the post's current search optimization.

Step 1: Read and parse the post

Read the target post file. Extract:

Title from front matter
Existing description/summary (if any)
All headers (H2, H3, etc.) and their hierarchy
First paragraph content (first 100 words)
Full body text for keyword analysis

Step 2: Identify primary keyword

Determine the primary keyword/phrase by:

Most repeated relevant phrase (excluding stop words)
Topic implied by the title
Technical term most central to the content

Document the result:

Primary keyword: "hugo debugging"
Secondary keywords: "template errors", "build failures", "hugo troubleshooting"

Step 3: Analyze keyword placement

Check keyword presence in each priority location:

Location	Weight	Check
Title	Critical	Exact match or close variation, front-loaded preferred
First paragraph	High	Within first 100 words
H2 headers	Medium	Present in 2-3 of main section headers
Body text	Medium	Natural usage throughout
URL slug	Medium	Keyword in filename

Calculate keyword density:

Density = (keyword occurrences / total words) * 100
Target: 1-2%  |  Warning: > 2.5%  |  Critical: > 3%

Step 4: Evaluate title

Criteria	Target
Length	50-60 characters
Keyword position	Front-loaded (first half)
Specificity	Specific problem/outcome over vague topic
Click potential	Conveys clear value to searcher

Step 5: Check meta description

If description exists: verify 150-160 characters, contains primary keyword, accurately reflects content, compels click.

If missing: flag for generation in Phase 3.

Step 6: Audit header structure

Verify: exactly one H1 (the title), 3-7 H2s for main sections, H3s for subsections, no skipped levels (no H1 to H3 without H2).

Step 7: Scan for internal linking opportunities

List all related posts. For each candidate:

Identify relevant anchor text in current post
Note the link target
Flag if current post is an orphan (zero inbound links)

Gate: Complete analysis with data for every check. Do not proceed to Phase 2 without keyword density calculated and all locations assessed.

目标：全面了解文章当前的搜索优化状态

步骤1：读取并解析文章

读取目标文章文件，提取以下内容：

前置元数据中的标题
现有描述/摘要（如有）
所有标题层级（H2、H3等）及其结构
首段内容（前100词）
完整正文用于关键词分析

步骤2：确定核心关键词

通过以下方式确定核心关键词/短语：

出现频率最高的相关短语（排除停用词）
标题隐含的主题
内容中最核心的技术术语

记录结果：

Primary keyword: "hugo debugging"
Secondary keywords: "template errors", "build failures", "hugo troubleshooting"

步骤3：分析关键词布局

检查关键词在各优先级位置的出现情况：

位置	权重	检查项
标题	关键	完全匹配或近似变体，建议前置
首段	高	出现在前100词内
H2标题	中	出现在2-3个主要章节标题中
正文	中	自然分布在全文
URL路径	中	文件名包含关键词

计算关键词密度：

Density = (keyword occurrences / total words) * 100
Target: 1-2%  |  Warning: > 2.5%  |  Critical: > 3%

步骤4：评估标题

评估标准	目标
长度	50-60字符
关键词位置	前置（前半部分）
具体性	聚焦具体问题/结果，而非模糊主题
点击潜力	向搜索者传递明确价值

步骤5：检查元描述

若存在描述：验证其长度为150-160字符、包含核心关键词、准确反映内容、具备吸引力。若缺失：标记为阶段3需要生成의内容。

步骤6：审核标题结构

验证：仅有一个H1（即标题），3-7个H2用于主要章节，H3用于子章节，无层级跳跃（不得从H1直接到H3而无H2）。

步骤7：扫描内部链接机会

列出所有相关文章，对每个候选文章：

在当前文章中识别相关锚文本
记录链接目标
若当前文章无入链（孤立文章），标记此情况

准入条件：完成所有带数据的检查分析。未计算关键词密度或未评估所有位置的情况下，不得进入阶段2。

Phase 2: DECIDE — Prioritize Changes

阶段2：决策——优先处理修改项

Goal: Rank findings by impact and effort, select actionable improvements.

Step 1: Score each issue

Issue	Impact	Effort
Missing meta description	High	Low
Title too short/long or missing keyword	High	Low
No keyword in first paragraph	Medium	Low
Missing internal links	Medium	Low
Header structure problems	Medium	Medium
Low keyword density	Low	Medium

Step 2: Prioritize high-impact, low-effort first

Add or fix meta description
Optimize title if needed
Add internal links
Adjust headers only if clearly beneficial

Drop any suggestion where the existing content is already good. Do not force changes for the sake of completeness.

Gate: Prioritized list of changes with rationale for each. Skip items that would not materially improve search visibility.

目标：根据影响和实施难度对问题排序，选择可执行的改进项。

步骤1：为每个问题评分

问题	影响	实施难度
缺失元描述	高	低
标题过短/过长或缺失关键词	高	低
首段无关键词	中	低
缺失内部链接	中	低
标题结构问题	中	中
关键词密度低	低	中

步骤2：优先处理高影响、低难度的项

添加或修复元描述
如有需要优化标题
添加内部链接
仅在明确有益时调整标题层级

若现有内容已足够优质，放弃相关建议。不得为了完整性而强制修改。

准入条件：列出带理由的优先修改项。跳过对搜索可见性无实质提升的项。

Phase 3: APPLY — Present Recommendations and Execute

阶段3：应用——呈现建议并执行

Goal: Show the user exactly what will change, get confirmation, apply.

Step 1: Generate output report

===============================================================
 SEO ANALYSIS: {file_path}
===============================================================

 CURRENT STATE:

 Title: "{current_title}" ({char_count} chars)
   {assessment}

 Description: "{current_description}" or "(missing)"
   {assessment}

 Primary Keyword: "{keyword}"
   - In title: yes/no
   - In H2s: {count} of {total}
   - In first paragraph: yes/no
   - Density: {percentage}%

 Headers: H2({count}), H3({count})
   {assessment}

 Internal Links: {count}
   {assessment}

===============================================================
 SUGGESTIONS:

 Title (pick one):
   1. "{alternative_1}" ({chars} chars) — [pattern used]
   2. "{alternative_2}" ({chars} chars) — [pattern used]
   3. "{alternative_3}" ({chars} chars) — [pattern used]

 Description:
   "{generated_description}" ({chars} chars)

 Internal Links:
   - Link "{anchor_text}" -> {target_post}

 Keyword Improvements:
   - {specific_suggestion}

===============================================================
 Apply changes? [preview / apply / skip]
===============================================================

Step 2: Handle user response

preview: Show exact diff of all proposed front matter and content changes
apply: Make changes to front matter fields and insert internal links
skip: Exit without changes

Step 3: Apply confirmed changes

Only modify:

```
title
```
in front matter (if user selected an alternative)
```
description
```
in front matter (add or update)
```
summary
```
in front matter (sync with description for Hugo/PaperMod)
Internal link insertions at suggested anchor points

Gate: All applied changes shown to user. No changes made without explicit confirmation.

目标：向用户准确展示将修改的内容，获得确认后应用。

步骤1：生成输出报告

===============================================================
 SEO ANALYSIS: {file_path}
===============================================================

 CURRENT STATE:

 Title: "{current_title}" ({char_count} chars)
   {assessment}

 Description: "{current_description}" or "(missing)"
   {assessment}

 Primary Keyword: "{keyword}"
   - In title: yes/no
   - In H2s: {count} of {total}
   - In first paragraph: yes/no
   - Density: {percentage}%

 Headers: H2({count}), H3({count})
   {assessment}

 Internal Links: {count}
   {assessment}

===============================================================
 SUGGESTIONS:

 Title (pick one):
   1. "{alternative_1}" ({chars} chars) — [pattern used]
   2. "{alternative_2}" ({chars} chars) — [pattern used]
   3. "{alternative_3}" ({chars} chars) — [pattern used]

 Description:
   "{generated_description}" ({chars} chars)

 Internal Links:
   - Link "{anchor_text}" -> {target_post}

 Keyword Improvements:
   - {specific_suggestion}

===============================================================
 Apply changes? [preview / apply / skip]
===============================================================

步骤2：处理用户响应

preview（预览）：展示所有建议修改的前置元数据和内容的精确差异
apply（应用）：修改前置元数据字段并插入内部链接
skip（跳过）：不做修改直接退出

步骤3：应用已确认的修改

仅修改以下内容：

前置元数据中的
```
title
```
（若用户选择了备选标题）
前置元数据中的
```
description
```
（添加或更新）
前置元数据中的
```
summary
```
（针对Hugo/PaperMod，与description同步）
在建议的锚点位置插入内部链接

准入条件：向用户展示所有已应用的修改。未经明确确认，不得进行任何修改。

Phase 4: VERIFY — Confirm Changes Are Valid

阶段4：验证——确认修改有效

Goal: Ensure changes did not break the post or introduce problems.

Step 1: Show the diff of all modified files

Step 2: Verify front matter is valid YAML (no unclosed quotes, no broken structure)

Step 3: Check that keyword density did not exceed 2.5% after changes

Step 4: If Hugo is available, run a build to confirm no breakage:

bash

hugo --quiet

Step 5: If build fails, revert changes immediately:

bash

git checkout {file_path}

Gate: Post builds successfully with all changes applied. Keyword density within target range. All verification steps pass.

目标：确保修改未破坏文章或引入问题。

步骤1：展示所有修改文件的差异

步骤2：验证前置元数据是有效的YAML格式（无未闭合引号、无结构错误）

步骤3：检查修改后关键词密度未超过2.5%

步骤4：若Hugo可用，执行构建以确认无问题：

bash

hugo --quiet

步骤5：若构建失败，立即回滚修改：

bash

git checkout {file_path}

准入条件：应用所有修改后文章构建成功，关键词密度在目标范围内，所有验证步骤通过。

Error Handling

错误处理

Error: "Post File Not Found"

错误：“文章文件未找到”

Cause: Specified post path does not exist or was misspelled Solution:

List available posts in the content directory
Present candidates to user
Ask user to specify correct filename

原因：指定的文章路径不存在或拼写错误解决方案：

列出内容目录中的可用文章
向用户展示候选文章
请用户指定正确的文件名

Error: "Hugo Build Failed After Changes"

错误：“修改后Hugo构建失败”

Cause: Applied changes broke front matter YAML or content structure Solution:

Revert changes with
```
git checkout {file_path}
```
Show the Hugo error output
Identify which specific change caused the failure
Re-apply changes individually to isolate the problem

原因：应用的修改破坏了前置元数据YAML格式或内容结构解决方案：

使用
```
git checkout {file_path}
```
回滚修改
展示Hugo的错误输出
确定导致失败的具体修改项
逐个重新应用修改以定位问题

Error: "Keyword Density Exceeds Threshold"

错误：“关键词密度超过阈值”

Cause: Post is already over-optimized or changes would push density above 2.5% Solution:

Do not add any changes that increase keyword frequency
Suggest removing redundant keyword occurrences instead
Focus recommendations on structural improvements (title, description, links)

原因：文章已过度优化，或修改会使密度超过2.5% 解决方案：

不得添加任何会增加关键词出现频率的修改
建议移除冗余的关键词出现次数
聚焦于结构性改进建议（标题、描述、链接）

Anti-Patterns

反模式

Anti-Pattern 1: Keyword Stuffing

反模式1：关键词堆砌

What it looks like: "Add 'hugo debugging' 15 more times to reach optimal density" Why wrong: Over-optimization hurts readability and search rankings. Search engines penalize stuffing. Do instead: Aim for 1-2% density with natural placement in title, first paragraph, and occasional headers.

表现：“再添加15次‘hugo debugging’以达到最佳密度” 问题：过度优化会损害可读性和搜索排名，搜索引擎会惩罚堆砌行为。 正确做法：目标密度为1-2%，在标题、首段和偶尔的标题层级中自然放置关键词。

Anti-Pattern 2: Clickbait Titles

反模式2：标题党标题

What it looks like: "You Won't BELIEVE These Hugo Debugging Secrets!" Why wrong: Violates technical, authentic tone. Misleads readers and damages trust. Do instead: Suggest specific, descriptive titles that accurately convey content value using patterns from

references/title-patterns.md

表现：“你绝对想不到这些Hugo调试技巧！” 问题：违背技术文章的真实语气，误导读者并损害信任。 正确做法：参考

references/title-patterns.md

中的格式，建议具体、描述性的标题，准确传达内容价值。

Anti-Pattern 3: Generic Meta Descriptions

反模式3：通用元描述

What it looks like: "Learn about Hugo debugging in this comprehensive guide." Why wrong: Vague descriptions do not differentiate content or compel clicks from search results. Do instead: Include specific outcomes, techniques, or problems addressed. Reference the primary keyword naturally.

表现：“在这份全面指南中了解Hugo调试。” 问题：模糊的描述无法区分内容，也无法吸引搜索结果中的点击。 正确做法：包含具体的成果、技术或解决的问题，自然融入核心关键词。

Anti-Pattern 4: Forcing Changes on Good Structure

反模式4：对优质结构强制修改

What it looks like: "Restructure all headers to include the primary keyword" Why wrong: If existing structure is logical and readable, forcing keywords into every header damages content quality for marginal SEO gain. Do instead: Only suggest header changes where keywords fit naturally AND improve clarity.

表现：“重构所有标题层级以包含核心关键词” 问题：若现有结构逻辑清晰、可读性强，为了微小的SEO收益强制在每个标题中加入关键词会损害内容质量。 正确做法：仅当关键词能自然融入且提升清晰度时，才建议修改标题层级。

Anti-Pattern 5: Optimizing Without Data

反模式5：无数据支撑的优化

What it looks like: Suggesting title changes without measuring current length or keyword presence Why wrong: Changes without baseline data cannot be evaluated for improvement. May make things worse. Do instead: Complete Phase 1 analysis fully before proposing any changes.

表现：未测量当前标题长度或关键词存在情况就建议修改标题问题：无基线数据的修改无法评估是否有改进，可能使情况更糟。 正确做法：在提出任何修改建议前，完整完成阶段1的分析。

References

参考资料

This skill uses these shared patterns:

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

本Skill使用以下共享模式：

反合理化 — 防止捷径式合理化
验证清单 — 完成前检查

Domain-Specific Anti-Rationalization

领域特定反合理化

Rationalization	Why It's Wrong	Required Action
"This title is fine, no need to measure"	Fine is subjective; measure character count	Run length and keyword checks
"Description isn't that important"	Description is the SERP sales pitch	Always analyze and optimize
"Just add keywords everywhere"	Stuffing hurts rankings	Calculate density, stay under 2.5%
"SEO is more important than readability"	Readers bounce from unnatural content	Voice preservation is hardcoded

合理化借口	问题所在	要求操作
“这个标题没问题，不用测量”	“没问题”是主观判断，需测量字符数	执行长度和关键词检查
“描述没那么重要”	描述是搜索结果页的“推销语”	始终分析并优化
“到处加关键词就行”	堆砌会损害排名	计算密度，保持在2.5%以下
“SEO比可读性更重要”	读者会离开不自然的内容	保留作者语气是硬编码规则

Reference Files

参考文件

```
${CLAUDE_SKILL_DIR}/references/seo-guidelines.md
```
: Length requirements, density targets, and best practices

${CLAUDE_SKILL_DIR}/references/keyword-placement.md

: Priority locations and placement techniques

${CLAUDE_SKILL_DIR}/references/title-patterns.md

: Effective title structures for technical blogs

${CLAUDE_SKILL_DIR}/references/seo-guidelines.md

：长度要求、密度目标和最佳实践

${CLAUDE_SKILL_DIR}/references/keyword-placement.md

：优先位置和布局技巧

${CLAUDE_SKILL_DIR}/references/title-patterns.md

：技术博客的有效标题结构