@catcuts-skills/handover 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Skill NPM Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# Handover Skill
+
+跨会话工作交接工具，支持 AI Agent 工作状态的保存与恢复。
+
+## 功能
+
+- **导出模式**：保存当前会话的工作状态到本地存档
+- **恢复模式**：从历史存档中恢复工作状态
+
+## 安装
+
+### 自动安装（推荐）
+
+安装本 npm 包时会自动将 skill 注册到 Claude Code：
+
+```bash
+# 全局安装（默认）
+npm install -g @catcheers/handover
+
+# 项目级安装
+SKILL_SCOPE=LOCAL npm install @catcheers/handover
+```
+
+**环境变量 `SKILL_SCOPE`**:
+
+- `GLOBAL`（默认）: 安装到用户目录 `~/.claude/skills/handover`
+- `LOCAL`: 安装到项目目录 `.claude/skills/handover`
+
+### 手动安装
+
+如果自动安装失败,可以手动运行：
+
+```bash
+# 全局安装
+npx add-skill . -a claude-code -g -y
+
+# 项目级安装
+npx add-skill . -a claude-code -y
+```
+
+**支持平台**: 基于 [Vercel 开源的 add-skill](https://github.com/vercel-labs/add-skill)，本技能支持 Opencode、Claude Code、Codex、Cursor 及其他 [19 个工具](https://github.com/vercel-labs/add-skill?tab=readme-ov-file#available-agents)。
+
+### 测试安装
+
+运行测试以验证安装配置（不会实际安装）：
+
+```bash
+npm test
+```
+
+### 卸载
+
+```bash
+# 全局卸载
+npm uninstall -g @catcheers/handover
+
+# 项目级卸载
+npm uninstall @catcheers/handover
+```
+
+卸载时会自动清理 skill 文件。
+
+## 使用
+
+**导出工作状态：**
+
+```
+请帮我交接当前工作
+```
+
+**恢复工作状态：**
+
+```
+请接手之前的 xx 工作
+```
+
+## 技术细节
+
+- 存档保存在项目根目录的 `.handover/` 中
+- 使用 Vercel 的 `add-skill` 工具进行安装管理
+
+### 安装路径
+
+**全局安装 (SKILL_SCOPE=GLOBAL)**:
+
+- 实际存储: `~/.agents/skills/handover/`
+- Claude Code 链接: `~/.claude/skills/handover/` (符号链接)
+
+**项目级安装 (SKILL_SCOPE=LOCAL)**:
+
+- 实际存储: `.agents/skills/handover/`
+- Claude Code 链接: `.claude/skills/handover/` (符号链接)
+
+### 系统要求
+
+- Node.js >= 18.0.0
+
+## 开发
+
+本技能基于 [agent-skill-npm-boilerplate](https://github.com/catcuts/agent-skill-npm-boilerplate) 开发。

package/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: handover
+description: 跨会话工作交接工具。支持"归档当前进度"和"恢复历史进度"两个模式。使用场景：需要在新会话中恢复之前的工作、需要在多个设备间同步工作上下文、需要保存当前工作状态以便稍后继续。
+allowed-tools: Read, Write, Bash
+---
+
+# Handover Skill
+
+## 任务指令
+
+当你被调用时，请判断用户的意图：是"交接出去"还是"接手回来"。
+
+## 模式 1：导出 (Export)
+
+如果用户说"交接"或类似含义（例如"交接。要求如下：..."）：
+
+1. **深度汇总**：分析当前会话，提取任务目标、已改代码、待办事项和核心逻辑，并形成一行简短的工作简述。
+
+2. **创建目录**：在 `.handover/` 下创建一个以第1步形成的"工作简述"命名的文件夹。
+
+3. **写入存档**：使用 `Write` 工具在第2步中创建的文件夹中生成 `HANDOVER.md`。
+
+4. **结束引导**：**必须**用在醒目的位置用醒目的样式在末尾输出以下文字：
+
+    ```
+    ✨ 存档已就绪 ✅
+
+    现在你可以（二选一）：
+    1) 直接手动执行 `/clear` 释放内存，在新会话中对我说明 `接手当前工作` 或类似的提示即可恢复。
+    2) 直接手动修改存档，或者通过与我对话的方式修改存档，直到满意为止，然后再执行 1) 操作。
+    ```
+
+## 模式 2：恢复 (Resume)
+
+如果用户输入"交接：接手"或类似含义（例如"交接：接手 xx 工作"）：
+
+1. **列出存档**：使用 `Bash` 工具执行 `ls -d .handover/*/` 列出所有已归档的工作目录。
+
+2. **交互选择**：
+    - 如果有多个存档，以数字列表形式展示（例如：`1. 优化登录逻辑`, `2. 修复样式Bug`）。
+    - 如果用户有明确指出要接手的工作，在列表中用"🚩"标注最有可能要接手的存档。
+    - 询问用户："请选择要接手的序号：已用 🚩 标记您最有可能要接手的存档。"
+    - 暂停等待用户选择后再继续。
+
+3. **读取并初始化**：
+    - 得到序号后，使用 `Read` 工具读取对应目录下的 `HANDOVER.md`。
+    - 告诉用户："✨ 读取成功。我已定位到存档的状态，现在我们可以在该存档的基础上继续工作。"
+
+## 附加信息
+
+存档文件保存在项目根目录的 `.handover/` 中，该目录已在 .gitignore 中排除。

package/package.json

@@ -0,0 +1,42 @@
+{
+    "name": "@catcuts-skills/handover",
+    "version": "1.0.0",
+    "description": "跨会话工作交接工具。支持归档当前进度和恢复历史进度两个模式。",
+    "main": "index.js",
+    "scripts": {
+        "postinstall": "node scripts/install-skill.js",
+        "preuninstall": "node scripts/uninstall-skill.js",
+        "test": "node scripts/install-skill.js --dry-run",
+        "install:global": "node scripts/install-skill.js --global",
+        "install:local": "node scripts/install-skill.js --local",
+        "lint": "echo 'Add your linting commands here'"
+    },
+    "files": [
+        "SKILL.md",
+        "scripts/"
+    ],
+    "optionalDependencies": {
+        "add-skill": "^1.0.29"
+    },
+    "keywords": [
+        "claude-code",
+        "skill",
+        "handover",
+        "session-management",
+        "context-transfer"
+    ],
+    "author": "catcuts",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/catcuts/agent-skills.git",
+        "directory": "skills/handover"
+    },
+    "bugs": {
+        "url": "https://github.com/catcuts/agent-skills/issues"
+    },
+    "homepage": "https://github.com/catcuts/agent-skills#readme",
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}

package/scripts/install-skill.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+/**
+ * Handover Skill 安装脚本
+ * 使用 add-skill 将 skill 安装到 Claude Code
+ *
+ * 命令行参数 (推荐):
+ * --dry-run: 测试模式,只显示将要执行的命令,不实际安装
+ * --global: 强制全局安装
+ * --local: 强制项目级安装
+ *
+ * 环境变量 (备用):
+ * - SKILL_SCOPE: 安装范围,可选值: GLOBAL(全局) 或 LOCAL(项目级),默认: GLOBAL
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// 获取包根目录
+const packageRoot = path.resolve(__dirname, '..');
+
+// 解析命令行参数
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const forceGlobal = args.includes('--global');
+const forceLocal = args.includes('--local');
+
+// 确定安装范围
+let scope;
+if (forceGlobal) {
+    scope = 'GLOBAL';
+} else if (forceLocal) {
+    scope = 'LOCAL';
+} else {
+    scope = (process.env.SKILL_SCOPE || 'GLOBAL').toUpperCase();
+}
+
+const isGlobal = scope === 'GLOBAL';
+
+// 日志函数
+function log(message, type = 'info') {
+    const prefix =
+        {
+            info: '✓',
+            success: '✓',
+            warning: '⚠',
+            error: '✗',
+        }[type] || '✓';
+
+    console.log(`${prefix} ${message}`);
+}
+
+// 错误处理
+function handleError(error) {
+    log(`安装失败: ${error.message}`, 'error');
+    log('\n您可以尝试手动安装:', 'warning');
+    log(`  npx add-skill "${packageRoot}" -a claude-code ${isGlobal ? '-g' : ''} -y`);
+    process.exit(1);
+}
+
+try {
+    log(`开始安装 Handover Skill...`, 'info');
+    log(`安装范围: ${isGlobal ? '全局(GLOBAL)' : '项目级(LOCAL)'}`, 'info');
+
+    // 构建 add-skill 命令
+    const commandParts = [
+        'npx',
+        'add-skill',
+        `"${packageRoot}"`,
+        // '-a', 'claude-code'  // 由 add-skill 自动检测，如果检测失败那么会自动弹出菜单让用户手动选择
+    ];
+
+    if (isGlobal) {
+        commandParts.push('-g');
+    }
+
+    commandParts.push('-y'); // 非交互模式
+
+    const command = commandParts.join(' ');
+
+    if (dryRun) {
+        log('\n[DRY-RUN] 将要执行的命令:', 'warning');
+        console.log(`  ${command}`);
+        log(
+            '\n测试通过 - 实际安装请运行: npm run install:global 或 npm run install:local',
+            'success'
+        );
+        process.exit(0);
+    }
+
+    // 执行安装
+    log('\n正在执行 add-skill...', 'info');
+    execSync(command, {
+        stdio: 'inherit',
+        cwd: packageRoot,
+    });
+
+    log('\n安装成功!', 'success');
+    log(
+        `Skill 已安装到: ${isGlobal ? '~/.claude/skills/handover' : '.claude/skills/handover'}`,
+        'info'
+    );
+} catch (error) {
+    handleError(error);
+}

package/scripts/uninstall-skill.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+/**
+ * Handover Skill 卸载脚本
+ * 从 Claude Code 中移除 skill
+ *
+ * 命令行参数 (推荐):
+ * --global: 强制全局卸载
+ * --local: 强制项目级卸载
+ *
+ * 环境变量 (备用):
+ * - SKILL_SCOPE: 安装范围,可选值: GLOBAL(全局) 或 LOCAL(项目级),默认: GLOBAL
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+// 解析命令行参数
+const args = process.argv.slice(2);
+const forceGlobal = args.includes('--global');
+const forceLocal = args.includes('--local');
+
+// 确定安装范围
+let scope;
+if (forceGlobal) {
+    scope = 'GLOBAL';
+} else if (forceLocal) {
+    scope = 'LOCAL';
+} else {
+    scope = (process.env.SKILL_SCOPE || 'GLOBAL').toUpperCase();
+}
+
+const isGlobal = scope === 'GLOBAL';
+
+// 日志函数
+function log(message, type = 'info') {
+    const prefix =
+        {
+            info: '✓',
+            success: '✓',
+            warning: '⚠',
+            error: '✗',
+        }[type] || '✓';
+
+    console.log(`${prefix} ${message}`);
+}
+
+// 递归删除目录
+function removeDirectory(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        return false;
+    }
+
+    try {
+        fs.rmSync(dirPath, { recursive: true, force: true });
+        return true;
+    } catch (error) {
+        log(`删除 ${dirPath} 失败: ${error.message}`, 'error');
+        return false;
+    }
+}
+
+try {
+    log(`开始卸载 Handover Skill...`, 'info');
+    log(`卸载范围: ${isGlobal ? '全局(GLOBAL)' : '项目级(LOCAL)'}`, 'info');
+
+    let removedCount = 0;
+
+    if (isGlobal) {
+        // 全局卸载
+        const homeDir = os.homedir();
+        const paths = [
+            path.join(homeDir, '.claude', 'skills', 'handover'),
+            path.join(homeDir, '.agents', 'skills', 'handover'),
+        ];
+
+        paths.forEach((dirPath) => {
+            if (removeDirectory(dirPath)) {
+                log(`已删除: ${dirPath}`, 'success');
+                removedCount++;
+            }
+        });
+    } else {
+        // 项目级卸载
+        const cwd = process.cwd();
+        const paths = [
+            path.join(cwd, '.claude', 'skills', 'handover'),
+            path.join(cwd, '.agents', 'skills', 'handover'),
+        ];
+
+        paths.forEach((dirPath) => {
+            if (removeDirectory(dirPath)) {
+                log(`已删除: ${dirPath}`, 'success');
+                removedCount++;
+            }
+        });
+    }
+
+    if (removedCount > 0) {
+        log(`\n卸载成功! 已删除 ${removedCount} 个目录`, 'success');
+    } else {
+        log('\n未找到已安装的 skill 文件', 'warning');
+    }
+} catch (error) {
+    log(`卸载失败: ${error.message}`, 'error');
+    process.exit(1);
+}