batch-editor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Batch Editor Skill

Operator Context

操作器上下文

This skill operates as an operator for bulk content editing, configuring Claude's behavior for safe, reversible batch modifications across Hugo blog posts. It implements a Preview-Confirm-Apply pattern with mandatory git safety checks before any destructive operation.

该Skill作为批量内容编辑的操作器，配置Claude的行为以实现对Hugo博客文章的安全、可撤销批量修改。它采用预览-确认-应用模式，在执行任何破坏性操作前强制进行Git安全检查。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md files
Preview First: ALWAYS show complete preview before applying any changes
Git Safety: Check for uncommitted changes before any modification
Never Auto-Apply: Require explicit user confirmation for destructive operations
Complete Output: Show all affected files and changes, never summarize matches
Atomic Operations: All files succeed or none are modified

CLAUDE.md 合规性：读取并遵循仓库中的CLAUDE.md文件
先预览：在应用任何更改前，始终展示完整预览内容
Git安全检查：在进行任何修改前，检查是否存在未提交的更改
绝不自动应用：执行破坏性操作前需要用户明确确认
完整输出：展示所有受影响的文件及更改内容，绝不汇总匹配结果
原子操作：要么所有文件修改成功，要么全部不修改

Default Behaviors (ON unless disabled)

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

Preview Mode: Show all matches without modifying files
Backup Reminder: Suggest git commit/stash before applying changes
Case Sensitive: Find/replace is case-sensitive by default
Content Scope: Only process files in content/posts/
Preserve Formatting: Keep original frontmatter indentation, quotes, field order

预览模式：展示所有匹配结果但不修改文件
备份提醒：在应用更改前建议用户执行git commit/stash
区分大小写：默认查找/替换操作区分大小写
内容范围：仅处理content/posts/目录下的文件
保留格式：保留原始Frontmatter的缩进、引号、字段顺序

Optional Behaviors (OFF unless enabled)

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

Case Insensitive: Use --ignore-case for case-insensitive matching
Include Drafts: Use --include-drafts to also process draft posts
Extended Scope: Use --scope to process other content directories
Force Apply: Use --force to skip git safety checks (dangerous)

不区分大小写：使用--ignore-case进行不区分大小写的匹配
包含草稿：使用--include-drafts同时处理草稿文章
扩展范围：使用--scope处理其他内容目录
强制应用：使用--force跳过Git安全检查（存在风险）

What This Skill CAN Do

该Skill能实现的功能

Find and replace text (literal or regex) across multiple markdown files
Add, modify, or remove frontmatter fields in bulk
Batch update tags, categories, or other taxonomy arrays
Standardize heading levels, link formats, and whitespace
Preview all changes with line-level context before applying
Count total matches and affected files with dry-run validation

在多个Markdown文件中进行文本查找和替换（支持字面量或正则表达式）
批量添加、修改或删除Frontmatter字段
批量更新标签、分类或其他分类法数组
统一标题层级、链接格式和空白字符
在应用更改前预览所有带行级上下文的修改
通过试运行验证统计匹配总数和受影响文件数

What This Skill CANNOT Do

该Skill不能实现的功能

Modify files outside content/ directory
Skip the preview step (hardcoded safety)
Undo changes without git (use git rollback)
Modify files when git has uncommitted changes (unless --force)
Process binary files or images
Make external API calls

修改content/目录以外的文件
跳过预览步骤（安全机制硬编码）
不通过Git撤销更改（请使用git回滚）
当Git存在未提交更改时修改文件（除非使用--force）
处理二进制文件或图片
调用外部API

Instructions

使用说明

Usage

用法

/batch-edit [operation] [options]

Operations:

```
find-replace
```
- Text replacement with optional regex
```
frontmatter
```
- Add/modify/remove frontmatter fields
```
transform
```
- Content transformations (links, headings, whitespace, quotes)

Common Options:

```
--dry-run
```
- Validate pattern, show matches, don't apply
```
--apply
```
- Apply changes after preview confirmation
```
--ignore-case
```
- Case-insensitive matching
```
--include-drafts
```
- Also process draft posts
```
--scope <path>
```
- Process different content directory
```
--regex
```
- Enable regex mode for find-replace

/batch-edit [operation] [options]

操作类型：

```
find-replace
```
- 文本替换（支持正则表达式）
```
frontmatter
```
- 批量添加/修改/删除Frontmatter字段
```
transform
```
- 内容转换（链接、标题、空白字符、引号等）

通用选项：

```
--dry-run
```
- 验证匹配模式，展示匹配结果但不应用更改
```
--apply
```
- 预览确认后应用更改
```
--ignore-case
```
- 不区分大小写匹配
```
--include-drafts
```
- 同时处理草稿文章
```
--scope <path>
```
- 处理指定的其他内容目录
```
--regex
```
- 为查找/替换开启正则模式

Phase 1: SAFETY CHECK

阶段1：安全检查

Before any batch operation, verify git status:

bash

cd $HOME/your-project && git status --porcelain

Analyze results:

Status	Action
Empty (clean)	Proceed with operation
Has changes	Warn user, suggest commit/stash first
Not a git repo	Warn about no rollback capability

Safety check output must include:

Repository path and current branch
Clean/dirty status
List of modified files (if any)
Recommended action (commit, stash, or proceed)

Gate: Git status is clean OR user provides --force. Do not proceed without passing this gate.

在执行任何批量操作前，先验证Git状态：

bash

cd $HOME/your-project && git status --porcelain

结果分析：

状态	操作
空（干净）	继续执行操作
存在未提交更改	向用户发出警告，建议先提交/暂存更改
非Git仓库	警告用户无法回滚更改

安全检查输出必须包含：

仓库路径和当前分支
仓库状态（干净/有未提交更改）
修改文件列表（如果有）
推荐操作（提交、暂存或继续）

准入条件：Git状态为干净，或用户提供--force参数。未满足条件则不继续执行。

Phase 2: SCAN AND PREVIEW

阶段2：扫描与预览

Step 1: Parse request

Extract from user request:

Pattern: Text or regex to find (for find-replace)
Replacement: Text to replace with (for find-replace)
Field/Value: Frontmatter field name and value (for frontmatter ops)
Action: add | modify | remove (for frontmatter ops)
Scope: File pattern (default:
```
content/posts/*.md
```
)
Options: Case sensitivity, regex mode, draft inclusion

Step 2: Find all matches

Use Grep to locate all matches within scope:

bash

undefined

步骤1：解析请求

从用户请求中提取：

匹配模式：要查找的文本或正则表达式（适用于find-replace操作）
替换内容：用于替换的文本（适用于find-replace操作）
字段/值：Frontmatter字段名和对应值（适用于frontmatter操作）
操作：add | modify | remove（适用于frontmatter操作）
范围：文件匹配模式（默认：
```
content/posts/*.md
```
）
选项：是否区分大小写、正则模式、是否包含草稿

步骤2：查找所有匹配项

使用Grep在指定范围内查找所有匹配项：

bash

undefined

For literal text

字面量文本查找

grep -rn "search-pattern" $HOME/your-project/content/posts/*.md

For regex

正则表达式查找

grep -rn -E "regex-pattern" $HOME/your-project/content/posts/*.md


For frontmatter operations, read each file and parse the YAML frontmatter block between `---` delimiters to check field presence and values.

**Step 3: Generate preview**

For each match, show:
- File path relative to repository root
- Line number and surrounding context
- Before/after comparison (for replacements)
- Diff-style additions (+) and removals (-) for frontmatter operations
- Total count of files affected and matches found

**Preview format for find-replace:**

content/posts/example.md: Line 5: "original text here" -> "replacement text here"


**Preview format for frontmatter:**

content/posts/example.md:

author: "Author Name" (add)

deprecated: "old" (remove) ~ tags: ["a"] -> ["a","b"] (modify)


**Gate**: Preview displayed with all matches visible. User must see every individual change. Never summarize as "N matches in M files" without showing each one.

grep -rn -E "regex-pattern" $HOME/your-project/content/posts/*.md


对于Frontmatter操作，读取每个文件并解析`---`分隔符之间的YAML Frontmatter块，检查字段是否存在及其值。

**步骤3：生成预览**

对于每个匹配项，展示：
- 相对于仓库根目录的文件路径
- 行号和上下文内容
- 替换前后的对比（适用于替换操作）
- Frontmatter操作的差异式添加（+）和删除（-）
- 受影响的文件总数和匹配项总数

**查找/替换的预览格式：**

content/posts/example.md: Line 5: "original text here" -> "replacement text here"


**Frontmatter操作的预览格式：**

content/posts/example.md:

author: "Author Name" (add)

deprecated: "old" (remove) ~ tags: ["a"] -> ["a","b"] (modify)


**准入条件**：展示所有可见的匹配项预览。用户必须能看到每一处具体更改，绝不能仅汇总为「M个文件中找到N个匹配项」而不展示每个匹配项。

Phase 3: APPLY (on explicit confirmation only)

阶段3：应用更改（仅在用户明确确认后执行）

Only proceed when user explicitly confirms with

--apply

or clear affirmative.

For find-replace:

Read each file with matches
Perform all replacements in the file
Write the modified content back
Report per-file completion

For frontmatter add:

Read file, parse frontmatter (YAML --- delimiters)
Insert new field before closing
```
---
```
Preserve original formatting (indentation, quote style, field order)
Write modified content

For frontmatter modify:

Read file, locate the target field line
Replace only that line's value
Preserve formatting of all other fields
Write modified content

For frontmatter remove:

Read file, locate and remove the target field line
Write modified content

Gate: All files written successfully. Show post-apply summary with per-file counts and rollback command.

仅当用户通过

--apply

或明确的肯定指令确认后，才继续执行。

对于查找/替换操作：

读取所有包含匹配项的文件
在文件中执行所有替换操作
将修改后的内容写回文件
报告每个文件的完成情况

对于Frontmatter添加操作：

读取文件，解析Frontmatter（YAML ---分隔符）
在结束
```
---
```
之前插入新字段
保留原始格式（缩进、引号样式、字段顺序）
写入修改后的内容

对于Frontmatter修改操作：

读取文件，定位目标字段所在行
仅替换该行的值
保留其他所有字段的格式
写入修改后的内容

对于Frontmatter删除操作：

读取文件，定位并删除目标字段所在行
写入修改后的内容

准入条件：所有文件写入成功。展示应用后的汇总信息，包括每个文件的更改数量和回滚命令。

Phase 4: VERIFY

阶段4：验证

After applying changes:

Report totals: Files changed, total replacements or field modifications
Show per-file summary: Each file with count of changes made
Provide rollback command:
```
git checkout -- content/posts/
```
Suggest next steps:
- ```
git diff content/posts/
```
  to review all changes
- ```
hugo --quiet
```
  to verify site still builds
- ```
git commit -am "batch edit: description"
```
  to save changes

Gate: Post-apply summary displayed with rollback instructions.

应用更改后：

统计报告：修改的文件数、总替换次数或字段修改次数
文件级汇总：每个文件的更改数量
提供回滚命令：
```
git checkout -- content/posts/
```
建议后续步骤：
- ```
git diff content/posts/
```
  查看所有更改
- ```
hugo --quiet
```
  验证站点仍能正常构建
- ```
git commit -am "batch edit: description"
```
  保存更改

准入条件：展示应用后的汇总信息及回滚说明。

Content Transformation Reference

内容转换参考

The

transform

operation supports these built-in transforms:

Transform	Pattern	Replacement
Demote headings	`^(#{1,5}) (.+)$`	`#$1 $2`
Promote headings	`^##(#{0,4}) (.+)$`	`#$1 $2`
Trailing whitespace	`[ \t]+$`	(empty)
Multiple blank lines	`\n{3,}`	`\n\n`
Smart quotes to straight	`[\u201C\u201D]`	`"`
HTTP to HTTPS links	`\[([^\]]+)\]\(http://`	`[$1](https://`

For custom transforms, use

find-replace --regex

with user-provided patterns. See

references/regex-patterns.md

for tested patterns.

transform

操作支持以下内置转换：

转换类型	匹配模式	替换内容
降低标题层级	`^(#{1,5}) (.+)$`	`#$1 $2`
提升标题层级	`^##(#{0,4}) (.+)$`	`#$1 $2`
尾部空白字符	`[ \t]+$`	（空）
多行空白	`\n{3,}`	`\n\n`
智能引号转直引号	`[\u201C\u201D]`	`"`
HTTP链接转HTTPS	`\[([^\]]+)\]\(http://`	`[$1](https://`

如需自定义转换，可使用

find-replace --regex

结合用户提供的模式。请查看

references/regex-patterns.md

获取已测试的正则模式。

Examples

示例

Example 1: Simple Find/Replace

示例1：简单查找/替换

User says: "Replace Hugo with Hugo SSG across all posts" Actions:

Check git status -- clean, proceed (SAFETY CHECK)
Grep for "Hugo" in content/posts/*.md, show all matches with line context (SCAN)
Display preview: 3 files, 7 matches with before/after for each line (PREVIEW gate)
User confirms with --apply
Apply replacements, show per-file summary with rollback command (APPLY + VERIFY) Result: All occurrences replaced, rollback instructions provided

用户指令："Replace Hugo with Hugo SSG across all posts" 操作步骤：

检查Git状态——状态干净，继续（安全检查）
在content/posts/*.md中Grep查找"Hugo"，展示所有带行上下文的匹配结果（扫描）
展示预览：3个文件，7处匹配，每行展示替换前后内容（预览准入）
用户通过--apply确认
执行替换，展示文件级汇总和回滚命令（应用+验证）结果：所有匹配项替换完成，提供回滚说明

Example 2: Add Frontmatter Field

示例2：添加Frontmatter字段

User says: "Add author field to all posts that don't have one" Actions:

Check git status -- clean, proceed (SAFETY CHECK)
Scan all posts, parse frontmatter, identify those missing
```
author
```
field (SCAN)
Show preview with
```
+ author: "Author Name"
```
for each file, skip files that already have it (PREVIEW gate)
User confirms with --apply
Insert field before closing
```
---
```
in each file, preserving formatting (APPLY)
Report: 4 files modified, 2 skipped (already had author) (VERIFY) Result: Field added to posts missing it, existing posts unchanged

用户指令："Add author field to all posts that don't have one" 操作步骤：

检查Git状态——状态干净，继续（安全检查）
扫描所有文章，解析Frontmatter，识别缺少
```
author
```
字段的文章（扫描）
展示预览：对每个目标文件显示
```
+ author: "Author Name"
```
，跳过已包含该字段的文件（预览准入）
用户通过--apply确认
在每个目标文件的结束
```
---
```
前插入字段，保留原始格式（应用）
报告：修改了4个文件，跳过2个（已包含author字段）（验证）结果：为缺少author字段的文章添加了该字段，已存在该字段的文章未修改

Example 3: Content Transform

示例3：内容转换

User says: "Demote all H1 headings to H2" Actions:

Check git status -- clean, proceed (SAFETY CHECK)
Grep for
```
^# 
```
(H1 pattern), show before/after per line (SCAN)
Display preview:
```
# Introduction
```
->
```
## Introduction
```
for each match (PREVIEW gate)
User confirms with --apply
Apply regex replacement
```
^# (.+)$
```
->
```
## $1
```
across matched files (APPLY)
Suggest
```
hugo --quiet
```
to verify no build issues (VERIFY) Result: All H1 headings demoted, H2+ unchanged

用户指令："Demote all H1 headings to H2" 操作步骤：

检查Git状态——状态干净，继续（安全检查）
Grep查找
```
^# 
```
（H1模式），每行展示转换前后内容（扫描）
展示预览：
```
# Introduction
```
->
```
## Introduction
```
每个匹配项（预览准入）
用户通过--apply确认
对匹配文件执行正则替换
```
^# (.+)$
```
->
```
## $1
```
（应用）
建议执行
```
hugo --quiet
```
验证站点构建无问题（验证）结果：所有H1标题层级降低为H2，H2及以上层级标题不变

Example 4: Regex with Dry Run

示例4：正则表达式试运行

User says: "Show me all date formats in posts but don't change anything" Actions:

Check git status (SAFETY CHECK)
Grep for
```
(\d{4})-(\d{2})-(\d{2})
```
across posts (SCAN)
Display all matches with file and line context (PREVIEW)
DRY RUN mode -- no apply option shown, pattern validation only Result: User sees all date occurrences, can decide on follow-up action

See

references/examples.md

for full output format templates with banner formatting.

用户指令："Show me all date formats in posts but don't change anything" 操作步骤：

检查Git状态（安全检查）
在所有文章中Grep查找
```
(\d{4})-(\d{2})-(\d{2})
```
（扫描）
展示所有匹配项的文件和行上下文（预览）
试运行模式——不展示应用选项，仅验证匹配模式结果：用户查看所有日期格式的匹配项，可决定后续操作

请查看

references/examples.md

获取完整输出格式模板和扩展示例。

Error Handling

错误处理

Error: "No Matches Found"

错误："未找到匹配项"

Cause: Pattern does not match any content in scope Solution:

Check spelling of search pattern
Try case-insensitive with --ignore-case
Expand scope with --scope content/
Verify files exist in target directory

原因：匹配模式在指定范围内未找到任何内容解决方案：

检查搜索模式的拼写
使用--ignore-case开启不区分大小写匹配
使用--scope content/扩展处理范围
验证目标目录下存在文件

Error: "Uncommitted Git Changes"

错误："存在未提交的Git更改"

Cause: Working directory has modifications that could be lost Solution:

Commit changes:

git commit -am "backup before batch edit"

Stash changes:
```
git stash
```
Override with --force (not recommended)

原因：工作目录存在可能丢失的修改解决方案：

提交更改：

git commit -am "backup before batch edit"

暂存更改：
```
git stash
```
使用--force强制跳过（不推荐）

Error: "Invalid Regex Pattern"

错误："无效的正则表达式模式"

Cause: Malformed regular expression syntax Solution:

Escape special characters:
```
 \[ \]
```
Test pattern first:
```
grep -E "pattern" content/posts/*.md
```
Use literal mode (no --regex) for simple text replacement

原因：正则表达式语法错误解决方案：

转义特殊字符：
```
 \[ \]
```
先测试模式：
```
grep -E "pattern" content/posts/*.md
```
对于简单文本替换，使用字面量模式（不添加--regex）

Error: "Partial Application Failure"

错误："部分应用失败"

Cause: Some files could not be written (permissions, disk space) Solution:

Check file permissions:
```
ls -la content/posts/
```
Rollback applied changes:
```
git checkout -- content/posts/
```
Fix permissions:
```
chmod 644 content/posts/*.md
```
Retry operation

原因：部分文件无法写入（权限问题、磁盘空间不足等）解决方案：

检查文件权限：
```
ls -la content/posts/
```
回滚已应用的更改：
```
git checkout -- content/posts/
```
修复权限：
```
chmod 644 content/posts/*.md
```
重试操作

Anti-Patterns

反模式

Anti-Pattern 1: Applying Without Preview

反模式1：不预览直接应用

What it looks like: Immediately modifying files without showing what will change Why wrong: Batch operations can cause widespread damage. User loses ability to catch mistakes. Do instead: ALWAYS show complete preview first. Never modify files until user explicitly confirms.

表现：不展示将要进行的更改就直接修改文件危害：批量操作可能造成大范围损坏，用户无法提前发现错误 正确做法：始终先展示完整预览，直到用户明确确认后再修改文件

Anti-Pattern 2: Summarizing Instead of Showing

反模式2：汇总结果而非逐个展示

What it looks like: "Found 47 matches across 12 files. Apply changes?" Why wrong: User cannot verify each change is correct. Some matches may be false positives. Do instead: Show every match with line-level before/after context.

表现：仅告知用户「在12个文件中找到47个匹配项，是否应用更改？」危害：用户无法验证每个更改是否正确，可能存在误匹配 正确做法：展示每个匹配项，包含行级别的替换前后对比

Anti-Pattern 3: Ignoring Git State

反模式3：忽略Git状态

What it looks like: Proceeding with batch edit when git has uncommitted changes Why wrong: User may lose work. Rollback becomes complicated with mixed changes. Do instead: Always check git status first. Block if uncommitted changes exist (unless --force).

表现：当Git存在未提交更改时仍执行批量编辑危害：用户可能丢失工作，回滚混合更改会变得复杂 正确做法：始终先检查Git状态，若存在未提交更改则阻止操作（除非使用--force）

Anti-Pattern 4: Destroying Frontmatter Format

反模式4：破坏Frontmatter格式

What it looks like: Rewriting entire frontmatter block when modifying a single field Why wrong: Creates noisy git diffs, may break parsers, loses author's preferred formatting. Do instead: Modify only the target field. Preserve indentation, quote style, and field order.

表现：修改单个字段时重写整个Frontmatter块危害：产生冗余的Git差异，可能破坏解析器，丢失作者偏好的格式 正确做法：仅修改目标字段，保留缩进、引号样式和字段顺序

Anti-Pattern 5: Non-Atomic Application

反模式5：非原子操作

What it looks like: Applying changes to some files, then failing on others mid-operation Why wrong: Leaves repository in inconsistent state with partial edits. Do instead: Validate all files are writable before applying any changes. All or nothing.

表现：部分文件修改成功，部分文件修改失败，导致操作中断危害：仓库处于不一致的部分编辑状态 正确做法：在应用更改前验证所有文件可写入，确保操作是原子性的（要么全成，要么全败）

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
"Only a few files, no need to preview"	Few files can still have false positives	Show complete preview
"Pattern is simple, regex won't over-match"	Simple patterns match unexpected content	Test with grep first
"Git is clean, no need to check"	Status could have changed since last check	Always verify
"User said apply, skip the preview"	User may not realize scope of changes	Preview is hardcoded, never skip

合理化借口	错误原因	正确做法
"只有几个文件，不需要预览"	即使少量文件也可能存在误匹配	始终展示完整预览
"模式很简单，正则不会误匹配"	简单模式也可能匹配到意外内容	先用grep测试模式
"Git状态是干净的，不需要检查"	自上次检查后状态可能已更改	每次操作前都要验证
"用户说要应用，跳过预览"	用户可能没意识到更改的范围	预览是硬编码的安全机制，绝不跳过

Reference Files

参考文件

${CLAUDE_SKILL_DIR}/references/operation-types.md

: Detailed operation syntax and options

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

: Common regex patterns for Hugo content

```
${CLAUDE_SKILL_DIR}/references/safety-checklist.md
```
: Pre-edit validation steps and rollback procedures
```
${CLAUDE_SKILL_DIR}/references/examples.md
```
: Full output format templates and extended examples

${CLAUDE_SKILL_DIR}/references/operation-types.md

：详细的操作语法和选项

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

：适用于Hugo内容的常用正则模式

${CLAUDE_SKILL_DIR}/references/safety-checklist.md

：编辑前的验证步骤和回滚流程

```
${CLAUDE_SKILL_DIR}/references/examples.md
```
：完整的输出格式模板和扩展示例