@catcuts-skills/commit 1.0.1 → 1.0.4

package/README.md

@@ -61,15 +61,44 @@ npm test
 
 ### 卸载
 
+**重要**：由于 npm 的限制，全局卸载时 preuninstall hook 可能不会执行。请按照以下步骤正确卸载：
+
+#### 方式 1：使用 npm scripts（推荐）
+
 ```bash
 # 全局卸载
-npm uninstall -g @<your-username>/commit
+npm run uninstall:global
+npm uninstall -g @catcuts-skills/commit
 
 # 项目级卸载
-npm uninstall @<your-username>/commit
+npm run uninstall:local
+npm uninstall @catcuts-skills/commit
 ```
 
-卸载时会自动清理 skill 文件。
+#### 方式 2：手动清理（如果方式 1 失败）
+
+```bash
+# 1. 清理技能文件
+rm -rf ~/.claude/skills/commit
+rm -rf ~/.agents/skills/commit
+
+# 2. 卸载 npm 包
+npm uninstall -g @catcuts-skills/commit
+```
+
+**Windows PowerShell**:
+```powershell
+# 1. 清理技能文件
+Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\skills\commit"
+Remove-Item -Recurse -Force "$env:USERPROFILE\.agents\skills\commit"
+
+# 2. 卸载 npm 包
+npm uninstall -g @catcuts-skills/commit
+```
+
+#### 为什么需要两步？
+
+npm 的 `preuninstall` hook 在全局卸载时**不保证被执行**，这是 npm 的已知限制。因此需要先手动清理技能文件，再卸载 npm 包。
 
 ## 使用示例
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catcuts-skills/commit",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "读取 staged 代码差异，自动生成符合 Conventional Commits 规范的提交文本",
   "main": "index.js",
   "scripts": {
@@ -15,7 +15,7 @@
     "scripts/"
   ],
   "optionalDependencies": {
-    "add-skill": "^1.0.29"
+    "skills": "^1.1.2"
   },
   "keywords": [
     "claude-code",
@@ -34,7 +34,7 @@
   "bugs": {
     "url": "https://github.com/catcuts/agent-skills/issues"
   },
-  "homepage": "https://github.com/catcuts/agent-skills#readme",
+  "homepage": "https://github.com/catcuts/agent-skills/tree/main/skills/commit#readme",
   "engines": {
     "node": ">=18.0.0"
   }

package/scripts/install-skill.js

@@ -2,7 +2,7 @@
 
 /**
  * Commit Skill Installation Script
- * Install skill to Claude Code using add-skill
+ * Install skill to Claude Code using skills
  *
  * Command Line Arguments (Recommended):
  * --dry-run: Test mode, show command without executing
@@ -15,14 +15,32 @@
 
 const { execSync } = require('child_process');
 const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const { printUsageGuide } = require('./usage-guide');
 
 // Get package root directory
 const packageRoot = path.resolve(__dirname, '..');
 
+// Get user home directory
+const homeDir = os.homedir();
+
 // Read package.json to get skill name
 const packageJson = require(path.join(packageRoot, 'package.json'));
 const skillName = packageJson.name.split('/')[1] || packageJson.name;
 
+// Paths to clean
+const pathsToClean = {
+    // skills CLI canonical copy directory (root cause of the issue)
+    canonical: path.join(homeDir, '.agents', 'skills', skillName),
+
+    // Claude Code global skill directory (symlink)
+    claudeGlobal: path.join(homeDir, '.claude', 'skills', skillName),
+
+    // Claude Code project-level skill directory (if exists)
+    claudeLocal: path.join(process.cwd(), '.claude', 'skills', skillName),
+};
+
 // Parse command line arguments
 const args = process.argv.slice(2);
 const dryRun = args.includes('--dry-run');
@@ -53,11 +71,102 @@ function log(message, type = 'info') {
     console.log(`${prefix} ${message}`);
 }
 
+// Safely remove a path (supports symlinks, files, directories)
+function safeRemovePath(filePath, description) {
+    try {
+        if (!fs.existsSync(filePath)) {
+            return { success: true, removed: false, message: 'Not found' };
+        }
+
+        const stats = fs.lstatSync(filePath);
+        const isLink = stats.isSymbolicLink();
+        const isDir = stats.isDirectory();
+
+        if (isLink) {
+            fs.unlinkSync(filePath);
+            return {
+                success: true,
+                removed: true,
+                message: `Removed symlink: ${description}`
+            };
+        } else if (isDir) {
+            fs.rmSync(filePath, { recursive: true, force: true });
+            return {
+                success: true,
+                removed: true,
+                message: `Removed directory: ${description}`
+            };
+        } else {
+            fs.unlinkSync(filePath);
+            return {
+                success: true,
+                removed: true,
+                message: `Removed file: ${description}`
+            };
+        }
+    } catch (error) {
+        return {
+            success: false,
+            removed: false,
+            message: `Failed to remove: ${error.message}`
+        };
+    }
+}
+
+// Clean old installation files
+function cleanOldInstallations() {
+    log('\nCleaning up old installation files...', 'info');
+
+    const results = [];
+
+    // 1. Clean canonical copy directory (.agents/skills/<skill>)
+    const canonicalResult = safeRemovePath(
+        pathsToClean.canonical,
+        'canonical copy'
+    );
+    results.push({ path: pathsToClean.canonical, ...canonicalResult });
+
+    // 2. Clean Claude Code global symlink
+    const globalResult = safeRemovePath(
+        pathsToClean.claudeGlobal,
+        'global skill link'
+    );
+    results.push({ path: pathsToClean.claudeGlobal, ...globalResult });
+
+    // 3. Clean Claude Code project-level installation (if exists)
+    const localResult = safeRemovePath(
+        pathsToClean.claudeLocal,
+        'project-level skill'
+    );
+    results.push({ path: pathsToClean.claudeLocal, ...localResult });
+
+    // Output cleanup results
+    let removedCount = 0;
+    results.forEach((result) => {
+        if (result.removed) {
+            log(`  ✓ ${result.message}`, 'success');
+            removedCount++;
+        } else if (result.success) {
+            log(`  ⊗ ${result.message} (skipped)`, 'info');
+        } else {
+            log(`  ✗ ${result.message}`, 'warning');
+        }
+    });
+
+    if (removedCount > 0) {
+        log(`\nCleaned up ${removedCount} old installation(s)`, 'success');
+    } else {
+        log('No old installations found to clean', 'info');
+    }
+
+    return removedCount > 0;
+}
+
 // Error handler
 function handleError(error) {
     log(`Installation failed: ${error.message}`, 'error');
     log('\nYou can try manual installation:', 'warning');
-    log(`  npx add-skill "${packageRoot}" -a claude-code ${isGlobal ? '-g' : ''} -y`);
+    log(`  npx skills add "${packageRoot}" ${isGlobal ? '-g' : ''} -y`);
     process.exit(1);
 }
 
@@ -65,10 +174,14 @@ try {
     log(`Starting installation of ${skillName}...`, 'info');
     log(`Installation scope: ${isGlobal ? 'Global (GLOBAL)' : 'Project-level (LOCAL)'}`, 'info');
 
-    // Build add-skill command
+    // Clean old installation files (solves incremental update file residue issue)
+    cleanOldInstallations();
+
+    // Build skills command
     const commandParts = [
         'npx',
-        'add-skill',
+        'skills',
+        'add',
         `"${packageRoot}"`,
     ];
 
@@ -88,7 +201,7 @@ try {
     }
 
     // Execute installation
-    log('\nExecuting add-skill...', 'info');
+    log('\nExecuting skills add...', 'info');
     execSync(command, {
         stdio: 'inherit',
         cwd: packageRoot
@@ -97,6 +210,9 @@ try {
     log('\nInstallation successful!', 'success');
     log(`Skill installed to: ${isGlobal ? `~/.claude/skills/${skillName}` : `.claude/skills/${skillName}`}`, 'info');
 
+    // 显示使用指南
+    printUsageGuide();
+
 } catch (error) {
     handleError(error);
 }

package/scripts/uninstall-skill.js

@@ -2,7 +2,14 @@
 
 /**
  * Commit Skill Uninstallation Script
- * Remove installed skill files
+ * Remove installed skill files from Claude Code
+ *
+ * Command Line Arguments:
+ * --global: Force global uninstallation
+ * --local: Force project-level uninstallation
+ *
+ * Environment Variables:
+ * - SKILL_SCOPE: Installation scope, GLOBAL or LOCAL, default: GLOBAL
  */
 
 const fs = require('fs');
@@ -16,6 +23,23 @@ const packageRoot = path.resolve(__dirname, '..');
 const packageName = require(path.join(packageRoot, 'package.json')).name;
 const skillName = packageName.split('/')[1] || packageName;
 
+// Parse command line arguments
+const args = process.argv.slice(2);
+const forceGlobal = args.includes('--global');
+const forceLocal = args.includes('--local');
+
+// Determine uninstallation scope
+let scope;
+if (forceGlobal) {
+    scope = 'GLOBAL';
+} else if (forceLocal) {
+    scope = 'LOCAL';
+} else {
+    scope = (process.env.SKILL_SCOPE || 'GLOBAL').toUpperCase();
+}
+
+const isGlobal = scope === 'GLOBAL';
+
 // Logging function
 function log(message, type = 'info') {
     const prefix = {
@@ -28,39 +52,123 @@ function log(message, type = 'info') {
     console.log(`${prefix} ${message}`);
 }
 
-// Remove function
-function removeSkill(dir, description) {
+// Safely remove a path (supports symlinks, files, directories)
+function safeRemovePath(filePath, description) {
     try {
-        if (fs.existsSync(dir)) {
-            fs.rmSync(dir, { recursive: true, force: true });
-            log(`Removed ${description}: ${dir}`, 'success');
+        if (!fs.existsSync(filePath)) {
+            return { success: true, removed: false, message: 'Not found' };
+        }
+
+        const stats = fs.lstatSync(filePath);
+        const isLink = stats.isSymbolicLink();
+        const isDir = stats.isDirectory();
+
+        if (isLink) {
+            fs.unlinkSync(filePath);
+            return {
+                success: true,
+                removed: true,
+                message: `Removed symlink: ${description}`
+            };
+        } else if (isDir) {
+            fs.rmSync(filePath, { recursive: true, force: true });
+            return {
+                success: true,
+                removed: true,
+                message: `Removed directory: ${description}`
+            };
         } else {
-            log(`${description} does not exist: ${dir}`, 'info');
+            fs.unlinkSync(filePath);
+            return {
+                success: true,
+                removed: true,
+                message: `Removed file: ${description}`
+            };
         }
     } catch (error) {
-        log(`Failed to remove ${description}: ${error.message}`, 'error');
+        // Ignore "file not found" errors, may have been deleted concurrently
+        if (error.code === 'ENOENT') {
+            return { success: true, removed: false, message: 'Already removed' };
+        }
+        return {
+            success: false,
+            removed: false,
+            message: `Failed: ${error.message}`
+        };
     }
 }
 
 try {
     log(`Starting uninstallation of ${skillName}...`, 'info');
+    log(`Uninstallation scope: ${isGlobal ? 'Global (GLOBAL)' : 'Project-level (LOCAL)'}`, 'info');
+
+    log('\nCleaning up skill files...', 'info');
+
+    const results = [];
 
-    // Remove global installation
-    const globalDir = path.join(os.homedir(), '.claude', 'skills', skillName);
-    removeSkill(globalDir, 'global installation');
+    if (isGlobal) {
+        // Global uninstallation
+        const homeDir = os.homedir();
 
-    // Remove project-level installation
-    const localDir = path.join(process.cwd(), '.claude', 'skills', skillName);
-    removeSkill(localDir, 'project-level installation');
+        // 1. Clean canonical copy directory (.agents/skills/<skill>)
+        const canonicalResult = safeRemovePath(
+            path.join(homeDir, '.agents', 'skills', skillName),
+            'canonical copy'
+        );
+        results.push(canonicalResult);
 
-    // Remove actual storage directories (.agents/)
-    const globalAgentsDir = path.join(os.homedir(), '.agents', 'skills', skillName);
-    removeSkill(globalAgentsDir, 'global storage directory');
+        // 2. Clean Claude Code global symlink
+        const globalResult = safeRemovePath(
+            path.join(homeDir, '.claude', 'skills', skillName),
+            'global skill link'
+        );
+        results.push(globalResult);
+    } else {
+        // Project-level uninstallation
+        const cwd = process.cwd();
 
-    const localAgentsDir = path.join(process.cwd(), '.agents', 'skills', skillName);
-    removeSkill(localAgentsDir, 'project-level storage directory');
+        // 1. Clean project-level canonical copy (if exists)
+        const canonicalResult = safeRemovePath(
+            path.join(cwd, '.agents', 'skills', skillName),
+            'project-level canonical copy'
+        );
+        results.push(canonicalResult);
 
-    log('\nUninstallation completed!', 'success');
+        // 2. Clean Claude Code project-level skill
+        const localResult = safeRemovePath(
+            path.join(cwd, '.claude', 'skills', skillName),
+            'project-level skill'
+        );
+        results.push(localResult);
+    }
+
+    // Output cleanup results
+    let removedCount = 0;
+    let errorCount = 0;
+
+    results.forEach((result) => {
+        if (result.removed) {
+            log(`  ✓ ${result.message}`, 'success');
+            removedCount++;
+        } else if (result.success) {
+            log(`  ⊗ ${result.message} (skipped)`, 'info');
+        } else {
+            log(`  ✗ ${result.message}`, 'error');
+            errorCount++;
+        }
+    });
+
+    // Summary
+    if (removedCount > 0) {
+        log(`\n✓ Uninstallation successful! Removed ${removedCount} file(s)/director(y)(ies)`, 'success');
+    } else if (errorCount === 0) {
+        log('\n⊗ No files found to uninstall', 'warning');
+    }
+
+    if (errorCount > 0) {
+        log(`\n⚠ ${errorCount} item(s) failed to remove, please clean up manually`, 'warning');
+        process.exit(1);
+    }
 
 } catch (error) {
     log(`Uninstallation failed: ${error.message}`, 'error');

package/scripts/usage-guide.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+/**
+ * 技能使用指南生成器
+ * 在安装成功后显示友好的使用指南
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * 读取 package.json 中的信息
+ */
+function getPackageInfo() {
+    const packageRoot = path.resolve(__dirname, '..');
+    const packageJsonPath = path.join(packageRoot, 'package.json');
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+
+    return {
+        name: packageJson.name.split('/')[1] || packageJson.name,
+        description: packageJson.description,
+        homepage: packageJson.homepage || '',
+        repository: packageJson.repository?.url || '',
+    };
+}
+
+/**
+ * 读取 SKILL.md 中的触发指令
+ */
+function getSkillInstructions() {
+    const packageRoot = path.resolve(__dirname, '..');
+    const skillMdPath = path.join(packageRoot, 'SKILL.md');
+
+    if (!fs.existsSync(skillMdPath)) {
+        return null;
+    }
+
+    const content = fs.readFileSync(skillMdPath, 'utf-8');
+    // 匹配 description 行中的指令说明
+    const match = content.match(/^description:\s*(.+)$/m);
+    return match ? match[1].trim() : null;
+}
+
+/**
+ * 打印使用指南
+ */
+function printUsageGuide() {
+    const pkg = getPackageInfo();
+    const instructions = getSkillInstructions();
+
+    // 如果 SKILL.md 中有指令说明，使用它；否则使用 package.json 的 description
+    const usageInfo = instructions || pkg.description;
+
+    const guide = `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  🎉 技能安装成功！
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📦 技能名称:    ${pkg.name}
+📝 功能描述:    ${pkg.description}
+
+🚀 如何使用:
+   ${usageInfo}
+
+📖 更多信息:
+   ${pkg.homepage ? `   文档: ${pkg.homepage}` : ''}
+   ${pkg.repository ? `   仓库: ${pkg.repository}` : ''}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+
+    console.log(guide);
+}
+
+module.exports = { printUsageGuide };