---
name: skill-refresh
version: "1.0.1"
category: meta
description: "当修改 SKILL.md 后需要刷新技能缓存时使用。不要用于普通技能执行或不相关任务。"
triggers:
  zh: ["refresh", "刷新", "reload", "更新技能", "skill update", "热更新"]
  en: ["refresh", "reload", "skill update", "hot reload"]
license: MIT
compatibility: Node.js >= 14
config:
  - config/git.yaml
dependencies:
  - git-safe
metadata:
  author: "sunhongda@example.com"
  created: "2026-06-16"
  updated: "2026-06-17"
  status: "stable"
---

# 技能刷新 / Skill Refresh

## Changelog / 版本履历

| 日期 | 版本 | 变更摘要 |
|------|------|---------|
| 2026-06-17 | 1.0.1 | Task 8 规范化：修复 YAML 分隔符、添加 Workflow 章节、修复 Changelog 格式、双语标头 |
| 2026-06-16 | 1.0.0 | 规范化调整 |

## Core Concept / 核心概念

### 🇨🇳
一句话说清：输入什么 → 做什么 → 输出什么。明确 **不做什么**。

**输入**: SKILL.md 文件变更 | **输出**: OpenCode 技能缓存刷新完成 | **不负责**: 中断当前会话或修改用户代码

### 🇺🇸
One line: Input → Process → Output. Explicitly state what is **NOT done**.

**Input**: SKILL.md file changes | **Output**: OpenCode skill cache refreshed | **NOT responsible for**: Interrupting current sessions or modifying user code

***

## Position / 定位

```
技能修改 (git-safe commit) → skill-refresh → OpenCode 缓存重载
    (SKILL.md 变更检测)        (缓存版本更新)      (会话无缝衔接)
```

***

## Workflow / 工作流程

### Step 1: Detect Changes / 检测变更

**中文：** 检测项目内所有 SKILL.md 文件的修改时间戳变化。通过 `git diff --name-only` 或文件系统 `mtime` 对比上次缓存时间戳。

**EN:** Detect modification timestamp changes for all SKILL.md files. Use `git diff --name-only` or filesystem `mtime` comparison against last cache timestamp.

### Step 2: Update Cache Version / 更新缓存版本

**中文：** 更新 `$OPENCODE_SKILLS_ROOT/.cache-version` 文件，写入当前时间戳。OpenCode 检测到版本变更后自动重新扫描技能目录。

**EN:** Update `$OPENCODE_SKILLS_ROOT/.cache-version` with current timestamp. OpenCode detects version change and auto-rescans skill directory.

### Step 3: Verify Refresh / 验证刷新

**中文：** 确认缓存文件时间戳已更新。可选：在新会话中验证技能是否加载最新版本。

**EN:** Confirm cache file timestamp is updated. Optional: verify skills load latest version in a new session.

### Step 4: Report / 输出报告

**中文：** 输出变更摘要：检测到的变更文件列表、缓存更新时间戳、刷新状态。

**EN:** Output change summary: detected file changes, cache update timestamp, refresh status.

***

## Iron Law / 核心铁律

### 🇨🇳
1. **铁律1**: 绝不强制刷新活跃会话中的技能缓存。违规示例：❌ 直接重启OpenCode进程。合规示例：✅ 仅更新缓存版本，等待下次会话自动加载。
2. **铁律2**: 必须验证缓存版本文件已正确更新。违规示例：❌ 假设脚本执行成功就完成。合规示例：✅ 检查 $OPENCODE_SKILLS_ROOT/.cache-version 时间戳是否更新。
3. **铁律3**: 绝不跳过后置提交钩子验证。违规示例：❌ 手动修改SKILL.md后不触发post-commit.sh。合规示例：✅ 确保git commit自动触发刷新流程。

### 🇺🇸
1. **Law 1**: Never force refresh skill cache during active sessions. Violation: ❌ Directly restarting OpenCode process. Compliance: ✅ Only update cache version, wait for next session auto-load.
2. **Law 2**: Always verify cache version file is properly updated. Violation: ❌ Assuming script execution success means completion. Compliance: ✅ Check $OPENCODE_SKILLS_ROOT/.cache-version timestamp is updated.
3. **Law 3**: Never skip post-commit hook verification. Violation: ❌ Manually modifying SKILL.md without triggering post-commit.sh. Compliance: ✅ Ensure git commit automatically triggers refresh workflow.

***

## Rationalization Table / 合理化防御表

| # | Trap / 陷阱 | Question / 请问自己 | Action / 应该怎么做 |
|---|-------------|------------------|------------------|
| 1 | "手动刷新就够了，不需要自动触发" | 自动刷新是否能减少人为错误？ | ✅ 必须保持自动触发机制，手动刷新仅作备用 |
| 2 | "缓存版本更新了就一定生效" | 如何验证OpenCode确实重新加载了技能？ | ✅ 检查新会话中技能是否包含最新变更 |
| 3 | "跳过post-commit钩子也没关系" | 不通过git提交的修改如何被检测到？ | ✅ 所有SKILL.md修改必须通过git-safe提交流程 |

***

## Red Flags / 三层防御

### Layer 1: Input / 输入
- **INPUT-01**: SKILL.md 文件未通过 git-safe 提交 → 🔴 CRITICAL → 中断并提示使用 git-safe commit

### Layer 2: Execution / 执行
- **EXEC-01**: post-commit.sh 脚本执行失败或超时 → 🔴 CRITICAL → 记录错误并提供手动刷新命令
- **EXEC-02**: cache-version 文件无法写入 → 🟡 WARN → 尝试备用缓存位置并标记警告

### Layer 3: Output / 输出
- **OUTPUT-01**: 新会话中技能仍使用旧版本 → 🔴 CRITICAL → 强制清除所有缓存并重新扫描

**级别标识**: 🔴 CRITICAL → 中断 | 🟡 WARN → 继续+标记 | 🔵 INFO → 记录

***

## Output / 输出规范

### 🇨🇳
输出格式为控制台日志，包含以下信息：
- 检测到的SKILL.md文件变更列表
- cache-version文件更新时间戳
- 刷新状态（成功/失败）及错误详情（如有）

### 🇺🇸
Output format is console log containing:
- List of detected SKILL.md file changes
- cache-version file update timestamp
- Refresh status (success/failure) with error details if any

***

## How It Works / 工作原理

```
修改 SKILL.md
    │
    ▼
git-safe commit (auto-detect changes)
    │
    ▼
skill-refresh 检测到变更
    │
    ├── 更新 .omo/skills-cache.json (版本时间戳)
    ├── 触发 OpenCode 重新扫描 skills 目录
    └── 不影响当前会话上下文
```

***

## Auto-Refresh Trigger / 自动触发

修改任意 SKILL.md 后，`skill-refresh` 通过以下方式生效：

1. **Git hook (post-commit)**: `scripts/post-commit.sh` 检测 SKILL.md 变更
2. **Cache busting**: 更新 `$OPENCODE_SKILLS_ROOT/.cache-version`
3. **Session reload**: OpenCode 检测到 cache version 变更后重新加载

## Manual Refresh / 手动刷新

```bash
node skill-refresh/scripts/refresh.js
```

## Refresh Script / 刷新脚本

`scripts/refresh.js` 执行以下操作：

```javascript
// 1. 扫描所有 SKILL.md 的 mtime
// 2. 对比上次缓存时间戳
// 3. 更新 cache-version 文件
// 4. 输出变更摘要
```

## Integration / 集成

- **修改 skills 后**: 自动触发 refresh
- **git pull 后**: 自动检测新增/修改的 skills
- **不影响原会话**: refresh 仅更新缓存，不中断当前对话

***

## Auto-Review / 自检清单

> 每次执行后自动检查：

| # | 检查项 | 状态 |
|---|--------|------|
| 1 | cache-version 文件时间戳已更新 | ☐ |
| 2 | post-commit.sh 脚本执行无错误 | ☐ |
| 3 | 新会话能正确加载更新后的技能 | ☐ |
| 4 | 原有会话未被中断或影响 | ☐ |
| 5 | 所有SKILL.md变更都被正确检测到 | ☐ |