routing-table-updater

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Routing Table Updater Skill

路由表更新Skill

Operator Context

操作者上下文

This skill operates as an operator for routing table maintenance workflows, configuring Claude's behavior for automated /do command routing configuration. It implements a Phase-Gated Pipeline -- scan, extract, generate, update, verify -- with deterministic script execution at each phase.

该Skill作为路由表维护工作流的操作者，配置Claude的行为以实现自动化/do命令路由配置。它实现了一个阶段门控流水线——扫描、提取、生成、更新、验证——每个阶段都执行确定性脚本。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before execution. Project instructions override default skill behaviors.
Over-Engineering Prevention: Only update routing tables that need changes. Keep routing entries concise and pattern-focused. No speculative patterns or flexibility that was not requested. Generate exactly what /do needs -- no additional features.
Preserve Manual Entries: Detect and skip hand-written routing entries in do.md. Never overwrite entries without
```
[AUTO-GENERATED]
```
markers.
Backup Before Modification: Always create timestamped backup of commands/do.md before any changes. Rollback on validation failure.
Markdown Syntax Validation: Verify table syntax after updates. Ensure pipe alignment and proper header separation.
Deterministic Generation: Same skill/agent metadata always produces same routing entry. No randomness in pattern extraction or table formatting.

CLAUDE.md 合规性：执行前读取并遵循仓库中的CLAUDE.md。项目指令优先于默认Skill行为。
避免过度设计：仅更新需要变更的路由表。保持路由条目简洁且聚焦于匹配模式。不添加未要求的推测性模式或灵活性。严格生成/do所需的内容——不额外增加功能。
保留手动条目：检测并跳过do.md中的手写路由条目。绝不覆盖无
```
[AUTO-GENERATED]
```
标记的条目。
修改前备份：在进行任何变更前，始终为commands/do.md创建带时间戳的备份。验证失败时自动回滚。
Markdown语法验证：更新后验证表格语法，确保管道符对齐且标题分隔符正确。
确定性生成：相同的Skill/Agent元数据始终生成相同的路由条目。模式提取或表格格式化过程无随机性。

Default Behaviors (ON unless disabled)

默认行为（默认开启，可禁用）

Communication Style: Report facts without self-congratulation. Show diff of routing changes rather than describing them.
Temporary File Cleanup: Remove temporary metadata JSON files and diff files at completion. Keep only backups and updated do.md.
Interactive Confirmation: Show diff and ask for confirmation before updating do.md (unless --auto-commit flag provided).
Progress Reporting: Stream updates as scanning, extracting, generating, and updating phases execute.
Conflict Detection: Warn when multiple routes match the same pattern with suggestions for resolution.
Alphabetical Ordering: Maintain alphabetical order within routing tables.

沟通风格：仅报告事实，不进行自我夸赞。展示路由变更的diff而非描述变更内容。
临时文件清理：完成后删除临时元数据JSON文件和diff文件。仅保留备份文件和更新后的do.md。
交互式确认：更新do.md前展示diff并请求确认（除非提供--auto-commit参数）。
进度报告：在扫描、提取、生成、更新阶段执行时实时输出进度。
冲突检测：当多个路由匹配同一模式时发出警告，并提供解决建议。
字母排序：在路由表内保持条目按字母顺序排列。

Optional Behaviors (OFF unless enabled)

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

Auto-Commit Mode:
```
--auto-commit
```
flag to skip confirmation and automatically commit changes.
Dry-Run Mode:
```
--dry-run
```
to show changes without modifying do.md.
Verbose Debug:
```
--verbose
```
for detailed parsing and generation logs.

自动提交模式：使用
```
--auto-commit
```
参数跳过确认步骤，自动提交变更。
试运行模式：使用
```
--dry-run
```
参数展示变更但不修改do.md。
详细调试：使用
```
--verbose
```
参数获取详细的解析和生成日志。

What This Skill CAN Do

该Skill可执行的操作

Scan all skills (skills//SKILL.md) and agents (agents/.md) for metadata
Extract YAML frontmatter (name, description, version) and trigger patterns
Generate routing table entries following /do format specification
Detect routing conflicts (same trigger mapped to multiple routes)
Safely update commands/do.md with atomic backup/restore
Update command files (commands/*.md) with skill/agent references
Preserve all hand-written manual routing entries
Validate markdown table syntax after updates
Batch mode: Process N skills at once from a Pipeline Spec or component list (used by pipeline-scaffolder Phase 4)
INDEX.json updates: Add/update agent entries in
```
agents/INDEX.json
```
alongside routing tables

扫描所有Skill（skills//SKILL.md）和Agent（agents/.md）以获取元数据
提取YAML前置元数据（名称、描述、版本）和触发模式
按照/do格式规范生成路由表条目
检测路由冲突（同一触发词映射到多个路由）
通过原子备份/恢复机制安全更新commands/do.md
更新命令文件（commands/*.md）中的Skill/Agent引用
保留所有手写的手动路由条目
更新后验证Markdown表格语法
批量模式：从流水线规范或组件列表中一次性处理N个Skill（用于pipeline-scaffolder第4阶段）
INDEX.json更新：在更新路由表的同时，将Agent条目添加/更新到
```
agents/INDEX.json
```

What This Skill CANNOT Do

该Skill不可执行的操作

Infer trigger patterns from vague descriptions (requires explicit phrases)
Create new routing table sections (only updates existing tables)
Resolve high-severity conflicts automatically (requires manual priority decisions)
Modify skill/agent metadata (read-only access to capabilities)
Handle non-standard markdown table formats

从模糊描述中推断触发模式（需要明确的短语）
创建新的路由表章节（仅更新现有表格）
自动解决高严重性冲突（需要手动优先级决策）
修改Skill/Agent元数据（仅具备读取权限）
处理非标准Markdown表格格式

Prerequisites

前置条件

Must be in agents repository root (has commands/do.md)
Skills must have valid YAML frontmatter in SKILL.md files
Agents must have valid YAML frontmatter in agents/*.md files
commands/do.md must have routing table sections with standard headers

必须处于Agent仓库根目录（包含commands/do.md）
Skill的SKILL.md文件中必须包含有效的YAML前置元数据
Agent的agents/*.md文件中必须包含有效的YAML前置元数据
commands/do.md必须包含带标准标题的路由表章节

Instructions

操作步骤

Phase 1: SCAN -- Discover All Skills and Agents

阶段1：扫描——发现所有Skill和Agent

Goal: Find every skill and agent file in the repository.

Step 1: Run scan script

bash

python3 ~/.claude/skills/routing-table-updater/scripts/scan.py --repo $HOME/claude-code-toolkit

Step 2: Validate scan output

Expected output is JSON with:

```
skills_found
```
: count of discovered skill files
```
agents_found
```
: count of discovered agent files
```
skills
```
: array of paths to skills/*/SKILL.md
```
agents
```
: array of paths to agents/*.md

Step 3: Check for gaps

Compare discovered count against expected. If skills or agents are missing, check:

Directory naming (must be skills/*/SKILL.md format)
Agent file naming (must be agents/*.md format)
File permissions

Gate: All skill directories and agent files discovered with no permission errors. Do NOT proceed to Phase 2 until gate passes.

If gate fails:

"Repository not found": Verify --repo path points to agents directory
"No skills found": Check skills/ directory exists and has subdirectories
"Permission denied": Verify file read permissions

目标：找到仓库中的所有Skill和Agent文件。

步骤1：运行扫描脚本

bash

python3 ~/.claude/skills/routing-table-updater/scripts/scan.py --repo $HOME/claude-code-toolkit

步骤2：验证扫描输出

预期输出为JSON格式，包含：

```
skills_found
```
：发现的Skill文件数量
```
agents_found
```
：发现的Agent文件数量
```
skills
```
：skills/*/SKILL.md的路径数组
```
agents
```
：agents/*.md的路径数组

步骤3：检查遗漏

将发现的数量与预期值对比。若存在Skill或Agent遗漏，检查：

目录命名格式（必须为skills/*/SKILL.md）
Agent文件命名格式（必须为agents/*.md）
文件权限

门控条件：所有Skill目录和Agent文件均被发现，无权限错误。在门控条件满足前，请勿进入阶段2。

若门控失败：

"Repository not found"：验证--repo路径指向Agent目录
"No skills found"：检查skills/目录是否存在且包含子目录
"Permission denied"：验证文件读取权限

Phase 2: EXTRACT -- Parse Metadata

阶段2：提取——解析元数据

Goal: Extract YAML frontmatter, trigger patterns, complexity, and routing table targets from every discovered file.

Step 1: Run extraction script

bash

python3 ~/.claude/skills/routing-table-updater/scripts/extract_metadata.py --input scan_results.json --output metadata.json

Step 2: Verify extraction completeness

For each capability, confirm these fields were extracted:

```
name
```
: Matches YAML frontmatter name field
```
description
```
: Full description text
```
version
```
: Semantic version string
```
trigger_patterns
```
(skills): Array of quoted phrases from description
```
domain_keywords
```
(agents): Array of technology/domain terms
```
complexity
```
: Inferred level (Simple, Medium, Complex)
```
routing_table
```
: Target table (Intent Detection, Task Type, Domain-Specific, or Combination)

Step 3: Validate trigger pattern quality

Review extracted patterns against

references/extraction-patterns.md

. Patterns should be:

Specific enough to avoid false matches
Broad enough to catch common phrasings
Free of generic terms that match too many routes

Gate: All YAML parsed successfully, required fields present (name, description, version), trigger patterns extracted for skills, domain keywords extracted for agents. Do NOT proceed to Phase 3 until gate passes.

If gate fails:

"Invalid YAML in {file}": Fix YAML frontmatter in the skill/agent file
"Missing description field": Add description to YAML frontmatter
"No trigger patterns found": Update description to include clear trigger phrases

目标：从所有发现的文件中提取YAML前置元数据、触发模式、复杂度和路由表目标。

步骤1：运行提取脚本

bash

python3 ~/.claude/skills/routing-table-updater/scripts/extract_metadata.py --input scan_results.json --output metadata.json

步骤2：验证提取完整性

对于每个功能，确认已提取以下字段：

```
name
```
：与YAML前置元数据中的name字段匹配
```
description
```
：完整描述文本
```
version
```
：语义化版本字符串
```
trigger_patterns
```
（Skill）：从描述中提取的带引号短语数组
```
domain_keywords
```
（Agent）：技术/领域术语数组
```
complexity
```
：推断的复杂度等级（Simple、Medium、Complex）
```
routing_table
```
：目标路由表（Intent Detection、Task Type、Domain-Specific或Combination）

步骤3：验证触发模式质量

对照

references/extraction-patterns.md

检查提取的模式。模式应满足：

足够具体以避免误匹配
足够宽泛以覆盖常见表述
不包含会匹配过多路由的通用术语

门控条件：所有YAML解析成功，必填字段（名称、描述、版本）存在，已提取Skill的触发模式和Agent的领域关键词。在门控条件满足前，请勿进入阶段3。

若门控失败：

"Invalid YAML in {file}"：修复Skill/Agent文件中的YAML前置元数据
"Missing description field"：在YAML前置元数据中添加描述
"No trigger patterns found"：更新描述以包含明确的触发短语

Phase 3: GENERATE -- Create Routing Table Entries

阶段3：生成——创建路由表条目

Goal: Map extracted metadata to routing entries and detect conflicts.

bash

python3 ~/.claude/skills/routing-table-updater/scripts/generate_routes.py --input metadata.json --output routing_entries.json

Generation process:

Load routing format specification from
```
references/routing-format.md
```
Map each capability to appropriate routing table
Format entries according to /do table structure
Detect pattern conflicts (see
```
references/conflict-resolution.md
```
)
Sort entries alphabetically within tables

Gate: All capabilities mapped to entries, entries follow /do format, conflicts detected and documented, no duplicates within same table. Do NOT proceed to Phase 4 until gate passes.

If gate fails:

"Unknown routing table target": Update routing table mapping logic
"High-severity conflict": Review conflicting patterns manually before proceeding

目标：将提取的元数据映射为路由条目并检测冲突。

bash

python3 ~/.claude/skills/routing-table-updater/scripts/generate_routes.py --input metadata.json --output routing_entries.json

生成流程：

从
```
references/routing-format.md
```
加载路由格式规范
将每个功能映射到对应的路由表
按照/do表格结构格式化条目
检测模式冲突（参见
```
references/conflict-resolution.md
```
）
在表格内按字母顺序排序条目

门控条件：所有功能均已映射为条目，条目符合/do格式，冲突已被检测并记录，同一表格内无重复条目。在门控条件满足前，请勿进入阶段4。

若门控失败：

"Unknown routing table target"：更新路由表映射逻辑
"High-severity conflict"：在继续前手动检查冲突模式

Phase 4A: UPDATE -- Safely Modify commands/do.md

阶段4A：更新——安全修改commands/do.md

Goal: Apply generated routing entries to do.md with backup and validation.

Step 1: Run update script with backup

bash

python3 ~/.claude/skills/routing-table-updater/scripts/update_routing.py --input routing_entries.json --target $HOME/claude-code-toolkit/commands/do.md --backup

Step 2: Verify backup exists

Confirm backup file at

commands/.do.md.backup.{timestamp}

before any modifications proceed.

Step 3: Review the diff

The script outputs a diff showing:

New entries being added (prefixed with +)
Modified entries being updated (old with -, new with +)
Manual entries being preserved (unchanged)

Review the diff for correctness. Count of preserved manual entries should match expectations.

Step 4: Confirm or abort

If diff looks correct: confirm to apply
If diff shows unexpected changes: abort and investigate
If using --auto-commit: confirmation is skipped

Step 5: Post-update validation

After writing, the script validates:

Pipe alignment in all tables
Header separator rows present
Consistent column counts per table
No orphaned rows

On validation failure: automatic restore from backup. Report error details.

Gate: Backup created, all manual entries preserved, markdown validated, diff confirmed. If gate fails, RESTORE from backup.

目标：通过备份和验证机制将生成的路由条目应用到do.md。

步骤1：带备份运行更新脚本

bash

python3 ~/.claude/skills/routing-table-updater/scripts/update_routing.py --input routing_entries.json --target $HOME/claude-code-toolkit/commands/do.md --backup

步骤2：验证备份存在

在进行任何修改前，确认

commands/.do.md.backup.{timestamp}

备份文件已生成。

步骤3：查看差异

脚本会输出差异信息，展示：

新增的条目（前缀为+）
被更新的条目（旧条目前缀为-，新条目前缀为+）
被保留的手动条目（无变更）

检查差异是否正确。被保留的手动条目数量应与预期一致。

步骤4：确认或终止

若差异正确：确认应用变更
若差异包含意外变更：终止操作并调查原因
若使用--auto-commit参数：跳过确认步骤

步骤5：更新后验证

写入完成后，脚本会验证：

所有表格中的管道符对齐
存在标题分隔行
每个表格的列数一致
无孤立行

若验证失败：自动从备份恢复，并报告错误详情。

门控条件：已创建备份，所有手动条目被保留，Markdown验证通过，差异已确认。若门控失败，从备份恢复。

Phase 4B: UPDATE -- Update Command Files

阶段4B：更新——更新命令文件

Goal: Update command files with current skill/agent references.

bash

python3 ~/.claude/skills/routing-table-updater/scripts/update_commands.py --commands-dir $HOME/claude-code-toolkit/commands --metadata metadata.json --backup

Update process:

Scan command files for skill invocations and references
Identify outdated or invalid references (renamed/removed skills)
Update references to match current metadata
Create backups for all modified command files
Validate updated markdown syntax

Gate: Backups created for all modified files, all referenced skills exist, markdown validated.

目标：更新命令文件中的当前Skill/Agent引用。

bash

python3 ~/.claude/skills/routing-table-updater/scripts/update_commands.py --commands-dir $HOME/claude-code-toolkit/commands --metadata metadata.json --backup

更新流程：

扫描命令文件中的Skill调用和引用
识别过时或无效的引用（已重命名/删除的Skill）
更新引用以匹配当前元数据
为所有修改的命令文件创建备份
验证更新后的Markdown语法

门控条件：已为所有修改的文件创建备份，所有引用的Skill均存在，Markdown验证通过。

Phase 5: VERIFY -- Validate Routing Correctness

阶段5：验证——确认路由正确性

Goal: Final validation of all routing tables.

bash

python3 ~/.claude/skills/routing-table-updater/scripts/validate.py --target $HOME/claude-code-toolkit/commands/do.md

Verification checks:

Structural: All routing tables present, headers formatted, pipes aligned
Content: All auto-generated entries marked, no duplicates, all referenced skills/agents exist
Conflicts: Overlapping patterns documented, priority rules applied
Integration: Sample pattern matching tests pass

Gate: All checks pass. Task complete ONLY if final gate passes.

If gate fails:

"Duplicate pattern detected": Remove duplicate from do.md
"Missing skill/agent file": Remove routing entry or create missing capability
"Invalid complexity level": Fix complexity value in routing entry

目标：对所有路由表进行最终验证。

bash

python3 ~/.claude/skills/routing-table-updater/scripts/validate.py --target $HOME/claude-code-toolkit/commands/do.md

验证检查项：

结构验证：所有路由表存在，标题格式正确，管道符对齐
内容验证：所有自动生成条目已标记，无重复条目，所有引用的Skill/Agent均存在
冲突验证：重叠模式已记录，优先级规则已应用
集成验证：示例模式匹配测试通过

门控条件：所有检查通过。仅当最终门控通过时，任务才算完成。

若门控失败：

"Duplicate pattern detected"：从do.md中移除重复条目
"Missing skill/agent file"：移除路由条目或创建缺失的功能
"Invalid complexity level"：修复路由条目中的复杂度值

Examples

示例

Example 1: New Skill Created

示例1：创建新Skill

User creates

skills/api-integration-helper/SKILL.md

via skill-creator-engineer:

yaml

---
name: api-integration-helper
description: Test API integrations with mock responses and validation. Use when "test API", "API integration", or "mock API".
version: 1.0.0
---

Actions:

SCAN: Detect new file in skills/ directory
EXTRACT: Parse frontmatter, extract trigger patterns ["test API", "API integration", "mock API"], complexity Medium
GENERATE: Create entry for Intent Detection Patterns table
UPDATE: Backup do.md, insert entry alphabetically, validate markdown
VERIFY: Run validate.py, confirm no conflicts, all tables intact

Generated routing entry:

| "test API", "API integration", "mock API" | api-integration-helper skill | Medium | [AUTO-GENERATED]

Result: New skill is discoverable via /do command

用户通过skill-creator-engineer创建了

skills/api-integration-helper/SKILL.md

：

yaml

---
name: api-integration-helper
description: Test API integrations with mock responses and validation. Use when "test API", "API integration", or "mock API".
version: 1.0.0
---

操作流程：

扫描：在skills/目录中发现新文件
提取：解析前置元数据，提取触发模式["test API", "API integration", "mock API"]，复杂度为Medium
生成：为Intent Detection Patterns表创建条目
更新：备份do.md，按字母顺序插入条目，验证Markdown
验证：运行validate.py，确认无冲突，所有表格完整

生成的路由条目：

| "test API", "API integration", "mock API" | api-integration-helper skill | Medium | [AUTO-GENERATED]

结果：新Skill可通过/do命令被调用

Example 2: Agent Description Updated

示例2：更新Agent描述

User updates golang-general-engineer description to add "concurrency" keyword.

Actions:

SCAN: Find modified agents/golang-general-engineer.md
EXTRACT: Parse updated domain keywords ["Go", "Golang", "gofmt", "Go concurrency"]
GENERATE: Update Domain-Specific routing entry with new keywords
UPDATE: Backup, replace existing auto-generated entry, preserve manual entries
VERIFY: Confirm no new conflicts, all references valid

Updated routing entry:

diff

-| Go, Golang, gofmt | golang-general-engineer | Medium-Complex | [AUTO-GENERATED]
+| Go, Golang, gofmt, Go concurrency | golang-general-engineer | Medium-Complex | [AUTO-GENERATED]

Result: Domain routing expanded to cover new keyword

用户更新了golang-general-engineer的描述，添加了"concurrency"关键词。

操作流程：

扫描：找到已修改的agents/golang-general-engineer.md
提取：解析更新后的领域关键词["Go", "Golang", "gofmt", "Go concurrency"]
生成：更新Domain-Specific路由条目以包含新关键词
更新：备份，替换现有的自动生成条目，保留手动条目
验证：确认无新冲突，所有引用有效

更新后的路由条目：

diff

-| Go, Golang, gofmt | golang-general-engineer | Medium-Complex | [AUTO-GENERATED]
+| Go, Golang, gofmt, Go concurrency | golang-general-engineer | Medium-Complex | [AUTO-GENERATED]

结果：领域路由已扩展，可覆盖新关键词

Example 3: Conflict Detection

示例3：冲突检测

Two skills both match "test API" pattern.

Actions:

GENERATE phase detects overlap between api-testing-skill and integration-testing-skill
Conflict logged with severity assessment (low: both routes reasonable)
Resolution: longer pattern "test API integration" takes precedence for integration skill
Document conflict in output, apply specificity rule

Resolution applied:

| "test API integration" | integration-testing-skill | Medium | [AUTO-GENERATED]
| "test API" | api-testing-skill | Medium | [AUTO-GENERATED]

Result: Unambiguous routing with longest-match precedence

两个Skill均匹配"test API"模式。

操作流程：

生成阶段检测到api-testing-skill和integration-testing-skill之间的重叠
记录冲突并评估严重性（低：两个路由均合理）
解决方案：更长的模式"test API integration"优先分配给集成Skill
在输出中记录冲突，应用特异性规则

应用的解决方案：

| "test API integration" | integration-testing-skill | Medium | [AUTO-GENERATED]
| "test API" | api-testing-skill | Medium | [AUTO-GENERATED]

结果：通过最长匹配优先级实现无歧义路由

Example 4: Manual Entry Preserved

示例4：保留手动条目

Existing do.md has a hand-curated combination entry (no AUTO-GENERATED marker):

| "review Python", "Python quality" | python-general-engineer + python-quality-gate | Medium |

Auto-generation produces a simpler entry for "review Python". Because the existing entry lacks the

[AUTO-GENERATED]

marker, it is preserved as-is. The auto-generated entry is skipped for this pattern.

Result: Manual curation respected, no data loss

现有do.md包含一个手动整理的组合条目（无AUTO-GENERATED标记）：

| "review Python", "Python quality" | python-general-engineer + python-quality-gate | Medium |

自动生成过程为"review Python"生成了一个更简单的条目。由于现有条目无

[AUTO-GENERATED]

标记，会被原样保留，自动生成的条目会被跳过。

结果：手动整理的内容被尊重，无数据丢失

Batch Mode

批量模式

When invoked by

pipeline-scaffolder

Phase 4 (INTEGRATE), this skill operates in batch mode to register N skills and 0-1 agents in a single pass.

当被

pipeline-scaffolder

第4阶段（集成阶段）调用时，该Skill会以批量模式运行，一次性注册N个Skill和0-1个Agent。

Batch Input

批量输入

The scaffolder provides a component list (from the Pipeline Spec):

json

{
  "domain": "prometheus",
  "agent": { "name": "prometheus-grafana-engineer", "is_new": false },
  "skills": [
    { "name": "prometheus-metrics", "triggers": ["prometheus metrics", "PromQL", "recording rules"], "agent": "prometheus-grafana-engineer" },
    { "name": "prometheus-alerting", "triggers": ["prometheus alerting", "alert rules", "alertmanager"], "agent": "prometheus-grafana-engineer" },
    { "name": "prometheus-operations", "triggers": ["prometheus operations", "prometheus troubleshooting"], "agent": "prometheus-grafana-engineer" }
  ]
}

脚手架工具会提供一个组件列表（来自流水线规范）：

json

{
  "domain": "prometheus",
  "agent": { "name": "prometheus-grafana-engineer", "is_new": false },
  "skills": [
    { "name": "prometheus-metrics", "triggers": ["prometheus metrics", "PromQL", "recording rules"], "agent": "prometheus-grafana-engineer" },
    { "name": "prometheus-alerting", "triggers": ["prometheus alerting", "alert rules", "alertmanager"], "agent": "prometheus-grafana-engineer" },
    { "name": "prometheus-operations", "triggers": ["prometheus operations", "prometheus troubleshooting"], "agent": "prometheus-grafana-engineer" }
  ]
}

Batch Process

批量流程

SCAN: Skip full repo scan — use the provided component list directly
EXTRACT: Read YAML frontmatter from each listed skill file (verify they exist)
GENERATE: Create routing entries for ALL N skills in one pass. Check for inter-batch conflicts (skills within the same batch that share triggers).
UPDATE:
- Add all N routing entries to
```
skills/do/references/routing-tables.md
```
  in one write
- If agent is new (
```
is_new: true
```
  ), add to
```
agents/INDEX.json
```
- Update
```
skills/do/SKILL.md
```
  if force-route triggers are needed
- Create
```
commands/{domain}-pipeline.md
```
  manifest
VERIFY: Validate all N entries are present and correctly formatted

扫描：跳过全仓库扫描——直接使用提供的组件列表
提取：读取每个列出的Skill文件的YAML前置元数据（验证其存在）
生成：一次性为所有N个Skill创建路由条目。检查批量内部的冲突（同一批量内Skill共享触发词的情况）。
更新：
- 一次性将所有N个路由条目写入
```
skills/do/references/routing-tables.md
```
- 若Agent是新的（
```
is_new: true
```
  ），将其添加到
```
agents/INDEX.json
```
- 若需要强制路由触发词，更新
```
skills/do/SKILL.md
```
- 创建
```
commands/{domain}-pipeline.md
```
  清单
验证：验证所有N个条目均存在且格式正确

Batch vs Single Mode

批量模式与单条模式对比

Aspect	Single Mode	Batch Mode
Input	Full repo scan	Component list from Pipeline Spec
Scan	All skills/* and agents/*	Only listed components
Conflict check	Against existing entries	Against existing AND within batch
OUTPUT	One entry at a time	N entries in one pass
Invoked by	skill-creator-engineer, agent-creator-engineer	pipeline-scaffolder Phase 4

维度	单条模式	批量模式
输入	全仓库扫描	来自流水线规范的组件列表
扫描范围	所有skills/和agents/	仅列出的组件
冲突检查	与现有条目对比	与现有条目及批量内部条目对比
输出	一次一条目	一次性输出N个条目
调用者	skill-creator-engineer、agent-creator-engineer	pipeline-scaffolder第4阶段

Integration

集成方式

This skill is typically invoked after other creation skills complete:

After skill-creator-engineer: New skill created, routing tables need updated entry
After agent-creator-engineer: New agent created, domain routing needs expansion
After skill/agent modification: Description or trigger changes require routing refresh
During repository maintenance: Periodic sync to catch manual drift
After pipeline-scaffolder Phase 3: N skills created for a domain, all need routing (batch mode)

Invocation by other skills:

skill: routing-table-updater

The skill reads metadata from all skills and agents but never modifies them. It only writes to

skills/do/SKILL.md

skills/do/references/routing-tables.md

agents/INDEX.json

, and

commands/*.md

files.

该Skill通常在其他创建类Skill完成后被调用：

skill-creator-engineer之后：新Skill已创建，路由表需要添加新条目
agent-creator-engineer之后：新Agent已创建，领域路由需要扩展
Skill/Agent修改之后：描述或触发词变更需要刷新路由
仓库维护期间：定期同步以捕获手动变更
pipeline-scaffolder第3阶段之后：为某个领域创建了N个Skill，所有都需要注册路由（批量模式）

被其他Skill调用的方式：

skill: routing-table-updater

该Skill会读取所有Skill和Agent的元数据，但绝不会修改它们。它仅会写入

skills/do/SKILL.md

、

skills/do/references/routing-tables.md

、

agents/INDEX.json

和

commands/*.md

文件。

Error Handling

错误处理

Error: "YAML Parse Error in {file}"

错误："YAML Parse Error in {file}"

Cause: Malformed YAML frontmatter in skill/agent file Solution: Fix YAML syntax (missing colons, bad indentation, unquoted special characters), re-run extraction

原因：Skill/Agent文件中的YAML前置元数据格式错误解决方案：修复YAML语法（缺失冒号、缩进错误、特殊字符未加引号），重新运行提取脚本

Error: "Routing Conflict -- High Severity"

错误："Routing Conflict -- High Severity"

Cause: Same trigger phrase maps to incompatible routes (e.g., "deploy" to both Docker and Kubernetes) Solution: Add domain context to patterns ("deploy Docker" vs "deploy K8s"), update skill descriptions, document resolution in

references/conflict-resolution.md

原因：同一触发短语映射到不兼容的路由（例如，"deploy"同时映射到Docker和Kubernetes）解决方案：为模式添加领域上下文（"deploy Docker" vs "deploy K8s"），更新Skill描述，在

references/conflict-resolution.md

中记录解决方案

Error: "Manual Entry Overwrite Detected"

错误："Manual Entry Overwrite Detected"

Cause: Bug in manual entry detection logic Solution: CRITICAL -- DO NOT PROCEED. Restore from backup immediately. Report detection regex issue.

原因：手动条目检测逻辑存在Bug 解决方案：严重问题——请勿继续。立即从备份恢复，报告检测正则表达式的问题。

Error: "Markdown Table Validation Failed"

错误："Markdown Table Validation Failed"

Cause: Generated table has misaligned pipes, missing headers, or inconsistent column counts Solution: Restore from backup, fix table generation logic, re-run. Do not commit broken markdown.

原因：生成的表格存在管道符对齐错误、缺失标题或列数不一致解决方案：从备份恢复，修复表格生成逻辑，重新运行。请勿提交损坏的Markdown。

Anti-Patterns

反模式

Anti-Pattern 1: Fixing Without Backup

反模式1：无备份修复

What it looks like: Running update_routing.py with --no-backup Why wrong: No recovery path if manual entries are lost or markdown is corrupted Do instead: Always use --backup flag. Verify backup exists before proceeding.

表现：运行update_routing.py时使用--no-backup参数危害：如果手动条目丢失或Markdown损坏，无恢复途径 正确做法：始终使用--backup参数。在继续前验证备份存在。

Anti-Pattern 2: Skipping Phase Gates

反模式2：跳过阶段门控

What it looks like: Running UPDATE before EXTRACT completes Why wrong: Missing metadata produces empty or incorrect routing tables. Phase gates prevent incomplete data from corrupting do.md. Do instead: Verify each gate passes before proceeding. Follow SCAN -> EXTRACT -> GENERATE -> UPDATE -> VERIFY sequence.

表现：在提取阶段完成前运行更新操作危害：缺失的元数据会生成空的或错误的路由表。阶段门控可防止不完整数据损坏do.md。 正确做法：在继续前验证每个门控条件都已满足。遵循扫描→提取→生成→更新→验证的顺序。

Anti-Pattern 3: Ignoring Conflict Warnings

反模式3：忽略冲突警告

What it looks like: Proceeding with high-severity conflicts unresolved Why wrong: Ambiguous routing confuses /do command. Users get wrong tool for their context. Do instead: Review severity. High-severity conflicts MUST be resolved. Add domain context to make patterns specific.

表现：在未解决高严重性冲突的情况下继续操作危害：模糊的路由会让/do命令产生混淆。 正确做法：检查严重性等级。高严重性冲突必须被解决。为模式添加领域上下文以使其更具体。

Anti-Pattern 4: Overwriting Manual Entries

反模式4：覆盖手动条目

What it looks like: Replacing all matching rows without checking for AUTO-GENERATED marker Why wrong: Manual entries contain curated routing decisions and hand-tuned combinations Do instead: Only update rows with

[AUTO-GENERATED]

marker. Preserve everything else.

表现：替换所有匹配的行而不检查AUTO-GENERATED标记危害：手动条目包含精心整理路由决策 正确做法：仅更新带有

[AUTO-GENERATED]

标记的行。保留所有其他条目。

References

参考资料

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations
Verification Checklist - Pre-completion checks
Gate Enforcement - Phase transition rules

该Skill使用以下共享模式：

Anti-Rationalization - 防止捷径式合理化
Verification Checklist - 完成前检查清单
Gate Enforcement - 阶段转换规则

Domain-Specific Anti-Rationalization

领域特定反合理化

Rationalization	Why It's Wrong	Required Action
"Routes look correct, no need to validate"	Visual inspection misses duplicate patterns and conflicts	Run validate.py against updated do.md
"Small routing change, skip backup"	One corrupt table makes /do unusable	Always create backup before modification
"Manual entries are outdated, replace them"	Manual entries contain intentional curation	Preserve all non-AUTO-GENERATED entries
"Conflict is low severity, ignore it"	Low severity today becomes user confusion tomorrow	Document all conflicts with resolution strategy

合理化借口	错误原因	必要操作
"路由看起来正确，无需验证"	视觉检查会遗漏重复模式和冲突	针对更新后的do.md运行validate.py
"路由变更很小，跳过备份"	一个损坏的表格会导致/do命令无法使用	修改前始终创建备份
"手动条目已过时，替换它们"	手动条目包含有意的整理内容	保留所有非AUTO-GENERATED条目
"冲突严重性低，可以忽略"	今天的低严重性问题明天会变成用户困惑	记录所有冲突及解决策略

Reference Files

参考文件

```
${CLAUDE_SKILL_DIR}/references/routing-format.md
```
: /do routing table format specification (table structure, entry formats, ordering rules)
```
${CLAUDE_SKILL_DIR}/references/extraction-patterns.md
```
: Trigger phrase extraction patterns (regex, keyword maps, complexity inference)
```
${CLAUDE_SKILL_DIR}/references/conflict-resolution.md
```
: Conflict types, priority rules, severity levels, resolution process
```
${CLAUDE_SKILL_DIR}/references/examples.md
```
: Real-world examples of routing table updates (new skill, updated agent, conflict detection, manual preservation)

```
${CLAUDE_SKILL_DIR}/references/routing-format.md
```
: /do路由表格式规范（表格结构、条目格式、排序规则）
```
${CLAUDE_SKILL_DIR}/references/extraction-patterns.md
```
: 触发短语提取模式（正则表达式、关键词映射、复杂度推断）
```
${CLAUDE_SKILL_DIR}/references/conflict-resolution.md
```
: 冲突类型、优先级规则、严重性等级、解决流程
```
${CLAUDE_SKILL_DIR}/references/examples.md
```
: 路由表更新的真实场景示例（新Skill、更新Agent、冲突检测、手动条目保留）