skillfish 1.0.10 → 1.0.12

package/README.md

@@ -10,15 +10,69 @@
   <a href="https://github.com/knoxgraeme/skillfish/actions"><img src="https://github.com/knoxgraeme/skillfish/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
 </p>
 
-Install AI agent skills from GitHub with a single command.
+<p align="center">
+  <strong>The skill manager for AI coding agents.</strong><br>
+  Install, update, and sync skills across Claude Code, Cursor, Copilot + more.
+</p>
+
+---
+
+## Quick Start
 
 ```bash
+# One-off skill installation
 npx skillfish add owner/repo
+
+# For ongoing skill management, install globally
+npm i -g skillfish
+skillfish list
+skillfish update
+```
+
+One command installs to **all detected agents** on your system.
+
+## What Are Agent Skills?
+
+Agent Skills are portable packages of instructions, prompts, scripts, and resources that AI coding agents can discover and use. They give agents like Claude Code, Cursor, and Copilot domain expertise, reusable workflows, and team-specific context - loaded on demand to extend capabilities.
+
+Each skill contains a `SKILL.md` file with structured prompts and instructions the agent can follow.
+
+Learn more at [agentskills.io](https://agentskills.io).
+
+## Find Skills
+
+- **[skill.fish](https://skill.fish)** - Browse and discover community skills
+- **[MCP Market](https://mcpmarket.com/tools/skills)** - Skills directory
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `skillfish add <owner/repo>` | Install skills |
+| `skillfish list` | View installed skills |
+| `skillfish remove [name]` | Remove skills |
+| `skillfish update` | Update installed skills |
+
+All commands support `--json` for automation.
+
+## Examples
+
+```bash
+skillfish add user/my-skill          # Install a skill
+skillfish add owner/repo --all       # Install all skills from repo
+skillfish list                       # See what's installed
+skillfish update                     # Update all skills
+skillfish remove old-skill           # Remove a skill
 ```
 
-## Overview
+## Supported Agents
 
-One command installs skills to **all detected agents**:
+Works with 17+ agents including:
+
+**Claude Code** · **Cursor** · **Windsurf** · **Codex** · **GitHub Copilot** · **Gemini CLI** · **OpenCode** · **Goose** · **Amp** · **Roo Code** · **Kiro CLI** · **Kilo Code** · **Trae** · **Cline** · **Antigravity** · **Droid** · **Clawdbot**
+
+<details>
+<summary>All supported agents</summary>
 
 | Agent | Skills Directory |
 |-------|------------------|
@@ -40,141 +94,65 @@ One command installs skills to **all detected agents**:
 | Droid | `~/.factory/skills/` |
 | Clawdbot | `~/.clawdbot/skills/` |
 
-## Usage
-
-### Install Skills
-
-```bash
-# Install a skill (auto-discovers SKILL.md location)
-npx skillfish add owner/repo
-
-# Full path from GitHub (plugin/skill syntax)
-npx skillfish add owner/repo/plugin/skill
-
-# Specify explicit path
-npx skillfish add owner/repo --path path/to/skill
-
-# Install all skills from a repo (non-interactive)
-npx skillfish add owner/repo --all
-
-# Overwrite existing skills
-npx skillfish add owner/repo --force
-
-# Skip confirmation prompt
-npx skillfish add owner/repo --yes
-```
-
-### List Skills
-
-```bash
-# Interactive agent and location picker
-npx skillfish list
+</details>
 
-# List global skills only
-npx skillfish list --global
+---
 
-# List project skills only
-npx skillfish list --project
+## Command Reference
 
-# List skills for a specific agent
-npx skillfish list --agent "Claude Code"
-```
+### add
 
-### Remove Skills
+Install skills from a repository.
 
 ```bash
-# Interactive skill picker
-npx skillfish remove
-
-# Remove a skill by name
-npx skillfish remove my-skill
-
-# Remove all installed skills
-npx skillfish remove --all
-
-# Remove from current project only
-npx skillfish remove my-skill --project
-
-# Remove from home directory only
-npx skillfish remove my-skill --global
-
-# Remove from specific agent
-npx skillfish remove my-skill --agent "Claude Code"
-
-# Skip confirmation prompt
-npx skillfish remove my-skill --yes
+skillfish add owner/repo                    # Auto-discover SKILL.md
+skillfish add owner/repo my-skill           # Install by skill name
+skillfish add owner/repo/path/to/skill      # Full path syntax
+skillfish add owner/repo --path skills/foo  # Explicit path
+skillfish add owner/repo --all              # Install all skills
+skillfish add owner/repo --force            # Overwrite existing
+skillfish add owner/repo --yes              # Skip confirmation
+skillfish add owner/repo --project          # Project only (./)
+skillfish add owner/repo --global           # Global only (~/)
 ```
 
-## Interactive Selection
+### list
 
-When a repo contains multiple skills, you'll get an interactive multi-select menu with skill names and descriptions from frontmatter:
+View installed skills.
 
-```
-◆  Select skills to install
-│  ◻ my-skill - A helpful skill for your AI agent
-│  ◻ another-skill - Another useful capability
-│  ◻ third-skill - Yet another skill option
-│  ...
-└
+```bash
+skillfish list                       # List all installed skills
+skillfish list --global              # Global skills only (~/)
+skillfish list --project             # Project skills only (./)
+skillfish list --agent "Claude Code" # Specific agent
 ```
 
-Use `--all` to install all skills non-interactively (useful for automation).
+### remove
 
-## Examples
+Remove installed skills.
 
 ```bash
-# Install from a skill repo with SKILL.md at root
-npx skillfish add user/my-skill
-
-# Install using full path from GitHub
-npx skillfish add owner/repo/path/to/skill
-
-# Install from a plugin repo with explicit path
-npx skillfish add org/plugin-repo --path plugins/my-plugin/skills/skill-name
-
-# Install all skills non-interactively
-npx skillfish add org/plugin-repo --all --yes
-
-# Force reinstall
-npx skillfish add user/skill --force
-
-# JSON output for automation
-npx skillfish add owner/repo --json
+skillfish remove                          # Interactive picker
+skillfish remove my-skill                 # By name
+skillfish remove --all                    # Remove all
+skillfish remove my-skill --project       # Project only
+skillfish remove my-skill --global        # Global only
+skillfish remove my-skill --agent "Cursor" # Specific agent
+skillfish remove my-skill --yes           # Skip confirmation
 ```
 
-## Discovery
-
-The CLI searches these locations for `SKILL.md`:
-1. Repository root
-2. `.claude/skills/{repo}/`
-3. `skills/{repo}/`
-4. `plugins/{repo}/skills/{repo}/`
-
-Use `--path` to skip discovery and specify the exact location.
-
-## Telemetry
-
-This CLI collects anonymous, aggregate install counts to understand skill popularity. No personally identifiable information is collected.
-
-**What is collected:**
-- Skill identifier (e.g., `owner/repo/skill-name`)
-- Incremented install count
-
-**What is NOT collected:**
-- IP addresses
-- User identifiers
-- System information
-- Usage patterns
+### update
 
-To opt out, set `DO_NOT_TRACK=1` in your environment:
+Update installed skills to latest version.
 
 ```bash
-DO_NOT_TRACK=1 npx skillfish add owner/repo
+skillfish update                     # Check for updates interactively
+skillfish update --yes               # Update all without prompting
+skillfish update --json              # Check for updates (JSON output)
 ```
 
-Telemetry is also automatically disabled in CI environments (`CI=true`).
-
-## Exit Codes
+<details>
+<summary>Exit Codes</summary>
 
 Exit codes help agents and scripts understand command results without parsing error messages.
 
@@ -193,22 +171,33 @@ skillfish add owner/repo --json
 # Output includes: "exit_code": 0 (or error code)
 ```
 
+</details>
+
+---
+
 ## Security
 
-**Security Note:** Skills are markdown files that provide instructions to AI agents. Always review skills before installing. skillfish does not vet third-party skills.
+Skills are markdown files that provide instructions to AI agents. Always review skills before installing. skillfish does not vet third-party skills.
 
-To report security vulnerabilities, please email security@skill.fish. See [SECURITY.md](SECURITY.md) for details.
+To report vulnerabilities, email security@skill.fish. See [SECURITY.md](SECURITY.md).
 
 ## Contributing
 
-Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md) for release history.
 
+<details>
+<summary>Telemetry</summary>
+
+Anonymous, aggregate install counts only. No PII collected.
+
+To opt out: `DO_NOT_TRACK=1` or `CI=true`.
+
+</details>
+
 ## License
 
 [AGPL-3.0](LICENSE) - Graeme Knox

package/dist/index.js

@@ -8,6 +8,7 @@ import { Command } from 'commander';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import updateNotifier from 'update-notifier';
 import { addCommand } from './commands/add.js';
 import { listCommand } from './commands/list.js';
 import { removeCommand } from './commands/remove.js';
@@ -15,6 +16,8 @@ import { updateCommand } from './commands/update.js';
 // Read version from package.json (single source of truth)
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+// Check for updates (runs in background, non-blocking)
+const notifier = updateNotifier({ pkg });
 const program = new Command()
     .name('skillfish')
     .description('Install and manage AI agent skills from GitHub repositories')
@@ -52,7 +55,17 @@ program.on('option:json', () => {
     // JSON mode is handled by commands
 });
 // Parse and run
-program.parseAsync(process.argv).catch((err) => {
+program
+    .parseAsync(process.argv)
+    .then(() => {
+    // Show update notification after command completes (if update available)
+    notifier.notify({
+        message: `Update available: {currentVersion} → {latestVersion}
+Run: npx skillfish@latest
+Or:  npm i -g skillfish`,
+    });
+})
+    .catch((err) => {
     console.error('Error:', err instanceof Error ? err.message : String(err));
     process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillfish",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Install AI agent skills from GitHub with a single command",
   "type": "module",
   "bin": {
@@ -71,11 +71,13 @@
     "@clack/prompts": "^0.11.0",
     "commander": "^14.0.2",
     "giget": "^3.1.1",
-    "picocolors": "^1.1.1"
+    "picocolors": "^1.1.1",
+    "update-notifier": "^7.3.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@types/node": "^20.0.0",
+    "@types/update-notifier": "^6.0.8",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "husky": "^9.1.7",