skill-neovim-research

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Neovim Research Skill

Neovim研究技能

Thin wrapper that delegates Neovim research to

neovim-research-agent

subagent.

IMPORTANT: This skill implements the skill-internal postflight pattern. After the subagent returns, this skill handles all postflight operations (status update, artifact linking, git commit) before returning.

这是一个轻量封装，将Neovim研究任务委托给

neovim-research-agent

子代理。

重要提示：本技能实现了技能内部的postflight模式。子代理返回后，本技能会在返回前处理所有postflight操作（状态更新、工件关联、Git提交）。

Context References

上下文参考

Reference (do not load eagerly):

Path:

.opencode/context/core/formats/return-metadata-file.md

- Metadata file schema

Path:

.opencode/context/core/patterns/postflight-control.md

- Marker file protocol

Path:

.opencode/context/core/patterns/jq-escaping-workarounds.md

- jq escaping patterns

参考内容（请勿提前加载）：

路径：

.opencode/context/core/formats/return-metadata-file.md

- 元数据文件 schema

路径：

.opencode/context/core/patterns/postflight-control.md

- 标记文件协议

路径：

.opencode/context/core/patterns/jq-escaping-workarounds.md

- jq转义方案

Trigger Conditions

触发条件

This skill activates when:

Task language is "neovim"
Research is needed for Neovim configuration
Plugin documentation or patterns need to be gathered

当满足以下条件时，本技能激活：

任务语言为"neovim"
需要针对Neovim配置开展研究
需要收集插件文档或相关模式

Execution Flow

执行流程

Stage 1: Input Validation

阶段1：输入验证

Validate required inputs:

```
task_number
```
- Must be provided and exist in state.json
```
focus_prompt
```
- Optional focus for research direction

bash

undefined

验证必填输入项：

```
task_number
```
- 必须提供且存在于state.json中
```
focus_prompt
```
- 可选，用于指定研究方向

bash

undefined

Lookup task

task_data=$(jq -r --argjson num "$task_number"
'.active_projects[] | select(.project_number == $num)'
specs/state.json)

Validate exists

if [ -z "$task_data" ]; then return error "Task $task_number not found" fi

Extract fields

language=$(echo "$task_data" | jq -r '.language // "neovim"') status=$(echo "$task_data" | jq -r '.status') project_name=$(echo "$task_data" | jq -r '.project_name') description=$(echo "$task_data" | jq -r '.description // ""')

---

---

Stage 2: Preflight Status Update

阶段2：预飞行状态更新

Update task status to "researching" BEFORE invoking subagent.

Update state.json:

bash

jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   --arg status "researching" \
   --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

Update TODO.md: Use Edit tool to change status marker to

[RESEARCHING]

在调用子代理之前，将任务状态更新为"researching"。

更新state.json：

bash

jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   --arg status "researching" \
   --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：使用编辑工具将状态标记改为

[RESEARCHING]

。

Stage 3: Create Postflight Marker

阶段3：创建飞行后标记

bash

padded_num=$(printf "%03d" "$task_number")
mkdir -p "specs/${padded_num}_${project_name}"

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

bash

padded_num=$(printf "%03d" "$task_number")
mkdir -p "specs/${padded_num}_${project_name}"

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

Stage 4: Prepare Delegation Context

阶段4：准备委托上下文

json

{
  "session_id": "sess_{timestamp}_{random}",
  "delegation_depth": 1,
  "delegation_path": ["orchestrator", "research", "skill-neovim-research"],
  "timeout": 3600,
  "task_context": {
    "task_number": N,
    "task_name": "{project_name}",
    "description": "{description}",
    "language": "neovim"
  },
  "focus_prompt": "{optional focus}",
  "metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json"
}

json

{
  "session_id": "sess_{timestamp}_{random}",
  "delegation_depth": 1,
  "delegation_path": ["orchestrator", "research", "skill-neovim-research"],
  "timeout": 3600,
  "task_context": {
    "task_number": N,
    "task_name": "{project_name}",
    "description": "{description}",
    "language": "neovim"
  },
  "focus_prompt": "{optional focus}",
  "metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json"
}

Stage 5: Invoke Subagent

阶段5：调用子代理

CRITICAL: You MUST use the Task tool to spawn the subagent.

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

The subagent will:

Search local Neovim configuration
Search web for plugin documentation
Analyze findings and synthesize recommendations
Create research report
Write metadata file
Return brief text summary

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

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

子代理将执行以下操作：

搜索本地Neovim配置
联网搜索插件文档
分析研究结果并生成建议
创建研究报告
编写元数据文件
返回简短文本摘要

Stage 6: Parse Subagent Return

阶段6：解析子代理返回结果

bash

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")
    artifact_path=$(jq -r '.artifacts[0].path // ""' "$metadata_file")
    artifact_type=$(jq -r '.artifacts[0].type // ""' "$metadata_file")
    artifact_summary=$(jq -r '.artifacts[0].summary // ""' "$metadata_file")
else
    status="failed"
fi

bash

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")
    artifact_path=$(jq -r '.artifacts[0].path // ""' "$metadata_file")
    artifact_type=$(jq -r '.artifacts[0].type // ""' "$metadata_file")
    artifact_summary=$(jq -r '.artifacts[0].summary // ""' "$metadata_file")
else
    status="failed"
fi

Stage 7: Update Task Status (Postflight)

阶段7：更新任务状态（飞行后）

If status is "researched", update state.json and TODO.md.

如果状态为"researched"，则更新state.json和TODO.md。

Stage 8: Link Artifacts

阶段8：关联工件

Add artifact to state.json with summary.

Update TODO.md: Add research artifact link.

Strip specs/ prefix for TODO.md (TODO.md is inside specs/):

todo_link_path="${artifact_path#specs/}"

markdown

- **Research**: [research-{NNN}.md]({todo_link_path})

将工件添加到state.json并附带摘要。

更新TODO.md：添加研究工件链接。

移除specs/前缀以适配TODO.md（TODO.md位于specs/目录内）：

todo_link_path="${artifact_path#specs/}"

markdown

- **Research**: [research-{NNN}.md]({todo_link_path})

Stage 9: Git Commit

阶段9：Git提交

bash

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

Session: ${session_id}

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

bash

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

Session: ${session_id}

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

Stage 10: Cleanup

阶段10：清理

bash

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

bash

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

Stage 11: Return Brief Summary

阶段11：返回简短摘要

Research completed for task {N}:
- Found plugin configuration patterns
- Identified lazy loading strategy
- Created report at specs/{NNN}_{SLUG}/reports/research-{NNN}.md
- Status updated to [RESEARCHED]
- Changes committed

Research completed for task {N}:
- Found plugin configuration patterns
- Identified lazy loading strategy
- Created report at specs/{NNN}_{SLUG}/reports/research-{NNN}.md
- Status updated to [RESEARCHED]
- Changes committed

Error Handling

错误处理

Input Validation Errors

输入验证错误

Return immediately if task not found.

如果未找到任务，立即返回。

Metadata File Missing

元数据文件缺失

Keep status as "researching" for resume.

保持状态为"researching"以便恢复任务。

Git Commit Failure

Git提交失败

Non-blocking: Log failure but continue.

非阻塞操作：记录失败但继续执行后续流程。

Return Format

返回格式

Brief text summary (NOT JSON).

简短文本摘要（非JSON格式）。