⚡

Neovim实现技能Skill skill-neovim-implementation

这个技能用于自动实现Neovim配置更改，包括输入验证、状态更新、调用子代理、处理后期操作如状态更新、工件链接和git提交。关键词：Neovim, 实现, 配置, 技能, 自动化, 开发工具。

其他 0 次安装 0 次浏览 更新于 3/22/2026

name: Neovim实现技能 description: 根据计划实现Neovim配置更改。用于Neovim实现任务。 allowed-tools: Task, Bash, Edit, Read, Write

Neovim实现技能

薄包装层，将Neovim实现委托给 neovim-implementation-agent 子代理。

重要：此技能实现技能内部后期操作模式。在子代理返回后，此技能处理所有后期操作（状态更新、工件链接、git提交）然后返回。

上下文引用

参考（不要提前加载）：

  • 路径：.claude/context/core/formats/return-metadata-file.md - 元数据文件模式
  • 路径：.claude/context/core/patterns/postflight-control.md - 标记文件协议
  • 路径：.claude/context/core/patterns/jq-escaping-workarounds.md - jq转义模式

触发条件

此技能在以下情况激活：

  • 任务语言为“neovim”
  • 任务存在实现计划
  • 需要应用Neovim配置更改

执行流程

阶段1：输入验证

验证必需输入：

  • task_number - 必须提供并存在于state.json中
  • plan_path - 实现计划必须存在
# 查找任务
task_data=$(jq -r --argjson num "$task_number" \
  '.active_projects[] | select(.project_number == $num)' \
  specs/state.json)

# 验证存在
if [ -z "$task_data" ]; then
  return error "任务 $task_number 未找到"
fi

# 提取字段
language=$(echo "$task_data" | jq -r '.language // "neovim"')
status=$(echo "$task_data" | jq -r '.status')
project_name=$(echo "$task_data" | jq -r '.project_name')

# 查找计划文件（使用填充目录号）
padded_num=$(printf "%03d" "$task_number")
plan_path="specs/${padded_num}_${project_name}/plans/implementation-001.md"
if [ ! -f "$plan_path" ]; then
  return error "计划未找到：$plan_path"
fi

阶段2：预飞状态更新

在调用子代理之前更新任务状态为“implementing”。

更新state.json：

jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   --arg status "implementing" \
   --arg sid "$session_id" \
  '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
    status: $status,
    last_updated: $ts,
    session_id: $sid
  }' specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json

更新TODO.md：使用Edit工具将状态标记更改为 [IMPLEMENTING]。

更新计划文件（如果存在）：更新计划元数据中的Status字段：

# 查找最新计划文件
plan_file=$(ls -1 "specs/${padded_num}_${project_name}/plans/implementation-"*.md 2>/dev/null | sort -V | tail -1)
if [ -n "$plan_file" ] && [ -f "$plan_file" ]; then
    # 先尝试项目符号模式，然后非项目符号模式
    sed -i 's/^\- \*\*Status\*\*: \[.*\]$/- **Status**: [IMPLEMENTING]/' "$plan_file"
    sed -i 's/^\*\*Status\*\*: \[.*\]$/**Status**: [IMPLEMENTING]/' "$plan_file"
fi

阶段3：创建后期操作标记

mkdir -p "specs/${padded_num}_${project_name}"

cat > "specs/${padded_num}_${project_name}/.postflight-pending" << EOF
{
  "session_id": "${session_id}",
  "skill": "skill-neovim-implementation",
  "task_number": ${task_number},
  "operation": "implement",
  "reason": "Postflight pending: status update, artifact linking, git commit",
  "created": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
}
EOF

阶段4：准备委托上下文

{
  "session_id": "sess_{timestamp}_{random}",
  "delegation_depth": 1,
  "delegation_path": ["orchestrator", "implement", "skill-neovim-implementation"],
  "timeout": 3600,
  "task_context": {
    "task_number": N,
    "task_name": "{project_name}",
    "description": "{description}",
    "language": "neovim"
  },
  "plan_path": "specs/{NNN}_{SLUG}/plans/implementation-001.md",
  "metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json"
}

阶段5：调用子代理

关键：必须使用 Task 工具来生成子代理。

Tool: Task (NOT Skill)
Parameters:
  - subagent_type: "neovim-implementation-agent"
  - prompt: [Include task_context, delegation_context, plan_path, metadata_file_path]
  - description: "Execute Neovim implementation for task {N}"

子代理将：

  • 读取和解析实现计划
  • 顺序执行阶段
  • 创建/修改Neovim配置文件
  • 使用nvim --headless验证更改
  • 创建实现摘要
  • 写入元数据文件
  • 返回简要文本摘要

阶段5a：验证子代理返回格式

重要：检查子代理是否意外地将JSON返回到控制台（v1模式）而不是写入文件（v2模式）。

如果子代理的文本返回解析为有效JSON，记录警告：

# 检查子代理返回是否看起来像JSON（以{开头且是有效JSON）
subagent_return="$SUBAGENT_TEXT_RETURN"
if echo "$subagent_return" | grep -q '^{' && echo "$subagent_return" | jq empty 2>/dev/null; then
    echo "WARNING: Subagent returned JSON to console instead of writing metadata file."
    echo "This indicates the agent may have outdated instructions (v1 pattern instead of v2)."
    echo "The skill will continue by reading the metadata file, but this should be fixed."
fi

此验证：

  • 不使操作失败（继续读取元数据文件）
  • 记录警告以调试
  • 指示子代理指令需要更新
  • 允许优雅处理混合v1/v2代理

阶段6：解析子代理返回

metadata_file="specs/${padded_num}_${project_name}/.return-meta.json"

if [ -f "$metadata_file" ] && jq empty "$metadata_file" 2>/dev/null; then
    status=$(jq -r '.status' "$metadata_file")
    phases_completed=$(jq -r '.metadata.phases_completed // 0' "$metadata_file")
    phases_total=$(jq -r '.metadata.phases_total // 0' "$metadata_file")

    # 提取completion_data字段（如果存在）
    completion_summary=$(jq -r '.completion_data.completion_summary // ""' "$metadata_file")
    roadmap_items=$(jq -c '.completion_data.roadmap_items // []' "$metadata_file")
else
    status="failed"
fi

阶段7：更新任务状态（后期操作）

如果状态为“implemented”，更新state.json和TODO.md。

更新state.json：

jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   --arg status "completed" \
  '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
    status: $status,
    last_updated: $ts,
    completed: $ts
  }' specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json

# 添加completion_summary（完成任务的始终必需）
if [ -n "$completion_summary" ]; then
    jq --arg summary "$completion_summary" \
      '(.active_projects[] | select(.project_number == '$task_number')).completion_summary = $summary' \
      specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json
fi

# 添加roadmap_items（如果存在且非空）
if [ "$roadmap_items" != "[]" ] && [ -n "$roadmap_items" ]; then
    jq --argjson items "$roadmap_items" \
      '(.active_projects[] | select(.project_number == '$task_number')).roadmap_items = $items' \
      specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json
fi

更新TODO.md：使用Edit工具将状态标记更改为 [COMPLETED]。

更新计划文件（如果存在）：更新Status字段为 [COMPLETED] 并验证：

plan_file=$(ls -1 "specs/${padded_num}_${project_name}/plans/implementation-"*.md 2>/dev/null | sort -V | tail -1)
if [ -n "$plan_file" ] && [ -f "$plan_file" ]; then
    # 先尝试项目符号模式，然后非项目符号模式
    sed -i 's/^\- \*\*Status\*\*: \[.*\]$/- **Status**: [COMPLETED]/' "$plan_file"
    sed -i 's/^\*\*Status\*\*: \[.*\]$/**Status**: [COMPLETED]/' "$plan_file"
    # 验证更新
    if grep -qE '^\*\*Status\*\*: \[COMPLETED\]|^\- \*\*Status\*\*: \[COMPLETED\]' "$plan_file"; then
        echo "计划文件状态更新为 [COMPLETED]"
    else
        echo "WARNING: 无法验证计划文件状态更新"
    fi
else
    echo "INFO: 未找到要更新的计划文件（文件：$plan_file）"
fi

如果状态为“partial”：

保持状态为“implementing”，但更新恢复点：

jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   --argjson phase "$phases_completed" \
  '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
    last_updated: $ts,
    resume_phase: ($phase + 1)
  }' specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json

TODO.md保持为 [IMPLEMENTING]。

更新计划文件（如果存在）：更新Status字段为 [PARTIAL] 并验证：

plan_file=$(ls -1 "specs/${padded_num}_${project_name}/plans/implementation-"*.md 2>/dev/null | sort -V | tail -1)
if [ -n "$plan_file" ] && [ -f "$plan_file" ]; then
    # 先尝试项目符号模式，然后非项目符号模式
    sed -i 's/^\- \*\*Status\*\*: \[.*\]$/- **Status**: [PARTIAL]/' "$plan_file"
    sed -i 's/^\*\*Status\*\*: \[.*\]$/**Status**: [PARTIAL]/' "$plan_file"
    # 验证更新
    if grep -qE '^\*\*Status\*\*: \[PARTIAL\]|^\- \*\*Status\*\*: \[PARTIAL\]' "$plan_file"; then
        echo "计划文件状态更新为 [PARTIAL]"
    else
        echo "WARNING: 无法验证计划文件状态更新"
    fi
else
    echo "INFO: 未找到要更新的计划文件（目录：specs/${padded_num}_${project_name}/plans/）"
fi

失败时：保持状态为“implementing”以便重试。不更新计划文件（保留为 [IMPLEMENTING] 以便重试）。

阶段8：链接工件

将实现工件添加到state.json。

阶段9：Git提交

git add -A
git commit -m "task ${task_number}: complete implementation

Session: ${session_id}

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

阶段10：清理

rm -f "specs/${padded_num}_${project_name}/.postflight-pending"
rm -f "specs/${padded_num}_${project_name}/.return-meta.json"

阶段11：返回简要摘要

任务 {N} 的实现完成：
- 执行了 {phases_completed}/{phases_total} 个阶段
- 创建/修改了Neovim配置文件
- 验证了启动和模块加载
- 创建了摘要位于 specs/{NNN}_{SLUG}/summaries/implementation-summary-{DATE}.md
- 状态更新为 [COMPLETED]
- 更改已提交

错误处理

计划未找到

如果实现计划不存在，返回错误。

验证失败

如果nvim --headless失败：

  1. 保持状态为“implementing”
  2. 将阶段标记为 [PARTIAL]
  3. 报告验证错误

Git提交失败

非阻塞：记录失败但继续。

返回格式

简要文本摘要（非JSON）。