skillfish 1.0.15 → 1.0.17

package/README.md

@@ -47,6 +47,7 @@ Learn more at [agentskills.io](https://agentskills.io).
 | Command | Description |
 |---------|-------------|
 | `skillfish add <owner/repo>` | Install skills |
+| `skillfish init` | Create a new skill |
 | `skillfish list` | View installed skills |
 | `skillfish remove [name]` | Remove skills |
 | `skillfish update` | Update installed skills |
@@ -56,8 +57,10 @@ All commands support `--json` for automation.
 ## Examples
 
 ```bash
-skillfish add user/my-skill          # Install a skill
+skillfish add owner/repo             # Install from a repository
 skillfish add owner/repo --all       # Install all skills from repo
+skillfish init                       # Create a new skill (interactive)
+skillfish init --name my-skill       # Create with a specified name
 skillfish list                       # See what's installed
 skillfish update                     # Update all skills
 skillfish remove old-skill           # Remove a skill
@@ -114,6 +117,23 @@ skillfish add owner/repo --project          # Project only (./)
 skillfish add owner/repo --global           # Global only (~/)
 ```
 
+### init
+
+Create a new skill template with `SKILL.md` and optional directories.
+
+```bash
+skillfish init                                  # Interactive skill creation
+skillfish init --name my-skill                  # Specify skill name
+skillfish init --name my-skill --description "Does a thing"  # Non-interactive
+skillfish init --project                        # Create in current project (./)
+skillfish init --global                         # Create in home directory (~/)
+skillfish init --name my-skill --yes            # Skip all prompts
+skillfish init --author "your-name"             # Set author metadata
+skillfish init --license MIT                    # Set license
+```
+
+Interactive mode prompts for name, description, optional metadata (author, license), optional directories (`scripts/`, `references/`, `assets/`), install location, and target agents.
+
 ### list
 
 View installed skills.

package/dist/commands/add.js

@@ -9,7 +9,7 @@ import pc from 'picocolors';
 import { trackInstall } from '../telemetry.js';
 import { isValidPath, parseFrontmatter, deriveSkillName, toTitleCase, truncate, batchMap, createJsonOutput, isInputTTY, isTTY, } from '../utils.js';
 import { getDetectedAgents, AGENT_CONFIGS } from '../lib/agents.js';
-import { findAllSkillMdFiles, fetchSkillMdContent, fetchDefaultBranch, fetchTreeSha, SKILL_FILENAME, RateLimitError, RepoNotFoundError, NetworkError, GitHubApiError, } from '../lib/github.js';
+import { findAllSkillMdFiles, fetchSkillMdContent, fetchDefaultBranch, fetchTreeSha, getSkillSha, SKILL_FILENAME, RateLimitError, RepoNotFoundError, NetworkError, GitHubApiError, } from '../lib/github.js';
 import { installSkill } from '../lib/installer.js';
 import { EXIT_CODES, isValidName } from '../lib/constants.js';
 // === Command Definition ===
@@ -127,11 +127,13 @@ Examples:
                 // If we can't fetch SHA, install without manifest tracking
                 sha = undefined;
             }
-            discoveryResult = { paths: [explicitPath], branch, sha };
+            // For explicit paths, we don't have the tree (would require extra API call)
+            // The sha will be root tree SHA - acceptable for explicit path installs
+            discoveryResult = { paths: [explicitPath], branch, sha, tree: [] };
         }
         catch {
             // If we can't fetch the branch, let degit try its own detection
-            discoveryResult = { paths: [explicitPath], branch: undefined, sha: undefined };
+            discoveryResult = { paths: [explicitPath], branch: undefined, sha: undefined, tree: [] };
         }
     }
     else {
@@ -143,7 +145,7 @@ Examples:
         }
         process.exit(EXIT_CODES.NOT_FOUND);
     }
-    const { paths: skillPaths, branch: discoveredBranch, sha: discoveredSha } = discoveryResult;
+    const { paths: skillPaths, branch: discoveredBranch, sha: discoveredSha, tree: discoveredTree, } = discoveryResult;
     // 2. Determine install location (global vs project)
     const baseDir = await selectInstallLocation(projectFlag, globalFlag, jsonMode);
     // 3. Select agents to install to
@@ -198,11 +200,15 @@ Examples:
             spinner = p.spinner();
             spinner.start(`Downloading ${skillName}...`);
         }
+        // Get directory-specific SHA for better update tracking
+        // skillPath is either 'SKILL.md' or a directory like 'skills/foo'
+        const skillMdPath = skillPath === SKILL_FILENAME ? SKILL_FILENAME : `${skillPath}/${SKILL_FILENAME}`;
+        const skillSha = getSkillSha(discoveredTree, skillMdPath) ?? discoveredSha;
         const result = await installSkill(owner, repo, skillPath, skillName, targetAgents, {
             force,
             baseDir,
             branch: discoveredBranch,
-            sha: discoveredSha,
+            sha: skillSha,
         });
         if (spinner) {
             if (result.failed) {
@@ -383,7 +389,7 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
         }
         process.exit(exitCode);
     }
-    const { paths: skillPaths, branch, sha } = skillDiscovery;
+    const { paths: skillPaths, branch, sha, tree } = skillDiscovery;
     if (skillPaths.length === 0) {
         const errorMsg = `No ${SKILL_FILENAME} found in repository`;
         if (jsonMode) {
@@ -442,7 +448,7 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
             if (!jsonMode) {
                 p.log.info(`${pc.bold(displayName)}${desc ? pc.dim(` - ${desc}`) : ''}`);
             }
-            return { paths: [matchedSkill.dir], branch, sha };
+            return { paths: [matchedSkill.dir], branch, sha, tree };
         }
         // Skill not found - show available skills
         const errorMsg = `Skill "${targetSkillName}" not found in repository`;
@@ -468,7 +474,7 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
         if (!jsonMode) {
             p.log.info(`${pc.bold(displayName)}${desc ? pc.dim(` - ${desc}`) : ''}`);
         }
-        return { paths: [skill.dir], branch, sha };
+        return { paths: [skill.dir], branch, sha, tree };
     }
     // Build options for selection with frontmatter metadata
     // No hints - @clack/prompts has rendering issues with long option lists
@@ -483,7 +489,7 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
             if (!jsonMode) {
                 console.log(`Installing all ${skills.length} skills`);
             }
-            return { paths: skills.map((s) => s.dir), branch, sha };
+            return { paths: skills.map((s) => s.dir), branch, sha, tree };
         }
         // Otherwise, list skills and exit with guidance
         if (jsonMode) {
@@ -511,7 +517,7 @@ async function discoverSkillPaths(owner, repo, installAll, jsonMode, jsonOutput,
         p.cancel('Cancelled');
         process.exit(EXIT_CODES.SUCCESS);
     }
-    return { paths: selected, branch, sha };
+    return { paths: selected, branch, sha, tree };
 }
 /**
  * SECURITY: Show warning and ask for user confirmation before installing.

package/dist/commands/init.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `skillfish init` command - Generate a template skill.
+ */
+import { Command } from 'commander';
+export declare const initCommand: Command;

package/dist/commands/init.js

@@ -0,0 +1,499 @@
+/**
+ * `skillfish init` command - Generate a template skill.
+ */
+import { Command } from 'commander';
+import { homedir } from 'os';
+import { join } from 'path';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { getDetectedAgents, getAgentSkillDir } from '../lib/agents.js';
+import { SKILL_FILENAME } from '../lib/github.js';
+import { EXIT_CODES } from '../lib/constants.js';
+import { isInputTTY, isTTY } from '../utils.js';
+// === Validation ===
+/**
+ * Validates skill name format.
+ * Must be lowercase, use hyphens or underscores, no spaces, no consecutive hyphens.
+ */
+function isValidSkillName(name) {
+    // Must start and end with alphanumeric, contain only lowercase, numbers, hyphens, underscores
+    if (!/^[a-z0-9][a-z0-9_-]*[a-z0-9]$|^[a-z0-9]$/.test(name)) {
+        return false;
+    }
+    // No consecutive hyphens or underscores
+    if (/[-_]{2,}/.test(name)) {
+        return false;
+    }
+    // Reasonable length
+    if (name.length < 1 || name.length > 64) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Convert user input to valid skill name format.
+ */
+function normalizeSkillName(input) {
+    return input
+        .toLowerCase()
+        .trim()
+        .replace(/\s+/g, '-') // spaces to hyphens
+        .replace(/[^a-z0-9_-]/g, '') // remove invalid chars
+        .replace(/[-_]{2,}/g, '-'); // collapse multiple separators
+}
+const OPTIONAL_DIRS = [
+    { value: 'scripts', label: 'scripts/', hint: 'Executable code (Python, Bash, JS)' },
+    { value: 'references', label: 'references/', hint: 'Additional documentation' },
+    { value: 'assets', label: 'assets/', hint: 'Templates, images, data files' },
+];
+/**
+ * Quote a YAML value if it contains characters that could break parsing.
+ * Wraps in double quotes and escapes internal double quotes/backslashes.
+ */
+function yamlQuote(value) {
+    // If the value contains any YAML-special characters, quote it
+    if (/[:#[\]{}&*!|>'"%@`\n\r\\,]/.test(value) || value.startsWith('-') || value.startsWith('?')) {
+        const escaped = value
+            .replace(/\\/g, '\\\\')
+            .replace(/"/g, '\\"')
+            .replace(/\n/g, '\\n')
+            .replace(/\r/g, '\\r');
+        return `"${escaped}"`;
+    }
+    return value;
+}
+/**
+ * Generate SKILL.md content with frontmatter and template.
+ */
+function generateSkillMd(meta, dirs) {
+    const frontmatterLines = [
+        '---',
+        `name: ${yamlQuote(meta.name)}`,
+        `description: ${yamlQuote(meta.description)}`,
+    ];
+    if (meta.license) {
+        frontmatterLines.push(`license: ${yamlQuote(meta.license)}`);
+    }
+    if (meta.author || meta.version) {
+        frontmatterLines.push('metadata:');
+        if (meta.author) {
+            frontmatterLines.push(`  author: ${yamlQuote(meta.author)}`);
+        }
+        if (meta.version) {
+            frontmatterLines.push(`  version: ${yamlQuote(meta.version)}`);
+        }
+    }
+    frontmatterLines.push('---');
+    const sections = [
+        `${frontmatterLines.join('\n')}`,
+        `# ${meta.name}`,
+        meta.description,
+        `## Instructions\n\n<!-- Add your skill instructions here. This is what the AI agent will read and follow. -->`,
+        `## Examples\n\n<!-- Provide examples of how this skill should be used. -->`,
+    ];
+    if (dirs.includes('references')) {
+        sections.push(`## References\n\n<!-- Reference additional docs from the references/ directory. -->\n<!-- Example: See [detailed guide](references/REFERENCE.md) for more info. -->`);
+    }
+    else {
+        sections.push(`## References\n\n<!-- Link to documentation, APIs, or other resources the agent might need. -->`);
+    }
+    if (dirs.includes('scripts')) {
+        sections.push(`## Scripts\n\n<!-- Executable code is available in the scripts/ directory. -->\n<!-- Example: Run scripts/setup.sh to configure the environment. -->`);
+    }
+    return sections.join('\n\n') + '\n';
+}
+// === Command Definition ===
+export const initCommand = new Command('init')
+    .description('Create a new skill template')
+    .option('--name <name>', 'Skill name (lowercase, hyphens)')
+    .option('--description <desc>', 'Skill description')
+    .option('--author <author>', 'Skill author')
+    .option('--version <version>', 'Skill version (default: 1.0.0)')
+    .option('--license <license>', 'Skill license (e.g., MIT, Apache-2.0)')
+    .option('-y, --yes', 'Skip confirmation prompts')
+    .option('--project', 'Create in current project (./.claude)')
+    .option('--global', 'Create in home directory (~/.claude)')
+    .helpOption('-h, --help', 'Display help for command')
+    .addHelpText('after', `
+Examples:
+  $ skillfish init                            Interactive skill creation
+  $ skillfish init --name my-skill            Create skill with specified name
+  $ skillfish init --project                  Create in current project
+  $ skillfish init --name my-skill --yes      Non-interactive creation`)
+    .action(async (options, command) => {
+    const jsonMode = command.parent?.opts().json ?? false;
+    const version = command.parent?.opts().version ?? '0.0.0';
+    // JSON output state
+    const jsonOutput = {
+        success: true,
+        errors: [],
+        created: [],
+        skipped: [],
+    };
+    function addError(message) {
+        jsonOutput.errors.push(message);
+        jsonOutput.success = false;
+    }
+    function outputJsonAndExit(exitCode) {
+        jsonOutput.exit_code = exitCode;
+        console.log(JSON.stringify(jsonOutput, null, 2));
+        process.exit(exitCode);
+    }
+    function exitWithError(message, exitCode, useClackLog = false) {
+        if (jsonMode) {
+            addError(message);
+            outputJsonAndExit(exitCode);
+        }
+        if (useClackLog) {
+            p.log.error(message);
+        }
+        else {
+            console.error(message);
+        }
+        process.exit(exitCode);
+    }
+    // Show banner and intro (TTY only, not in JSON mode)
+    if (isTTY() && !jsonMode) {
+        console.log();
+        console.log(pc.cyan('     ≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋'));
+        console.log(`       ${pc.cyan('><>')}  ${pc.bold('SKILL FISH')}  ${pc.cyan('><>')}`);
+        console.log(pc.cyan('     ≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋≋'));
+        console.log();
+        p.intro(`${pc.bgCyan(pc.black(' skillfish '))} ${pc.dim(`v${version}`)} ${pc.dim('· Create a skill')}`);
+    }
+    const skipPrompts = options.yes ?? false;
+    const projectFlag = options.project ?? false;
+    const globalFlag = options.global ?? false;
+    if (projectFlag && globalFlag) {
+        exitWithError('Cannot use both --project and --global. Choose one.', EXIT_CODES.INVALID_ARGS);
+    }
+    // 1. Get skill name
+    let skillName;
+    if (options.name) {
+        // Validate provided name
+        const normalized = normalizeSkillName(options.name);
+        if (!isValidSkillName(normalized)) {
+            exitWithError('Invalid skill name. Use lowercase letters, numbers, and hyphens (e.g., my-skill).', EXIT_CODES.INVALID_ARGS);
+        }
+        skillName = normalized;
+    }
+    else if (!isInputTTY() || jsonMode) {
+        exitWithError('Skill name is required. Use --name <name> in non-interactive mode.', EXIT_CODES.INVALID_ARGS);
+    }
+    else {
+        // Interactive prompt for skill name
+        const nameInput = await p.text({
+            message: 'Skill name',
+            placeholder: 'my-skill',
+            validate: (value) => {
+                const normalized = normalizeSkillName(value);
+                if (!normalized) {
+                    return 'Skill name is required';
+                }
+                if (!isValidSkillName(normalized)) {
+                    return 'Use lowercase letters, numbers, and hyphens (e.g., my-skill)';
+                }
+            },
+        });
+        if (p.isCancel(nameInput)) {
+            p.cancel('Cancelled');
+            process.exit(EXIT_CODES.SUCCESS);
+        }
+        skillName = normalizeSkillName(nameInput);
+    }
+    // 2. Get skill description
+    let skillDescription;
+    if (options.description) {
+        skillDescription = options.description;
+    }
+    else if (!isInputTTY() || jsonMode) {
+        exitWithError('Skill description is required. Use --description <desc> in non-interactive mode.', EXIT_CODES.INVALID_ARGS);
+    }
+    else {
+        const descInput = await p.text({
+            message: 'Description',
+            placeholder: 'What does this skill do?',
+            validate: (value) => {
+                if (!value.trim()) {
+                    return 'Description is required';
+                }
+            },
+        });
+        if (p.isCancel(descInput)) {
+            p.cancel('Cancelled');
+            process.exit(EXIT_CODES.SUCCESS);
+        }
+        skillDescription = descInput.trim();
+    }
+    // 3. Optional metadata (author, version, license) - only prompt interactively
+    let author = options.author;
+    let skillVersion = options.version || '1.0.0';
+    let license = options.license;
+    if (isInputTTY() && !jsonMode && !skipPrompts) {
+        const addMetadata = await p.confirm({
+            message: 'Add optional metadata (author, license)?',
+            initialValue: false,
+        });
+        if (p.isCancel(addMetadata)) {
+            p.cancel('Cancelled');
+            process.exit(EXIT_CODES.SUCCESS);
+        }
+        if (addMetadata) {
+            const authorInput = await p.text({
+                message: 'Author',
+                placeholder: 'your-name or your-org (optional)',
+            });
+            if (p.isCancel(authorInput)) {
+                p.cancel('Cancelled');
+                process.exit(EXIT_CODES.SUCCESS);
+            }
+            author = authorInput.trim() || undefined;
+            const licenseInput = await p.select({
+                message: 'License',
+                options: [
+                    { value: '', label: 'None' },
+                    { value: 'MIT', label: 'MIT' },
+                    { value: 'Apache-2.0', label: 'Apache-2.0' },
+                    { value: 'BSD-3-Clause', label: 'BSD-3-Clause' },
+                    { value: 'GPL-3.0', label: 'GPL-3.0' },
+                    { value: 'AGPL-3.0', label: 'AGPL-3.0' },
+                    { value: 'Unlicense', label: 'Unlicense' },
+                ],
+            });
+            if (p.isCancel(licenseInput)) {
+                p.cancel('Cancelled');
+                process.exit(EXIT_CODES.SUCCESS);
+            }
+            license = licenseInput || undefined;
+        }
+    }
+    // 4. Select optional directories
+    let optionalDirs = [];
+    if (isInputTTY() && !jsonMode && !skipPrompts) {
+        const addDirs = await p.confirm({
+            message: 'Include optional directories (scripts/, references/, assets/)?',
+            initialValue: false,
+        });
+        if (p.isCancel(addDirs)) {
+            p.cancel('Cancelled');
+            process.exit(EXIT_CODES.SUCCESS);
+        }
+        if (addDirs) {
+            const selected = await p.multiselect({
+                message: 'Select directories to include',
+                options: OPTIONAL_DIRS.map((d) => ({
+                    value: d.value,
+                    label: d.label,
+                    hint: d.hint,
+                })),
+                required: false,
+            });
+            if (p.isCancel(selected)) {
+                p.cancel('Cancelled');
+                process.exit(EXIT_CODES.SUCCESS);
+            }
+            optionalDirs = selected;
+        }
+    }
+    // 5. Determine install location (global vs project)
+    const baseDir = await selectInstallLocation(projectFlag, globalFlag, jsonMode);
+    // 6. Select agents to create skill for
+    const detected = getDetectedAgents();
+    if (detected.length === 0) {
+        const errorMsg = 'No agents detected. Install Claude Code, Cursor, or another supported agent first.';
+        if (jsonMode) {
+            addError(errorMsg);
+            outputJsonAndExit(EXIT_CODES.GENERAL_ERROR);
+        }
+        p.log.error(errorMsg);
+        p.outro(pc.dim('https://skill.fish/agents'));
+        process.exit(EXIT_CODES.GENERAL_ERROR);
+    }
+    let targetAgents;
+    if (!isInputTTY() || jsonMode || skipPrompts) {
+        // Non-TTY or JSON mode or --yes: use all detected agents
+        if (!jsonMode) {
+            console.log(`Creating for ${detected.length} agent(s): ${detected.map((a) => a.name).join(', ')}`);
+        }
+        targetAgents = detected;
+    }
+    else {
+        // Interactive: let user choose from detected agents
+        const isLocal = baseDir !== homedir();
+        targetAgents = await selectAgents(detected, isLocal, jsonMode);
+    }
+    // 7. Create the skill
+    const skillMeta = {
+        name: skillName,
+        description: skillDescription,
+        author,
+        version: skillVersion,
+        license,
+    };
+    const skillContent = generateSkillMd(skillMeta, optionalDirs);
+    const isLocal = baseDir !== homedir();
+    const pathPrefix = isLocal ? '.' : '~';
+    if (!jsonMode) {
+        p.log.step(`Creating ${pc.bold(skillName)}`);
+    }
+    let created = 0;
+    let skipped = 0;
+    for (const agent of targetAgents) {
+        const skillDir = join(getAgentSkillDir(agent, baseDir), skillName);
+        const skillFilePath = join(skillDir, SKILL_FILENAME);
+        // Check if skill already exists
+        if (existsSync(skillFilePath)) {
+            if (!jsonMode) {
+                console.log(`  ${pc.yellow('●')} ${agent.name} ${pc.dim('(already exists)')}`);
+            }
+            jsonOutput.skipped.push({
+                skill: skillName,
+                agent: agent.name,
+                reason: 'Already exists',
+            });
+            skipped++;
+            continue;
+        }
+        // Create skill directory and SKILL.md
+        try {
+            mkdirSync(skillDir, { recursive: true, mode: 0o700 });
+            writeFileSync(skillFilePath, skillContent, { mode: 0o600 });
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            if (!jsonMode) {
+                console.log(`  ${pc.red('✗')} ${agent.name} ${pc.dim(`(${errMsg})`)}`);
+            }
+            addError(`Failed to create skill for ${agent.name}: ${errMsg}`);
+            continue;
+        }
+        // Create optional directories (non-fatal — SKILL.md is already written)
+        for (const dir of optionalDirs) {
+            try {
+                mkdirSync(join(skillDir, dir), { recursive: true, mode: 0o700 });
+            }
+            catch (err) {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                if (!jsonMode) {
+                    console.log(`  ${pc.yellow('!')} ${agent.name}: failed to create ${dir}/ ${pc.dim(`(${errMsg})`)}`);
+                }
+                jsonOutput.errors.push(`Failed to create ${dir}/ for ${agent.name}: ${errMsg}`);
+            }
+        }
+        const displayPath = `${pathPrefix}/${agent.dir}/${skillName}`;
+        if (!jsonMode) {
+            console.log(`  ${pc.green('✓')} ${agent.name} ${pc.dim(`→ ${displayPath}`)}`);
+        }
+        jsonOutput.created.push({
+            skill: skillName,
+            agent: agent.name,
+            path: skillDir,
+        });
+        created++;
+    }
+    // Summary
+    if (jsonMode) {
+        outputJsonAndExit(jsonOutput.success ? EXIT_CODES.SUCCESS : EXIT_CODES.GENERAL_ERROR);
+    }
+    console.log();
+    if (created > 0) {
+        p.log.success(`Created ${pc.bold(skillName)}`);
+        console.log();
+        console.log(pc.dim('  Next steps:'));
+        console.log(pc.dim(`  1. Edit ${SKILL_FILENAME} to add your instructions`));
+        if (optionalDirs.length > 0) {
+            console.log(pc.dim(`  2. Add files to ${optionalDirs.map((d) => `${d}/`).join(', ')}`));
+            console.log(pc.dim('  3. Test with your AI agent'));
+            console.log(pc.dim('  4. Share on skill.fish or GitHub'));
+        }
+        else {
+            console.log(pc.dim('  2. Test with your AI agent'));
+            console.log(pc.dim('  3. Share on skill.fish or GitHub'));
+        }
+        console.log();
+        p.outro(pc.green(`Done! Created ${created} skill${created === 1 ? '' : 's'}`));
+    }
+    else if (skipped > 0) {
+        p.outro(pc.yellow(`Skill "${skillName}" already exists for all selected agents`));
+    }
+    else {
+        p.outro(pc.yellow('No skills created'));
+    }
+    process.exit(created > 0 || skipped > 0 ? EXIT_CODES.SUCCESS : EXIT_CODES.GENERAL_ERROR);
+});
+// === Helper Functions ===
+async function selectInstallLocation(projectFlag, globalFlag, jsonMode) {
+    // If flag specified, use it
+    if (projectFlag) {
+        if (!jsonMode) {
+            p.log.info(`Location: ${pc.cyan('Project')} ${pc.dim('(current directory)')}`);
+        }
+        return process.cwd();
+    }
+    if (globalFlag) {
+        if (!jsonMode) {
+            p.log.info(`Location: ${pc.cyan('Global')} ${pc.dim('(home directory)')}`);
+        }
+        return homedir();
+    }
+    // Non-TTY or JSON mode defaults to project (more common for init)
+    if (!isInputTTY() || jsonMode) {
+        return process.cwd();
+    }
+    // Interactive selection
+    const location = await p.select({
+        message: 'Install location',
+        options: [
+            {
+                value: 'project',
+                label: 'Project',
+                hint: 'For this project only (recommended)',
+            },
+            {
+                value: 'global',
+                label: 'Global',
+                hint: 'Available in all projects',
+            },
+        ],
+    });
+    if (p.isCancel(location)) {
+        p.cancel('Cancelled');
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    return location === 'project' ? process.cwd() : homedir();
+}
+async function selectAgents(agents, isLocal, jsonMode) {
+    const pathPrefix = isLocal ? '.' : '~';
+    // Show detected agents
+    if (!jsonMode) {
+        p.log.info(`Detected ${pc.cyan(agents.length.toString())} agent${agents.length === 1 ? '' : 's'}: ${agents.map((a) => a.name).join(', ')}`);
+    }
+    const installAll = await p.confirm({
+        message: 'Create for all detected agents?',
+        initialValue: true,
+    });
+    if (p.isCancel(installAll)) {
+        p.cancel('Cancelled');
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    if (installAll) {
+        return agents;
+    }
+    // User wants to choose specific agents
+    const options = agents.map((a) => ({
+        value: a.name,
+        label: a.name,
+        hint: `${pathPrefix}/${a.dir}`,
+    }));
+    const selected = await p.multiselect({
+        message: 'Select agents',
+        options,
+        required: true,
+    });
+    if (p.isCancel(selected)) {
+        p.cancel('Cancelled');
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    return agents.filter((a) => selected.includes(a.name));
+}

package/dist/commands/update.js

@@ -9,7 +9,7 @@ import pc from 'picocolors';
 import { getDetectedAgents, getAgentSkillDir } from '../lib/agents.js';
 import { listInstalledSkillsInDir, installSkill } from '../lib/installer.js';
 import { readManifest } from '../lib/manifest.js';
-import { fetchTreeSha, RateLimitError, RepoNotFoundError, NetworkError, GitHubApiError, } from '../lib/github.js';
+import { fetchRecursiveTree, getSkillSha, RateLimitError, RepoNotFoundError, NetworkError, GitHubApiError, } from '../lib/github.js';
 import { EXIT_CODES } from '../lib/constants.js';
 import { isInputTTY, isTTY } from '../utils.js';
 // === Command Definition ===
@@ -260,14 +260,15 @@ function collectTrackedSkills(agents) {
 }
 /**
  * Check which tracked skills have updates available.
- * Caches tree SHA lookups to avoid duplicate API calls for skills from the same repo.
+ * Caches recursive tree lookups to avoid duplicate API calls for skills from the same repo.
+ * Uses directory-level SHA comparison for accurate change detection.
  */
 async function checkForUpdates(skills) {
     const outdated = [];
     const errors = [];
     let rateLimitHit = false;
-    // Cache tree SHA lookups by owner/repo/branch to avoid duplicate API calls
-    const shaCache = new Map();
+    // Cache full tree lookups by owner/repo/branch to avoid duplicate API calls
+    const treeCache = new Map();
     const errorCache = new Map();
     for (const skill of skills) {
         const cacheKey = `${skill.manifest.owner}/${skill.manifest.repo}/${skill.manifest.branch}`;
@@ -288,12 +289,13 @@ async function checkForUpdates(skills) {
             }
             continue;
         }
-        // Check if we already have a cached SHA for this repo
-        let remoteSha = shaCache.get(cacheKey);
-        if (!remoteSha) {
+        // Check if we already have a cached tree for this repo
+        let cached = treeCache.get(cacheKey);
+        if (!cached) {
             try {
-                remoteSha = await fetchTreeSha(skill.manifest.owner, skill.manifest.repo, skill.manifest.branch);
-                shaCache.set(cacheKey, remoteSha);
+                const { sha, tree } = await fetchRecursiveTree(skill.manifest.owner, skill.manifest.repo, skill.manifest.branch);
+                cached = { rootSha: sha, tree };
+                treeCache.set(cacheKey, cached);
             }
             catch (err) {
                 if (err instanceof RateLimitError) {
@@ -319,6 +321,9 @@ async function checkForUpdates(skills) {
                 continue;
             }
         }
+        // Get directory-specific SHA for accurate change detection
+        // Falls back to root SHA for backward compatibility with old manifests
+        const remoteSha = getSkillSha(cached.tree, skill.manifest.path) ?? cached.rootSha;
         if (skill.manifest.sha !== remoteSha) {
             outdated.push({ ...skill, remoteSha });
         }

package/dist/index.js

@@ -10,6 +10,7 @@ import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import updateNotifier from 'update-notifier';
 import { addCommand } from './commands/add.js';
+import { initCommand } from './commands/init.js';
 import { listCommand } from './commands/list.js';
 import { removeCommand } from './commands/remove.js';
 import { updateCommand } from './commands/update.js';
@@ -37,6 +38,7 @@ const program = new Command()
 Examples:
   $ skillfish add owner/repo                 Install skills from a repository
   $ skillfish add owner/repo/plugin/skill    Install a specific skill
+  $ skillfish init                           Create a new skill template
   $ skillfish list                           Show installed skills
   $ skillfish remove my-skill                Remove a skill
 
@@ -47,6 +49,7 @@ program.hook('preAction', (thisCommand) => {
 });
 // Add subcommands
 program.addCommand(addCommand);
+program.addCommand(initCommand);
 program.addCommand(listCommand);
 program.addCommand(removeCommand);
 program.addCommand(updateCommand);

package/dist/lib/github.d.ts

@@ -1,6 +1,7 @@
 /**
  * GitHub API functions for skill discovery and fetching.
  */
+import { type GitTreeItem } from '../utils.js';
 export declare const SKILL_FILENAME = "SKILL.md";
 /**
  * Result of skill discovery including branch and SHA information.
@@ -8,9 +9,20 @@ export declare const SKILL_FILENAME = "SKILL.md";
 export interface SkillDiscoveryResult {
     paths: string[];
     branch: string;
-    /** Tree SHA from git/trees response - changes when any file in repo changes */
+    /** Root tree SHA from git/trees response - changes when any file in repo changes */
     sha: string;
+    /** Raw tree items for directory-level SHA lookups */
+    tree: GitTreeItem[];
 }
+/**
+ * Get the SHA for a skill path from a git tree.
+ * - For subdirectory skills: returns the directory's tree SHA
+ * - For root-level skills: returns the SKILL.md blob SHA
+ *
+ * This enables directory-level change detection instead of repo-level,
+ * reducing false "outdated" notifications when unrelated files change.
+ */
+export declare function getSkillSha(tree: GitTreeItem[], skillPath: string): string | undefined;
 /**
  * Thrown when GitHub API rate limit is exceeded.
  */
@@ -67,6 +79,19 @@ export declare function fetchSkillMdContent(owner: string, repo: string, path: s
  * @throws {GitHubApiError} When the API response format is unexpected
  */
 export declare function fetchTreeSha(owner: string, repo: string, branch: string): Promise<string>;
+/**
+ * Fetch the recursive tree for a repository branch.
+ * Returns both the root SHA and the full tree for directory-level SHA lookups.
+ *
+ * @throws {RepoNotFoundError} When the repository is not found
+ * @throws {RateLimitError} When GitHub API rate limit is exceeded
+ * @throws {NetworkError} On network errors
+ * @throws {GitHubApiError} When the API response format is unexpected
+ */
+export declare function fetchRecursiveTree(owner: string, repo: string, branch: string): Promise<{
+    sha: string;
+    tree: GitTreeItem[];
+}>;
 /**
  * Find all SKILL.md files in a GitHub repository.
  * Fetches the default branch, then searches for skills on that branch.

package/dist/lib/github.js

@@ -7,6 +7,26 @@ const API_TIMEOUT_MS = 10000;
 const MAX_RETRIES = 3;
 const RETRY_DELAYS_MS = [1000, 2000, 4000]; // Exponential backoff
 export const SKILL_FILENAME = 'SKILL.md';
+// === Helper Functions ===
+/**
+ * Get the SHA for a skill path from a git tree.
+ * - For subdirectory skills: returns the directory's tree SHA
+ * - For root-level skills: returns the SKILL.md blob SHA
+ *
+ * This enables directory-level change detection instead of repo-level,
+ * reducing false "outdated" notifications when unrelated files change.
+ */
+export function getSkillSha(tree, skillPath) {
+    // Root-level skill - use the blob SHA of SKILL.md itself
+    if (skillPath === SKILL_FILENAME) {
+        const blob = tree.find((item) => item.path === SKILL_FILENAME && item.type === 'blob');
+        return blob?.sha;
+    }
+    // Subdirectory skill - use the directory's tree SHA
+    const dirPath = skillPath.replace(/\/SKILL\.md$/, '');
+    const dir = tree.find((item) => item.path === dirPath && item.type === 'tree');
+    return dir?.sha;
+}
 // === Error Types ===
 /**
  * Thrown when GitHub API rate limit is exceeded.
@@ -208,25 +228,25 @@ export async function fetchTreeSha(owner, repo, branch) {
     }
 }
 /**
- * Find all SKILL.md files in a GitHub repository.
- * Fetches the default branch, then searches for skills on that branch.
+ * Fetch the recursive tree for a repository branch.
+ * Returns both the root SHA and the full tree for directory-level SHA lookups.
  *
- * @returns SkillDiscoveryResult with paths and the branch they were found on
- * @throws {RateLimitError} When GitHub API rate limit is exceeded
  * @throws {RepoNotFoundError} When the repository is not found
- * @throws {NetworkError} On network errors (timeout, connection refused)
+ * @throws {RateLimitError} When GitHub API rate limit is exceeded
+ * @throws {NetworkError} On network errors
  * @throws {GitHubApiError} When the API response format is unexpected
  */
-export async function findAllSkillMdFiles(owner, repo) {
+export async function fetchRecursiveTree(owner, repo, branch) {
     const headers = { 'User-Agent': 'skillfish' };
-    // Get the default branch
-    const branch = await fetchDefaultBranch(owner, repo);
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), API_TIMEOUT_MS);
     try {
         const url = `https://api.github.com/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`;
         const res = await fetchWithRetry(url, { headers, signal: controller.signal });
         checkRateLimit(res);
+        if (res.status === 404) {
+            throw new RepoNotFoundError(owner, repo);
+        }
         if (!res.ok) {
             throw new GitHubApiError(`GitHub API returned status ${res.status}`);
         }
@@ -234,9 +254,12 @@ export async function findAllSkillMdFiles(owner, repo) {
         if (!isGitTreeResponse(rawData)) {
             throw new GitHubApiError('Unexpected response format from GitHub API.');
         }
-        const paths = extractSkillPaths(rawData, SKILL_FILENAME);
-        const sha = rawData.sha ?? '';
-        return { paths, branch, sha };
+        const sha = rawData.sha;
+        if (typeof sha !== 'string' || !/^[a-f0-9]{40}$/.test(sha)) {
+            throw new GitHubApiError('Invalid or missing sha field in tree response');
+        }
+        const tree = rawData.tree ?? [];
+        return { sha, tree };
     }
     catch (err) {
         wrapApiError(err);
@@ -245,3 +268,22 @@ export async function findAllSkillMdFiles(owner, repo) {
         clearTimeout(timeoutId);
     }
 }
+/**
+ * Find all SKILL.md files in a GitHub repository.
+ * Fetches the default branch, then searches for skills on that branch.
+ *
+ * @returns SkillDiscoveryResult with paths and the branch they were found on
+ * @throws {RateLimitError} When GitHub API rate limit is exceeded
+ * @throws {RepoNotFoundError} When the repository is not found
+ * @throws {NetworkError} On network errors (timeout, connection refused)
+ * @throws {GitHubApiError} When the API response format is unexpected
+ */
+export async function findAllSkillMdFiles(owner, repo) {
+    // Get the default branch
+    const branch = await fetchDefaultBranch(owner, repo);
+    // Fetch the recursive tree (reuses fetchRecursiveTree to avoid duplication)
+    const { sha, tree } = await fetchRecursiveTree(owner, repo, branch);
+    // Extract SKILL.md paths from the tree
+    const paths = extractSkillPaths({ tree }, SKILL_FILENAME);
+    return { paths, branch, sha, tree };
+}

package/dist/utils.d.ts

@@ -133,6 +133,21 @@ export interface UpdateJsonOutput extends BaseJsonOutput {
     outdated: OutdatedSkill[];
     updated: InstalledSkill[];
 }
+/**
+ * JSON output for the `init` command.
+ */
+export interface InitJsonOutput extends BaseJsonOutput {
+    created: {
+        skill: string;
+        agent: string;
+        path: string;
+    }[];
+    skipped: {
+        skill: string;
+        agent: string;
+        reason: string;
+    }[];
+}
 /** @deprecated Use AddJsonOutput instead */
 export type JsonOutput = AddJsonOutput;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillfish",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "All in one Skill manager for AI coding agents. Install, update, and sync Skills across Claude Code, Cursor, Copilot + more.",
   "type": "module",
   "bin": {
@@ -76,7 +76,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
-    "@types/node": "^20.0.0",
+    "@types/node": "^25.0.10",
     "@types/update-notifier": "^6.0.8",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",