agent-skill-manager 1.1.0 → 1.2.0

package/README.md

@@ -7,25 +7,29 @@
 </p>
 
 <p align="center">
-  <em>The universal skill manager for AI coding agents.</em>
+  <em>The universal skill manager for AI agents.</em>
 </p>
 
 <p align="center">
+  <a href="#features">Features</a> &middot;
   <a href="#install">Install</a> &middot;
   <a href="#usage">Usage</a> &middot;
   <a href="#configuration">Configuration</a> &middot;
+  <a href="docs/">Docs</a> &middot;
   <a href="CONTRIBUTING.md">Contributing</a> &middot;
   <a href="LICENSE">License</a>
 </p>
 
 <p align="center">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License" /></a>
+  <a href="https://www.npmjs.com/package/agent-skill-manager"><img src="https://img.shields.io/npm/v/agent-skill-manager.svg" alt="npm version" /></a>
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.0-black.svg" alt="Bun" /></a>
+  <a href="https://github.com/luongnv89/agent-skill-manager/actions"><img src="https://github.com/luongnv89/agent-skill-manager/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
 </p>
 
 ---
 
-**agent-skill-manager** is an interactive terminal UI for managing installed skills across AI coding agents — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [OpenClaw](https://github.com/openclaw), and more. Built with [OpenTUI](https://github.com/nicholasgasior/opentui) and [Bun](https://bun.sh).
+**agent-skill-manager** (`asm`) is an interactive TUI and CLI for managing installed skills across AI coding agents — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [OpenClaw](https://github.com/openclaw), and more. Built with [OpenTUI](https://github.com/nicholasgasior/opentui) and [Bun](https://bun.sh).
 
 <p align="center">
   <img src="assets/screenshots/agent-skill-manager.png" alt="agent-skill-manager TUI dashboard" width="800" />
@@ -33,17 +37,36 @@
 
 ## Features
 
-- **Multi-agent support** — Manage skills for Claude Code, Codex, OpenClaw, and custom agent tools from one TUI
+- **Dual interface** — Full interactive TUI and non-interactive CLI (`asm list`, `asm search`, etc.)
+- **Multi-agent support** — Manage skills for Claude Code, Codex, OpenClaw, and custom agent tools from a single tool
 - **Configurable providers** — Define which agent tool directories to scan via `~/.config/agent-skill-manager/config.json`
 - **Global & project scopes** — Filter skills by global (`~/.<tool>/skills/`) or project-level (`./<tool>/skills/`)
 - **Real-time search** — Filter skills by name, description, or provider
 - **Sort** — By name, version, or location
 - **Detailed skill view** — Metadata from SKILL.md frontmatter including provider, path, symlink info
+- **Duplicate audit** — Detect and remove duplicate skills across providers and scopes
 - **Safe uninstall** — Confirmation dialog, removes skill directories, rule files, and AGENTS.md blocks
 - **In-TUI config editor** — Toggle providers on/off, or open config in `$EDITOR`
+- **JSON output** — Machine-readable output for scripting (`--json`)
 
 ## Install
 
+### npm (recommended)
+
+The npm package ships as a pre-built bundle — **no build step required** on install.
+
+**Prerequisites:** [Bun](https://bun.sh) >= 1.0.0 (used as the runtime)
+
+```bash
+# Install globally via npm
+npm install -g agent-skill-manager
+
+# Or via Bun
+bun install -g agent-skill-manager
+```
+
+> **Note:** While the package is installed through npm, it requires the [Bun](https://bun.sh) runtime to execute. Install Bun with: `curl -fsSL https://bun.sh/install | bash`
+
 ### Quick Install (one command)
 
 ```bash
@@ -58,27 +81,20 @@ wget -qO- https://raw.githubusercontent.com/luongnv89/agent-skill-manager/main/i
 
 This will automatically install [Bun](https://bun.sh) (if not already installed) and then install `agent-skill-manager` globally.
 
-### Manual Install
-
-**Prerequisites:** [Bun](https://bun.sh) >= 1.0.0
-
-```bash
-bun install -g agent-skill-manager
-```
-
 ### From Source
 
 ```bash
 git clone https://github.com/luongnv89/agent-skill-manager.git
 cd agent-skill-manager
 bun install
-bun run start
+bun run build    # bundle to dist/
+bun run start    # run from source (development)
 ```
 
 ### Advanced Options
 
 ```bash
-# Download and inspect before running
+# Download and inspect the install script before running
 curl -sSL https://raw.githubusercontent.com/luongnv89/agent-skill-manager/main/install.sh -o install.sh
 less install.sh  # review the script
 bash install.sh
@@ -86,13 +102,60 @@ bash install.sh
 
 ## Usage
 
+### Interactive TUI
+
+Launch without arguments to open the interactive terminal UI:
+
 ```bash
-agent-skill-manager              # Launch the interactive TUI
-agent-skill-manager --help       # Show help
-agent-skill-manager --version    # Show version
+asm                    # or: agent-skill-manager
 ```
 
-## Keyboard Shortcuts
+### CLI Commands
+
+```bash
+asm list                       # List all discovered skills
+asm search <query>             # Search by name/description/provider
+asm inspect <skill-name>       # Show detailed info for a skill
+asm uninstall <skill-name>     # Remove a skill (with confirmation)
+asm audit                      # Detect duplicate skills
+asm config show                # Print current config
+asm config path                # Print config file path
+asm config reset               # Reset config to defaults
+asm config edit                # Open config in $EDITOR
+```
+
+### Global Options
+
+```text
+-h, --help             Show help for any command
+-v, --version          Print version and exit
+--json                 Output as JSON (list, search, inspect, audit)
+-s, --scope <scope>    Filter: global, project, or both (default: both)
+--sort <field>         Sort by: name, version, or location (default: name)
+-y, --yes              Skip confirmation prompts
+--no-color             Disable ANSI colors
+```
+
+### Examples
+
+```bash
+# List all global skills sorted by provider location
+asm list --scope global --sort location
+
+# Search for skills and output JSON
+asm search "code review" --json
+
+# Inspect a specific skill
+asm inspect my-skill
+
+# Remove duplicates automatically
+asm audit --yes
+
+# Uninstall without confirmation
+asm uninstall old-skill --yes
+```
+
+## TUI Keyboard Shortcuts
 
 | Key            | Action                                |
 | -------------- | ------------------------------------- |
@@ -105,6 +168,7 @@ agent-skill-manager --version    # Show version
 | `s`            | Cycle sort: Name → Version → Location |
 | `r`            | Refresh / rescan skills               |
 | `c`            | Open configuration                    |
+| `a`            | Audit duplicates                      |
 | `q`            | Quit                                  |
 | `?`            | Toggle help overlay                   |
 
@@ -158,7 +222,7 @@ On first run, a config file is created at `~/.config/agent-skill-manager/config.
 - **Disable providers** — Set `enabled: false` to skip scanning a provider
 - **Preferences** — Set default scope and sort order
 
-You can also toggle providers on/off directly in the TUI by pressing `c`.
+You can also manage config from the CLI (`asm config show|path|reset|edit`) or toggle providers in the TUI by pressing `c`.
 
 ## Supported Agent Tools
 
@@ -173,27 +237,45 @@ Additional tools can be added via the config file.
 
 ## Project Structure
 
-```
+```text
 agent-skill-manager/
-├── bin/                    # CLI entry point
+├── bin/                       # CLI entry point (source)
 │   └── agent-skill-manager.ts
+├── dist/                      # Built bundle (npm package ships this)
+│   └── agent-skill-manager.js
+├── scripts/
+│   └── build.ts               # Build script with version injection
 ├── src/
-│   ├── index.ts            # App bootstrap & keyboard handling
-│   ├── config.ts           # Config loading & saving
-│   ├── scanner.ts          # Skill directory scanning & filtering
-│   ├── uninstaller.ts      # Safe skill removal logic
+│   ├── index.ts               # TUI app bootstrap & keyboard handling
+│   ├── cli.ts                 # CLI command parser & dispatcher
+│   ├── config.ts              # Config loading & saving
+│   ├── scanner.ts             # Skill directory scanning & filtering
+│   ├── auditor.ts             # Duplicate detection & reporting
+│   ├── uninstaller.ts         # Safe skill removal logic
+│   ├── formatter.ts           # Output formatting (tables, detail, JSON)
 │   ├── utils/
-│   │   ├── types.ts        # Shared TypeScript types
-│   │   ├── colors.ts       # TUI color palette
-│   │   └── frontmatter.ts  # SKILL.md frontmatter parser
+│   │   ├── types.ts           # Shared TypeScript types
+│   │   ├── colors.ts          # TUI color palette
+│   │   ├── version.ts         # Version constant
+│   │   └── frontmatter.ts     # SKILL.md frontmatter parser
 │   └── views/
-│       ├── dashboard.ts    # Main dashboard layout
-│       ├── skill-list.ts   # Scrollable skill list
-│       ├── skill-detail.ts # Skill detail overlay
-│       ├── confirm.ts      # Uninstall confirmation dialog
-│       ├── config.ts       # In-TUI config editor
-│       └── help.ts         # Help overlay
-├── docs/                   # Extended documentation
+│       ├── dashboard.ts       # Main dashboard layout
+│       ├── skill-list.ts      # Scrollable skill list
+│       ├── skill-detail.ts    # Skill detail overlay
+│       ├── confirm.ts         # Uninstall confirmation dialog
+│       ├── duplicates.ts      # Duplicate audit overlay
+│       ├── config.ts          # In-TUI config editor
+│       └── help.ts            # Help overlay
+├── docs/                      # Extended documentation
+│   ├── ARCHITECTURE.md        # System design & data flow
+│   ├── DEVELOPMENT.md         # Local setup & debugging
+│   ├── DEPLOYMENT.md          # Publishing & CI pipeline
+│   ├── CHANGELOG.md           # Version history
+│   └── brand_kit.md           # Logo, colors, typography
+├── assets/
+│   ├── logo/                  # SVG logos (full, mark, wordmark, icon, favicon)
+│   └── screenshots/           # TUI screenshots
+├── install.sh                 # One-command installer (curl | bash)
 ├── package.json
 ├── tsconfig.json
 └── README.md
@@ -203,10 +285,24 @@ agent-skill-manager/
 
 - **Runtime:** [Bun](https://bun.sh) >= 1.0.0
 - **Language:** TypeScript (ESNext, strict mode)
+- **Build:** Bun bundler (ships pre-built via npm)
 - **TUI Framework:** [OpenTUI](https://github.com/nicholasgasior/opentui)
 - **Testing:** Bun test runner
 - **CI:** GitHub Actions + pre-commit hooks
 
+## Documentation
+
+| Document                              | Description                              |
+| ------------------------------------- | ---------------------------------------- |
+| [Architecture](docs/ARCHITECTURE.md)  | System design, components, and data flow |
+| [Development](docs/DEVELOPMENT.md)    | Local setup, testing, and debugging      |
+| [Deployment](docs/DEPLOYMENT.md)      | Publishing and CI pipeline               |
+| [Changelog](docs/CHANGELOG.md)        | Version history                          |
+| [Brand Kit](docs/brand_kit.md)        | Logo, colors, and typography             |
+| [Contributing](CONTRIBUTING.md)       | How to contribute                        |
+| [Security](SECURITY.md)               | Vulnerability reporting                  |
+| [Code of Conduct](CODE_OF_CONDUCT.md) | Community guidelines                     |
+
 ## Contributing
 
 Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.