@hasna/skills 0.1.19 → 0.1.20

package/README.md

@@ -1,6 +1,6 @@
 # @hasna/skills
 
-Skills library for AI coding agents
+Skills library for AI coding agents — discover, install, and run reusable capabilities for Claude Code, Codex CLI, Gemini CLI, and more.
 
 [![npm](https://img.shields.io/npm/v/@hasna/skills)](https://www.npmjs.com/package/@hasna/skills)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
@@ -11,33 +11,92 @@ Skills library for AI coding agents
 npm install -g @hasna/skills
 ```
 
-## CLI Usage
+Requires [Bun](https://bun.sh/) 1.0+.
+
+## Quick Start
 
 ```bash
-skills --help
+# Browse skills interactively
+skills
+
+# Install a skill to your project
+skills install image
+
+# Install for a specific agent
+skills install image --for claude
+
+# See what a skill needs
+skills info image
+
+# Run a skill
+skills run image "a cat sitting on a windowsill"
 ```
 
-- `skills install`
-- `skills list`
-- `skills search`
-- `skills info`
-- `skills docs`
-- `skills run`
-- `skills remove`
-- `skills categories`
-- `skills tags`
+## CLI Commands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `skills` | | Interactive TUI to browse, search, and install skills |
+| `skills install <name>` | `add` | Install one or more skills to `.skills/` |
+| `skills install --for claude` | | Copy SKILL.md to `~/.claude/skills/` (also `codex`, `gemini`, `pi`, `opencode`, `all`) |
+| `skills install --category "Development Tools"` | | Install all skills in a category |
+| `skills list` | `ls` | List available skills (filter with `-c`, `-i`, `-t`, `--brief`) |
+| `skills search <query>` | `s` | Search by name, description, or tags |
+| `skills info <name>` | | Show metadata, env vars, and system dependencies |
+| `skills docs <name>` | | Show documentation (SKILL.md > README.md > CLAUDE.md) |
+| `skills requires <name>` | | Show env vars, system deps, and npm dependencies |
+| `skills run <name> [args]` | | Execute a skill directly |
+| `skills remove <name>` | `rm` | Remove an installed skill |
+| `skills update` | | Reinstall all skills with `--overwrite` (version diff shown) |
+| `skills diff <name>` | | Preview file changes before updating a skill |
+| `skills init` | | Generate `.env.example` and update `.gitignore` for installed skills |
+| `skills categories` | | List all categories with skill counts |
+| `skills tags` | | List all unique tags with occurrence counts |
+| `skills doctor` | | Check env vars, system deps, and install health |
+| `skills test [name]` | | Test skill readiness (env, system, npm deps) |
+| `skills outdated` | | Compare installed vs registry versions |
+| `skills auth [name]` | | Show/set auth env vars in `.env` |
+| `skills whoami` | | Version, installed skills, agent configs, paths |
+| `skills export` | | Export installed skills as JSON |
+| `skills import <file>` | | Install skills from a JSON export |
+| `skills config set <key> <value>` | | Set default agent, scope, or output format |
+| `skills create <name>` | | Scaffold a new custom skill directory |
+| `skills sync --to claude` | | Push custom skills to agent directories |
+| `skills sync --from claude` | | List agent skills, `--register` to import unknown ones |
+| `skills validate <name>` | | Check a skill's directory structure |
+| `skills schedule add <skill> <cron>` | | Set up recurring skill execution |
+| `skills schedule list` | | List all schedules (enabled/disabled/last run) |
+| `skills mcp` | | Start MCP server on stdio |
+| `skills mcp --register claude` | | Auto-register MCP server with an agent |
+| `skills serve` | | Start the HTTP dashboard on localhost |
+| `skills self-update` | | Update this package to the latest version |
+| `skills completion <shell>` | | Generate shell completions (bash, zsh, fish) |
+
+### Common Options
+
+- `--json` — Output as JSON (pipeable)
+- `--brief` — One-line format
+- `--dry-run` — Preview without applying changes
+- `--verbose` — Debug logging to stderr
+- `--no-color` — Disable ANSI colors
+- `-o, --overwrite` — Overwrite existing files during install
 
 ## MCP Server
 
 ```bash
-skills-mcp
+skills mcp    # stdio transport (use with Claude/Codex MCP config)
 ```
 
-5 tools available.
+The MCP server exposes 20+ tools including `list_skills`, `search_skills`, `install_skill`, `get_skill_info`, `get_skill_docs`, `get_requirements`, `run_skill`, `schedule_skill`, `detect_project_skills`, `validate_skill`, and more.
 
-## Cloud Sync
+### Register with an Agent
+
+```bash
+skills mcp --register claude    # Auto-register with Claude Code
+skills mcp --register all       # Register with all supported agents
+```
 
-This package supports cloud sync via `@hasna/cloud`:
+## Cloud Sync
 
 ```bash
 cloud setup
@@ -45,10 +104,69 @@ cloud sync push --service skills
 cloud sync pull --service skills
 ```
 
+## Dashboard
+
+```bash
+skills serve              # Start HTTP server (opens browser automatically)
+skills serve --no-open    # Start without opening the browser
+```
+
+Dashboard features: searchable/filterable skills table, detail dialogs, stats cards, dark/light/system theme, oklch color tokens.
+
+## Project Structure
+
+```
+src/
+├── cli/index.tsx           # Commander.js CLI + Ink TUI
+├── mcp/index.ts            # MCP server (stdio) with ~20 tools
+├── server/serve.ts          # Bun.serve HTTP server + REST API
+├── lib/
+│   ├── registry.ts          # 202+ entries, search, categories, tags
+│   ├── installer.ts         # Copy skills to .skills/ or agent dirs
+│   ├── skillinfo.ts         # Docs, requirements, env/system detection
+│   ├── scheduler.ts         # Cron-based skill execution
+│   ├── config.ts            # Global + project config loading
+│   └── utils.ts             # normalizeSkillName()
+├── index.ts                 # Library re-exports (npm package entry)
+└── *.test.ts                # Test files
+
+skills/                      # 202+ skill directories
+├── _common/                 # Shared utilities
+└── skill-*/                 # Each skill: src/, SKILL.md, package.json
+
+dashboard/                   # Vite + React 19 + Tailwind v4 SPA
+```
+
+## Installation Types
+
+1. **Full source** — copies skill to `.skills/` in your project (default)
+2. **Agent config** — copies only SKILL.md to `~/.{agent}/skills/` (use `--for`)
+3. **Global custom** — create with `skills create --global` (stores in `~/.hasna/skills/custom/`)
+
+## Development
+
+```bash
+bun install
+bun run build              # Build CLI, MCP, library, and types
+bun run dev                # Run CLI in dev mode (no build needed)
+bun run dashboard:dev       # Vite dev server for web dashboard
+bun run server:dev          # HTTP server with --watch
+bun test                   # Run all tests
+bun run typecheck          # TypeScript type checking
+```
+
+## Adding a New Skill
+
+1. Create `skills/skill-{name}/` with `src/index.ts`, `package.json`, `tsconfig.json`, `SKILL.md`
+2. Add an entry to the `SKILLS` array in `src/lib/registry.ts`
+3. Run `bun test` to verify validation passes
+
+Skill directories are auto-discovered from `~/.hasna/skills/custom/` and `.skills/custom-skills/` — no registry entry needed for local custom skills.
+
 ## Data Directory
 
-Data is stored in `~/.hasna/skills/`.
+Configuration and runtime data are stored in `~/.hasna/skills/`. Legacy `~/.skillsrc` is auto-migrated on first run.
 
 ## License
 
-Apache-2.0 -- see [LICENSE](LICENSE)
+Apache-2.0 — see [LICENSE](LICENSE)