@sstar/skill-install 1.2.2 → 1.2.3

package/README.md

@@ -4,9 +4,9 @@
 
 ## 功能特性
 
-- **多工具支持**：同时支持 Claude Code (`~/.claude/skills/`) 和 Codex (`~/.codex/skills/`)
+- **多工具支持**：同时支持 Claude Code (`~/.claude/skills/`) 和 Codex (`~/.agents/skills/`)
 - **自动检测来源**：自动识别来源类型（公开 URL、需认证的 Wiki URL 或本地文件）
-- **多种归档格式**：支持 `.zip` 和 `.tar.gz` 归档文件
+- **多种归档格式**：支持 `.zip`、`.skill`、`.tar.gz`、`.tgz`，并优先按文件内容识别
 - **严格验证**：验证归档包含有效的 `SKILL.md` 文件及必需的 frontmatter
 - **Wiki 认证**：支持内部 Confluence Wiki 的身份认证
 - **技能管理**：列出已安装的技能并支持卸载
@@ -90,8 +90,8 @@ skill-install install ./my-skill.zip --force
 | 选项 | 描述 |
 |------|------|
 | `<source>` | 技能归档的 URL 或本地文件路径 |
-| `-g, --global` | 安装到全局目录 (`~/.claude/skills/` 或 `~/.codex/skills/`) |
-| `-l, --local` | 安装到本地目录 (`./.claude/skills/` 或 `./.codex/skills/`) |
+| `-g, --global` | 安装到全局目录 (`~/.claude/skills/` 或 `~/.agents/skills/`) |
+| `-l, --local` | 安装到本地目录 (`./.claude/skills/` 或 `./.agents/skills/`) |
 | `-u, --username <username>` | Wiki 用户名（用于 Wiki URL） |
 | `-p, --password <password>` | Wiki 密码（或使用环境变量） |
 | `--allow-self-signed` | 允许自签名 SSL 证书（默认：true） |
@@ -149,8 +149,9 @@ description: 对该技能功能的简要描述
 - **本地**：`./.claude/skills/` - 项目特定
 
 ### Codex
-- **全局**：`~/.codex/skills/` - 所有项目可用
-- **本地**：`./.codex/skills/` - 项目特定
+- **全局**：`~/.agents/skills/` - 所有项目可用
+- **本地**：`./.agents/skills/` - 项目特定
+- **兼容**：读取与卸载时会兼容旧目录 `~/.codex/skills/` 和 `./.codex/skills/`
 
 ### 目录选择
 - **全局**：使用 `--global` 标志或提示时选择 "1"（推荐用于常用技能）
@@ -177,7 +178,7 @@ skill-install install https://github.com/user/repo/archive/main.zip
 # 输出：
 # Select AI tool:
 #   1. Claude Code (~/.claude/skills/)
-#   2. Codex      (~/.codex/skills/)
+#   2. Codex      (~/.agents/skills/)
 #
 # Choose [1/2]: 1
 #
@@ -251,7 +252,7 @@ skill-install uninstall
 # 输出：
 # Select AI tool:
 #   1. Claude Code (~/.claude/skills/)
-#   2. Codex      (~/.codex/skills/)
+#   2. Codex      (~/.agents/skills/)
 #
 # Choose [1/2]: 1
 #

package/dist/archive/archive-extractor.d.ts

@@ -5,6 +5,16 @@ export declare class ArchiveExtractor {
      * Detect the archive type from a filename
      */
     detectArchiveType(filename: string): ArchiveType;
+    /**
+     * Detect archive type from file content first, then fallback to file extension.
+     * This supports extensionless archives and custom suffixes like .skill.
+     */
+    private resolveArchiveType;
+    private detectArchiveTypeWithFileCommand;
+    private getFileMimeType;
+    private getFileDescription;
+    private mapMimeTypeToArchiveType;
+    private mapDescriptionToArchiveType;
     /**
      * Extract an archive to a directory
      * @param archivePath Path to the archive file

package/dist/archive/archive-extractor.js

@@ -6,10 +6,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArchiveExtractor = void 0;
 const promises_1 = require("fs/promises");
 const path_1 = require("path");
+const child_process_1 = require("child_process");
+const util_1 = require("util");
 const tar_1 = require("tar");
 const adm_zip_1 = __importDefault(require("adm-zip"));
 const logger_1 = require("../core/logger");
 const errors_1 = require("../core/errors");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
 class ArchiveExtractor {
     constructor() {
         this.logger = new logger_1.Logger('ArchiveExtractor');
@@ -20,10 +23,17 @@ class ArchiveExtractor {
     detectArchiveType(filename) {
         const ext = (0, path_1.extname)(filename).toLowerCase();
         const base = (0, path_1.basename)(filename, ext).toLowerCase();
+        const lowercaseFilename = filename.toLowerCase();
         // Check for compound extensions
-        if (filename.toLowerCase().endsWith('.tar.gz') || filename.toLowerCase().endsWith('.tgz')) {
+        if (lowercaseFilename.endsWith('.tar.gz')) {
             return 'tar.gz';
         }
+        if (lowercaseFilename.endsWith('.tgz')) {
+            return 'tgz';
+        }
+        if (ext === '.skill') {
+            return 'zip';
+        }
         if (ext === '.zip') {
             return 'zip';
         }
@@ -32,6 +42,76 @@ class ArchiveExtractor {
         }
         return 'unknown';
     }
+    /**
+     * Detect archive type from file content first, then fallback to file extension.
+     * This supports extensionless archives and custom suffixes like .skill.
+     */
+    async resolveArchiveType(archivePath) {
+        const byContent = await this.detectArchiveTypeWithFileCommand(archivePath);
+        if (byContent !== 'unknown') {
+            return byContent;
+        }
+        return this.detectArchiveType(archivePath);
+    }
+    async detectArchiveTypeWithFileCommand(archivePath) {
+        const mimeType = await this.getFileMimeType(archivePath);
+        const byMime = this.mapMimeTypeToArchiveType(mimeType);
+        if (byMime !== 'unknown') {
+            return byMime;
+        }
+        const description = await this.getFileDescription(archivePath);
+        return this.mapDescriptionToArchiveType(description);
+    }
+    async getFileMimeType(archivePath) {
+        try {
+            const result = await execFileAsync('file', ['--brief', '--mime-type', archivePath], { timeout: 5000 });
+            return String(result.stdout).trim().toLowerCase();
+        }
+        catch (error) {
+            this.logger.debug(`Unable to detect mime type via file command: ${error}`);
+            return '';
+        }
+    }
+    async getFileDescription(archivePath) {
+        try {
+            const result = await execFileAsync('file', ['--brief', archivePath], { timeout: 5000 });
+            return String(result.stdout).trim().toLowerCase();
+        }
+        catch (error) {
+            this.logger.debug(`Unable to detect description via file command: ${error}`);
+            return '';
+        }
+    }
+    mapMimeTypeToArchiveType(mimeType) {
+        if (!mimeType) {
+            return 'unknown';
+        }
+        if (mimeType === 'application/zip') {
+            return 'zip';
+        }
+        if (mimeType === 'application/x-tar') {
+            return 'tar';
+        }
+        if (mimeType === 'application/gzip' || mimeType === 'application/x-gzip') {
+            return 'tar.gz';
+        }
+        return 'unknown';
+    }
+    mapDescriptionToArchiveType(description) {
+        if (!description) {
+            return 'unknown';
+        }
+        if (description.includes('zip archive data')) {
+            return 'zip';
+        }
+        if (description.includes('tar archive')) {
+            return 'tar';
+        }
+        if (description.includes('gzip compressed data')) {
+            return 'tar.gz';
+        }
+        return 'unknown';
+    }
     /**
      * Extract an archive to a directory
      * @param archivePath Path to the archive file
@@ -39,7 +119,7 @@ class ArchiveExtractor {
      * @throws WikiError if extraction fails
      */
     async extract(archivePath, targetDir) {
-        const archiveType = this.detectArchiveType(archivePath);
+        const archiveType = await this.resolveArchiveType(archivePath);
         this.logger.info(`Extracting ${archiveType} archive: ${archivePath} -> ${targetDir}`);
         switch (archiveType) {
             case 'zip':
@@ -51,7 +131,7 @@ class ArchiveExtractor {
                 await this.extractTar(archivePath, targetDir);
                 break;
             default:
-                throw new errors_1.WikiError(errors_1.ErrorType.EXTRACTION_FAILED, `Unknown archive type: ${archivePath}. Supported formats: .zip, .tar, .tar.gz`);
+                throw new errors_1.WikiError(errors_1.ErrorType.EXTRACTION_FAILED, `Unknown archive type: ${archivePath}. Supported formats: .zip, .skill, .tar, .tar.gz, .tgz`);
         }
         this.logger.info(`Extraction complete: ${targetDir}`);
     }
@@ -88,7 +168,7 @@ class ArchiveExtractor {
      * Useful for detecting if the archive contains a single root directory
      */
     async getRootDirectoryName(archivePath) {
-        const archiveType = this.detectArchiveType(archivePath);
+        const archiveType = await this.resolveArchiveType(archivePath);
         if (archiveType === 'zip') {
             return this.getZipRootDir(archivePath);
         }

package/dist/skills/skills-manager.d.ts

@@ -8,6 +8,10 @@ export interface InstalledSkill {
 export declare class SkillsManager {
     private readonly logger;
     private readonly validator;
+    private getPrimaryToolDirName;
+    private getLegacyToolDirNames;
+    private getDefaultSkillsDirs;
+    private getCandidateSkillsDirs;
     /**
      * Get the global skills directory for the specified AI tool
      */

package/dist/skills/skills-manager.js

@@ -12,17 +12,37 @@ class SkillsManager {
         this.logger = new logger_1.Logger('SkillsManager');
         this.validator = new skill_validator_1.SkillValidator();
     }
+    getPrimaryToolDirName(aiTool) {
+        return aiTool === 'codex' ? '.agents' : `.${aiTool}`;
+    }
+    getLegacyToolDirNames(aiTool) {
+        return aiTool === 'codex' ? ['.codex'] : [];
+    }
+    getDefaultSkillsDirs(aiTool = 'claude', isGlobal = true) {
+        const basePath = isGlobal ? (0, os_1.homedir)() : process.cwd();
+        const dirNames = [
+            this.getPrimaryToolDirName(aiTool),
+            ...this.getLegacyToolDirNames(aiTool)
+        ];
+        return dirNames.map(dirName => (0, path_1.join)(basePath, dirName, 'skills'));
+    }
+    getCandidateSkillsDirs(skillsDir, aiTool = 'claude') {
+        if (skillsDir) {
+            return [skillsDir];
+        }
+        return this.getDefaultSkillsDirs(aiTool, true);
+    }
     /**
      * Get the global skills directory for the specified AI tool
      */
     getGlobalSkillsDir(aiTool = 'claude') {
-        return (0, path_1.join)((0, os_1.homedir)(), `.${aiTool}`, 'skills');
+        return this.getDefaultSkillsDirs(aiTool, true)[0];
     }
     /**
      * Get the local skills directory for the specified AI tool
      */
     getLocalSkillsDir(aiTool = 'claude') {
-        return (0, path_1.join)(process.cwd(), `.${aiTool}`, 'skills');
+        return this.getDefaultSkillsDirs(aiTool, false)[0];
     }
     /**
      * Get both global and local directories for an AI tool
@@ -51,40 +71,45 @@ class SkillsManager {
      * @returns Array of installed skill metadata
      */
     async listInstalled(skillsDir, aiTool = 'claude') {
-        const dir = this.getEffectiveSkillsDir(skillsDir, aiTool);
-        const skills = [];
-        this.logger.info(`Listing skills in: ${dir}`);
-        try {
-            const entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
-            for (const entry of entries) {
-                if (!entry.isDirectory()) {
-                    continue;
-                }
-                const skillPath = (0, path_1.join)(dir, entry.name);
-                try {
-                    const metadata = await this.validator.validateOrThrow(skillPath);
-                    skills.push({
-                        name: metadata.name,
-                        description: metadata.description,
-                        path: skillPath,
-                        tool: aiTool
-                    });
-                }
-                catch (error) {
-                    // Skip invalid entries but log a warning
-                    this.logger.warn(`Skipping invalid skill directory: ${entry.name}`);
+        const candidateDirs = this.getCandidateSkillsDirs(skillsDir, aiTool);
+        const skills = new Map();
+        for (const dir of candidateDirs) {
+            this.logger.info(`Listing skills in: ${dir}`);
+            try {
+                const entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (!entry.isDirectory()) {
+                        continue;
+                    }
+                    const skillPath = (0, path_1.join)(dir, entry.name);
+                    try {
+                        const metadata = await this.validator.validateOrThrow(skillPath);
+                        // Keep the first discovered skill path (primary directory wins).
+                        if (!skills.has(metadata.name)) {
+                            skills.set(metadata.name, {
+                                name: metadata.name,
+                                description: metadata.description,
+                                path: skillPath,
+                                tool: aiTool
+                            });
+                        }
+                    }
+                    catch {
+                        // Skip invalid entries but log a warning
+                        this.logger.warn(`Skipping invalid skill directory: ${entry.name}`);
+                    }
                 }
             }
-            return skills;
-        }
-        catch (error) {
-            if (error.code === 'ENOENT') {
-                // Directory doesn't exist yet, return empty array
-                this.logger.info('Skills directory does not exist yet');
-                return [];
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    // Directory doesn't exist yet, continue to next candidate
+                    this.logger.info(`Skills directory does not exist yet: ${dir}`);
+                    continue;
+                }
+                throw error;
             }
-            throw error;
         }
+        return Array.from(skills.values());
     }
     /**
      * Uninstall a skill by name
@@ -94,14 +119,13 @@ class SkillsManager {
      * @throws WikiError if skill not found or deletion fails
      */
     async uninstall(name, skillsDir, aiTool = 'claude') {
-        const dir = this.getEffectiveSkillsDir(skillsDir, aiTool);
-        const skillPath = (0, path_1.join)(dir, name);
-        this.logger.info(`Uninstalling skill: ${name} from ${skillPath}`);
-        // Check if skill exists
-        const skills = await this.listInstalled(dir, aiTool);
+        const candidateDirs = this.getCandidateSkillsDirs(skillsDir, aiTool);
+        this.logger.info(`Uninstalling skill: ${name} from ${candidateDirs.join(', ')}`);
+        // Check if skill exists across candidate directories.
+        const skills = await this.listInstalled(skillsDir, aiTool);
         const skill = skills.find(s => s.name === name);
         if (!skill) {
-            throw new errors_1.WikiError(errors_1.ErrorType.NOT_FOUND, `Skill "${name}" not found in ${dir}`);
+            throw new errors_1.WikiError(errors_1.ErrorType.NOT_FOUND, `Skill "${name}" not found in ${candidateDirs.join(', ')}`);
         }
         // Delete the skill directory
         try {

package/dist/ui/prompts.js

@@ -106,7 +106,7 @@ async function promptAiTool() {
         message: 'Select AI tool',
         choices: [
             { value: 'claude', name: 'Claude Code', description: '~/.claude/skills/' },
-            { value: 'codex', name: 'Codex', description: '~/.codex/skills/' },
+            { value: 'codex', name: 'Codex', description: '~/.agents/skills/' },
         ],
         theme: commonTheme,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sstar/skill-install",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Agent Skill installation tool - download, extract, validate, and install skills for Claude Code and Codex",
   "main": "dist/index.js",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "test": "npm run build --silent && node --test tests/**/*.test.js",
     "prepublishOnly": "npm run build",
     "start": "node dist/cli.js",
     "dev": "ts-node src/cli.ts",