@hasna/skills 0.1.18 → 0.1.20

package/README.md

@@ -1,436 +1,172 @@
 # @hasna/skills
 
-Open source skill library for AI coding agents. 202 pre-built skills across 17 categories -- search, install, and run any skill with a single command.
+Skills library for AI coding agents — discover, install, and run reusable capabilities for Claude Code, Codex CLI, Gemini CLI, and more.
 
-```bash
-npx @hasna/skills
-```
-
-## Features
+[![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)
 
-- **202 ready-to-use skills** across development, business, content, data, media, design, and more
-- **Interactive TUI** -- browse by category, search, and install from the terminal
-- **MCP server** -- 10 tools and 2 resources for AI agent integration
-- **HTTP dashboard** -- React web UI to browse, search, install, and manage skills
-- **Agent-aware installs** -- copies SKILL.md to `~/.claude/skills/`, `~/.codex/skills/`, or `~/.gemini/skills/`
-- **Auto-generated index** -- `.skills/index.ts` is updated on every install for easy imports
-- **Library exports** -- use the registry, installer, and skill info programmatically
-
-## Installation
+## Install
 
 ```bash
-# Global install (recommended)
-bun install -g @hasna/skills
-
-# Or use npx (no install needed)
-npx @hasna/skills
-
-# Or install as a project dependency
-bun add @hasna/skills
+npm install -g @hasna/skills
 ```
 
+Requires [Bun](https://bun.sh/) 1.0+.
+
 ## Quick Start
 
 ```bash
-# Launch interactive browser (TUI)
+# Browse skills interactively
 skills
 
-# Search for skills
-skills search "image generation"
+# Install a skill to your project
+skills install image
 
-# Install skills to .skills/ in your project
-skills install image deep-research generate-pdf
-
-# Install a skill for Claude Code (copies SKILL.md)
+# Install for a specific agent
 skills install image --for claude
 
-# Get skill details
+# See what a skill needs
 skills info image
 
-# Run a skill directly
-skills run image --prompt "a sunset over mountains"
-
-# Start the web dashboard
-skills serve
-
-# Smart init: detect project type and install skills for Claude
-skills init --for claude
-
-# Browse skills by tag
-skills list --tags api,testing
+# Run a skill
+skills run image "a cat sitting on a windowsill"
 ```
 
-## Categories
-
-| Category | Count | Examples |
-|----------|------:|---------|
-| Development Tools | 32 | api-test-suite, deploy, mcp-builder, scaffold-project |
-| Business & Marketing | 25 | email-campaign, salescopy, seo-brief-builder, persona-generator |
-| Finance & Compliance | 16 | invoice, extract-invoice, budget-variance-analyzer |
-| Content Generation | 14 | image, video, audio, generate-pdf, generate-presentation |
-| Media Processing | 13 | subtitle, transcript, compress-video, remove-background |
-| Data & Analysis | 12 | analyze-data, extract, dashboard-builder, generate-chart |
-| Productivity & Organization | 11 | convert, merge-pdfs, file-organizer, notion-manager |
-| Design & Branding | 11 | brand-style-guide, generate-favicon, product-mockup |
-| Research & Writing | 10 | deepresearch, write, create-blog-article, create-ebook |
-| Science & Academic | 10 | advanced-math, chemistry-calculator, citation-formatter |
-| Education & Learning | 10 | study-guide-builder, lesson-plan-customizer, exam-readiness-check |
-| Project Management | 9 | implementation, implementation-plan, action-item-router |
-| Health & Wellness | 8 | meal-plan-designer, workout-cycle-planner, habit-reflection-digest |
-| Travel & Lifestyle | 7 | itinerary-architect, destination-briefing, travel-budget-balancer |
-| Communication | 4 | gmail, slack-assistant, sms, calendar-events |
-| Web & Browser | 4 | browse, webcrawling, domainsearch, domainpurchase |
-| Event Management | 4 | seating-chart-maker, livestream-runofshow, onsite-ops-checklist |
-
 ## CLI Commands
 
 | Command | Alias | Description |
 |---------|-------|-------------|
-| `skills` | `skills i` | Interactive TUI browser (default) |
-| `skills install <names...>` | `skills add` | Install one or more skills to `.skills/` |
-| `skills install <name> --for <agent>` | | Install SKILL.md for claude, codex, gemini, or all |
-| `skills remove <name>` | `skills rm` | Remove an installed skill |
-| `skills list` | `skills ls` | List all available skills (supports `--tags` to filter by tags) |
-| `skills list --category <cat>` | | List skills in a category |
-| `skills list --installed` | | List installed skills |
-| `skills search <query>` | | Search skills by name, description, or tags (supports `--tags` to filter by tags) |
-| `skills info <name>` | | Show skill metadata, requirements, and env vars |
-| `skills docs <name>` | | Show skill documentation (SKILL.md/README.md/CLAUDE.md) |
+| `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...]` | | Run a skill directly |
-| `skills categories` | | List all categories with counts |
-| `skills tags` | | List all tags with skill counts |
-| `skills init` | | Initialize project, detect deps, and optionally install for agents |
-| `skills update [names...]` | | Update installed skills (reinstall with overwrite) |
-| `skills serve` | | Start the HTTP dashboard (auto-assigns free port) |
-| `skills mcp` | | Start the MCP server on stdio |
-| `skills mcp --register <agent>` | | Register MCP server with claude, codex, gemini, or all |
-| `skills self-update` | | Update `@hasna/skills` to the latest version |
-
-All list/search/info commands support `--json` for machine-readable output. Search uses fuzzy matching -- typos and abbreviations are tolerated.
+| `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
 
-The MCP server exposes the full skill library to AI agents over stdio.
-
-### Starting the server
-
 ```bash
-# Via CLI
-skills mcp
-
-# Direct binary
-skills-mcp
-
-# Register with Claude Code
-skills mcp --register claude
+skills mcp    # stdio transport (use with Claude/Codex MCP config)
 ```
 
-### Configuration for Claude Code
+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.
 
-Add to your MCP config:
-
-```json
-{
-  "mcpServers": {
-    "skills": {
-      "command": "skills-mcp"
-    }
-  }
-}
-```
-
-### Tools (10)
-
-| Tool | Description |
-|------|-------------|
-| `list_skills` | List all skills, optionally filtered by category |
-| `search_skills` | Search skills by query (name, description, tags) |
-| `get_skill_info` | Get skill metadata including requirements and env vars |
-| `get_skill_docs` | Get documentation (SKILL.md, README.md, or CLAUDE.md) |
-| `install_skill` | Install a skill (full source to `.skills/` or SKILL.md to agent dir) |
-| `remove_skill` | Remove an installed skill |
-| `list_categories` | List all categories with skill counts |
-| `list_tags` | List all skill tags with counts |
-| `get_requirements` | Get env vars, system deps, and npm dependencies |
-| `run_skill` | Run a skill by name with optional arguments |
-
-### Resources (2)
-
-| URI | Description |
-|-----|-------------|
-| `skills://registry` | Full skill registry as JSON |
-| `skills://{name}` | Individual skill metadata and documentation |
-
-## HTTP Dashboard
-
-A React web UI for browsing, searching, and managing skills.
+### Register with an Agent
 
 ```bash
-# Start the dashboard
-skills serve
-
-# Custom port
-skills serve --port 8080
-
-# Don't auto-open browser
-skills serve --no-open
-```
-
-The dashboard picks a random free port automatically (or use `--port` to pin one) and provides:
-
-- Searchable, sortable skills table with category filters
-- Skill detail dialog with documentation, tags, and requirements
-- One-click install and remove
-- Dark/light/system theme toggle
-- Self-update button
-
-### REST API
-
-The dashboard server also exposes a REST API:
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/api/skills` | GET | All skills with install status |
-| `/api/categories` | GET | Categories with counts |
-| `/api/skills/search?q=` | GET | Search skills |
-| `/api/skills/:name` | GET | Single skill detail with docs |
-| `/api/skills/:name/docs` | GET | Raw documentation text |
-| `/api/skills/:name/install` | POST | Install a skill |
-| `/api/skills/:name/remove` | POST | Remove a skill |
-| `/api/tags` | GET | All tags with skill counts |
-| `/api/version` | GET | Current package version |
-| `/api/self-update` | POST | Update to latest version |
-
-## Library Usage
-
-Use the registry, installer, and skill info modules programmatically:
-
-```typescript
-import {
-  SKILLS,
-  CATEGORIES,
-  searchSkills,
-  getSkill,
-  getSkillsByCategory,
-} from "@hasna/skills";
-
-// Search skills
-const results = searchSkills("image");
-
-// Get skills in a category
-const devTools = getSkillsByCategory("Development Tools");
-
-// Get a specific skill
-const skill = getSkill("image");
-// => { name: "image", displayName: "Image", description: "...", category: "Content Generation", tags: [...] }
-```
-
-```typescript
-import {
-  installSkill,
-  installSkillForAgent,
-  removeSkill,
-  getInstalledSkills,
-} from "@hasna/skills";
-
-// Install a skill to .skills/
-const result = installSkill("image");
-// => { skill: "image", success: true, path: "/path/to/.skills/skill-image" }
-
-// Install SKILL.md for Claude Code
-installSkillForAgent("image", { agent: "claude", scope: "global" });
-
-// List installed skills
-const installed = getInstalledSkills();
-// => ["image", "deep-research"]
-```
-
-```typescript
-import {
-  getSkillDocs,
-  getSkillRequirements,
-  runSkill,
-} from "@hasna/skills";
-
-// Read documentation
-const docs = getSkillDocs("image");
-// => { skillMd: "...", readme: "...", claudeMd: "..." }
-
-// Check requirements
-const reqs = getSkillRequirements("image");
-// => { envVars: ["OPENAI_API_KEY"], systemDeps: [], cliCommand: "image", dependencies: {...} }
-
-// Run a skill
-const { exitCode } = await runSkill("image", ["--prompt", "a cat"]);
-```
-
-## Skill Structure
-
-Each skill is a self-contained directory under `skills/skill-{name}/`:
-
-```
-skills/skill-{name}/
-├── src/
-│   ├── index.ts          # Main entry point / programmatic API
-│   ├── commands/          # CLI command handlers (optional)
-│   ├── lib/               # Core logic
-│   ├── types/             # TypeScript types
-│   └── utils/             # Utility functions
-├── SKILL.md               # Skill definition (used by agent installs)
-├── README.md              # Usage documentation
-├── CLAUDE.md              # Development guide (optional)
-├── package.json           # Dependencies and bin entry
-└── tsconfig.json          # Extends skills/tsconfig.base.json
-```
-
-Key files:
-
-- **SKILL.md** -- the primary doc file, copied to agent skill directories on `--for` installs. Contains frontmatter (name, description) and usage instructions.
-- **package.json** -- must have a `bin` entry for the skill to be runnable via `skills run`.
-- **src/index.ts** -- exported in the auto-generated `.skills/index.ts` when installed.
-
-## Using Installed Skills
-
-After installing, skills are available via the auto-generated index:
-
-```typescript
-import { image, deep_research } from "./.skills";
+skills mcp --register claude    # Auto-register with Claude Code
+skills mcp --register all       # Register with all supported agents
 ```
 
-Or import directly:
-
-```typescript
-import { generateImage } from "./.skills/skill-image/src/index.js";
-```
-
-## Creating a Custom Skill
-
-1. Create the skill directory:
+## Cloud Sync
 
 ```bash
-mkdir -p skills/skill-my-skill/src
+cloud setup
+cloud sync push --service skills
+cloud sync pull --service skills
 ```
 
-2. Add `package.json`:
+## Dashboard
 
-```json
-{
-  "name": "skill-my-skill",
-  "version": "0.0.1",
-  "bin": { "my-skill": "./src/index.ts" },
-  "dependencies": {}
-}
+```bash
+skills serve              # Start HTTP server (opens browser automatically)
+skills serve --no-open    # Start without opening the browser
 ```
 
-3. Add `SKILL.md` with frontmatter:
-
-```markdown
----
-name: my-skill
-description: What this skill does
----
+Dashboard features: searchable/filterable skills table, detail dialogs, stats cards, dark/light/system theme, oklch color tokens.
 
-# My Skill
+## Project Structure
 
-Usage instructions here.
 ```
+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
 
-4. Add `src/index.ts` with your logic.
-
-5. Register in `src/lib/registry.ts`:
+skills/                      # 202+ skill directories
+├── _common/                 # Shared utilities
+└── skill-*/                 # Each skill: src/, SKILL.md, package.json
 
-```typescript
-{
-  name: "my-skill",
-  displayName: "My Skill",
-  description: "What this skill does",
-  category: "Development Tools",
-  tags: ["my", "skill"],
-}
+dashboard/                   # Vite + React 19 + Tailwind v4 SPA
 ```
 
-6. Run tests to validate:
+## Installation Types
 
-```bash
-bun test
-```
+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
-# Install dependencies
 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
+```
 
-# Run CLI in dev mode
-bun run dev
-
-# Build CLI, MCP server, and library
-bun run build
-
-# Type check
-bun run typecheck
-
-# Run all tests
-bun test
-
-# Build the dashboard
-bun run dashboard:build
+## Adding a New Skill
 
-# Run dashboard dev server
-bun run dashboard:dev
+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
 
-# Start HTTP server (with dashboard)
-bun run server:dev
-```
+Skill directories are auto-discovered from `~/.hasna/skills/custom/` and `.skills/custom-skills/` — no registry entry needed for local custom skills.
 
-## Architecture
+## Data Directory
 
-```
-src/
-├── cli/
-│   ├── index.tsx              # Commander.js CLI + Ink TUI
-│   ├── cli.test.ts            # CLI integration tests
-│   └── components/
-│       └── App.tsx            # Interactive TUI (React/Ink)
-├── mcp/
-│   ├── index.ts               # MCP server (stdio transport)
-│   └── mcp.test.ts            # MCP integration tests
-├── server/
-│   ├── serve.ts               # Bun HTTP server + REST API
-│   └── serve.test.ts          # Server tests
-├── lib/
-│   ├── registry.ts            # SKILLS array (202) + CATEGORIES (17)
-│   ├── installer.ts           # Install/remove to .skills/ and agent dirs
-│   ├── skillinfo.ts           # Docs, requirements, env vars, run
-│   ├── utils.ts               # normalizeSkillName()
-│   ├── registry.test.ts       # Registry tests
-│   ├── installer.test.ts      # Installer tests
-│   ├── skillinfo.test.ts      # Skill info tests
-│   ├── skillinfo-run.test.ts  # Skill run tests
-│   ├── utils.test.ts          # Utils tests
-│   └── validation.test.ts     # Structural validation (all 202 skills)
-├── index.ts                   # Library re-exports
-└── index.test.ts              # Library export tests
-
-dashboard/                     # Vite + React 19 + Tailwind v4 + shadcn/ui
-├── src/components/
-│   ├── skills-table.tsx       # Main skills table (TanStack Table)
-│   ├── skill-detail-dialog.tsx# Skill detail dialog
-│   ├── stats-cards.tsx        # Summary cards
-│   ├── theme-provider.tsx     # Dark/light/system theme
-│   ├── theme-toggle.tsx       # Theme toggle button
-│   └── ui/                    # shadcn/ui primitives
-└── package.json
-
-skills/                        # 202 self-contained skill directories
-├── _common/                   # Shared utilities
-├── skill-image/
-├── skill-deep-research/
-├── ...
-└── tsconfig.base.json         # Shared TS config for skills
-```
+Configuration and runtime data are stored in `~/.hasna/skills/`. Legacy `~/.skillsrc` is auto-migrated on first run.
 
 ## License
 
-Apache-2.0
+Apache-2.0 — see [LICENSE](LICENSE)