@biggora/claude-plugins 1.0.0 → 1.1.1

package/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:n8n.hm.neutron.lv)",
+      "WebFetch(domain:docs.n8n.io)",
+      "WebFetch(domain:deepwiki.com)",
+      "WebFetch(domain:commafeed.hm.neutron.lv)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(done)",
+      "Bash(npm --version)"
+    ]
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+CLI marketplace for discovering, installing, and managing Claude Code plugins. Published as `@biggora/claude-plugins` on npm. Plugins are git-cloned into `~/.claude/plugins/` where Claude Code auto-discovers them.
+
+## Commands
+
+```bash
+# Run the CLI (no build step needed)
+node bin/cli.js --help
+
+# Test (currently just runs --help)
+npm test
+```
+
+## Architecture
+
+Pure JavaScript ESM project (`"type": "module"`) with no build/transpile step. Node.js >= 18 required.
+
+### Entry Points
+
+- `bin/cli.js` - CLI entry point using Commander.js. Defines all commands with lazy `await import()` for each handler.
+- `package.json` `bin` field maps `claude-plugins` to `bin/cli.js`.
+
+### Core Modules
+
+- `src/config.js` - Constants and directory helpers. Defines `PLUGINS_DIR` (`~/.claude/plugins`), `CACHE_DIR`, `CACHE_TTL` (15 min), and `REGISTRY_URL` (GitHub raw URL).
+- `src/registry.js` - Fetches registry with 3-tier fallback: remote -> local cache -> bundled `registry/registry.json`. Provides `searchPlugins()` (keyword match across name/description/keywords/author) and `findPlugin()` (exact name match).
+- `src/utils.js` - Logging helpers (`log.info/success/warn/error/dim`), `spinner()` (ora), `formatTable()`, `truncate()`.
+
+### Command Handlers (`src/commands/`)
+
+Each file exports a single async function matching its command name:
+- `search.js` - Lists/filters plugins from registry
+- `install.js` - `git clone` from plugin's repository URL into plugins dir
+- `uninstall.js` - Removes plugin directory
+- `list.js` - Reads installed plugins from `~/.claude/plugins/`
+- `info.js` - Shows detailed plugin metadata
+- `update.js` - `git pull --ff-only` on installed plugins
+- `publish.js` - Validates plugin structure (`.claude-plugin/plugin.json` + `README.md`) and generates registry JSON entry
+
+### Registry (`registry/`)
+
+- `registry.json` - Bundled fallback registry with plugin entries
+- `schema.json` - JSON schema for registry format
+
+## Key Patterns
+
+- All shell operations use `execFileSync` (not `exec`) with `stdio: 'pipe'` for safety
+- Dependencies: `chalk` (styling), `commander` (CLI framework), `ora` (spinners) - all ESM-only
+- Plugin names must match `^[a-z0-9-]+$`
+- Registry entries require: name, version, description, author, repository

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 biggora
+Copyright (c) 2026 Aleksejs Gordejevs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,67 +1,182 @@
-# claude-plugins
+# @biggora/claude-plugins
 
-CLI marketplace for discovering, installing, and managing Claude Code plugins.
+[![npm version](https://img.shields.io/npm/v/@biggora/claude-plugins.svg)](https://www.npmjs.com/package/@biggora/claude-plugins)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+CLI marketplace for discovering, installing, and managing [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugins and skills.
 
 ## Installation
 
 ```bash
-npm install -g claude-plugins
+npm install -g @biggora/claude-plugins
 ```
 
-Or use directly with npx:
+Or use directly with npx (no install required):
 
 ```bash
-npx claude-plugins search
+npx @biggora/claude-plugins search
 ```
 
-## Commands
+## Skills
+
+Skills are self-contained instruction sets (SKILL.md files) that teach Claude Code how to perform specific tasks. They are installed into `~/.claude/skills/` and auto-discovered by Claude Code on startup.
 
-### Browse & Search
+### Install a Skill from Git
+
+Install a specific skill directly from a Git repository:
 
 ```bash
-# List all available plugins
-claude-plugins search
+# Install a single skill from a repository
+npx @biggora/claude-plugins skills add https://github.com/biggora/claude-plugins-registry --skill commafeed-api
 
-# Search by name or keyword
-claude-plugins search typescript
-claude-plugins search code-quality
+# Short form
+claude-plugins skills add https://github.com/biggora/claude-plugins-registry --skill n8n-api
 ```
 
-### Install & Remove
+### Manage Installed Skills
 
 ```bash
+# List installed skills
+claude-plugins skills list
+
+# Update a specific skill
+claude-plugins skills update commafeed-api
+
+# Update all installed skills
+claude-plugins skills update
+
+# Remove a skill
+claude-plugins skills remove commafeed-api
+```
+
+### Available Skills
+
+| Skill | Category | Description |
+|-------|----------|-------------|
+| `codex-cli` | devops | Install, configure, and automate tasks using OpenAI Codex CLI — approval modes, sandbox policies, MCP servers, and CI integration |
+| `commafeed-api` | workflow | Manage CommaFeed RSS reader via REST API — subscriptions, categories, feeds, entries, and OPML import/export |
+| `gemini-cli` | devops | Install, configure, and script with Gemini CLI — headless prompts, MCP servers, custom slash commands, extensions, and CI automation |
+| `n8n-api` | workflow | Build, debug, and manage n8n workflows via REST API — create workflows, manage credentials, execute and monitor runs |
+| `notebook-lm` | workflow | Automate Google NotebookLM — create notebooks, add sources, chat, generate audio/video overviews, quizzes, reports, and mind maps |
+| `screen-recording` | other | Autonomous video creation — product demos, presentation videos, UI walkthroughs, and narrated screencasts via Pillow, MoviePy, and pyttsx3 |
+| `test-mobile-app` | testing | Automated mobile app testing — analyzes APK/source, generates use cases, runs Appium tests on emulator, and produces QA reports |
+| `test-web-ui` | testing | Automated web QA — discovers site structure, generates use cases and test plans, runs Playwright tests, and produces HTML reports |
+| `text-to-speech` | other | Converts text to speech audio files using pyttsx3, espeak-ng, Kokoro ONNX, or cloud TTS engines with multilingual support |
+| `tm-search` | workflow | Search, validate, and check availability of US trademarks via USPTO APIs — keyword search, batch validation, and status lookup |
+| `wp-rest-api` | workflow | Build, extend, and debug WordPress REST API endpoints — routes, controllers, schema validation, authentication, and custom fields |
+| `youtube-search` | workflow | Search YouTube for videos, channels, playlists and extract metadata, transcripts, and analytics via multiple API methods |
+| `youtube-thumbnail` | other | Generates professional YouTube thumbnails in 11 strategic styles with auto-detection of AI image backends and Pillow compositing |
+
+#### Install Examples
+
+```bash
+npx skills add https://github.com/biggora/claude-plugins-registry --skill --skill codex-cli
+npx skills add https://github.com/biggora/claude-plugins-registry --skill --skill gemini-cli
+npx skills add https://github.com/biggora/claude-plugins-registry --skill --skill n8n-api
+npx skills add https://github.com/biggora/claude-plugins-registry --skill --skill notebook-lm
+npx skills add https://github.com/biggora/claude-plugins-registry --skill --skill commafeed-api
+npx skills add https://github.com/biggora/claude-plugins-registry --skill --skill tm-search
+npx skills add https://github.com/biggora/claude-plugins-registry --skill --skill wp-rest-api
+npx skills add https://github.com/biggora/claude-plugins-registry --skill --skill youtube-search
+npx skills add https://github.com/biggora/claude-plugins-registry --skill --skill youtube-thumbnail
+npx skills add https://github.com/biggora/claude-plugins-registry --skill --skill screen-recording
+npx skills add https://github.com/biggora/claude-plugins-registry --skill --skill text-to-speech
+npx skills add https://github.com/biggora/claude-plugins-registry --skill --skill test-web-ui
+npx skills add https://github.com/biggora/claude-plugins-registry --skill --skill test-mobile-app
+```
+
+## Plugins
+
+### Quick Start
+
+```bash
+# Browse all available plugins
+claude-plugins search
+
+# Search by keyword
+claude-plugins search typescript
+
 # Install a plugin
 claude-plugins install code-optimizer
 
-# Remove a plugin
-claude-plugins uninstall code-optimizer
+# Restart Claude Code to load the plugin
+```
+
+### Plugin Commands
+
+| Command | Description |
+|---------|-------------|
+| `claude-plugins search [query]` | Browse or search plugins by name, keyword, or category |
+| `claude-plugins install <name>` | Install a plugin from the registry |
+| `claude-plugins uninstall <name>` | Remove an installed plugin |
+| `claude-plugins list` | List locally installed plugins |
+| `claude-plugins info <name>` | Show detailed plugin information |
+| `claude-plugins update [name]` | Update one or all installed plugins |
+| `claude-plugins publish` | Validate plugin and generate registry entry for submission |
+
+### Skills Commands
+
+| Command | Description |
+|---------|-------------|
+| `claude-plugins skills add <source>` | Install a skill from a Git URL or registry name |
+| `claude-plugins skills add <url> --skill <name>` | Install a specific skill from a multi-skill repository |
+| `claude-plugins skills list` | List installed skills |
+| `claude-plugins skills update [name]` | Update one or all installed skills |
+| `claude-plugins skills remove <name>` | Remove an installed skill |
+
+### Aliases
+
+- `claude-plugins ls` - alias for `list`
+- `claude-plugins remove <name>` - alias for `uninstall`
+- `claude-plugins upgrade [name]` - alias for `update`
+- `claude-plugins skills ls` - alias for `skills list`
+- `claude-plugins skills rm <name>` - alias for `skills remove`
+
+## Usage Examples
+
+### Search & Install Plugins
+
+```bash
+# List all plugins in the registry
+claude-plugins search
+
+# Search for code quality tools
+claude-plugins search code-quality
+
+# Get details about a specific plugin
+claude-plugins info typescript-eslint-fixer
+
+# Install it
+claude-plugins install typescript-eslint-fixer
 ```
 
-### Manage
+### Manage Installed Plugins
 
 ```bash
-# List installed plugins
+# See what you have installed
 claude-plugins list
 
-# Show plugin details
-claude-plugins info code-optimizer
-
-# Update all plugins
+# Update all plugins to latest
 claude-plugins update
 
 # Update a specific plugin
 claude-plugins update code-optimizer
+
+# Remove a plugin
+claude-plugins uninstall code-optimizer
 ```
 
-### Publish
+### Publish Your Own Plugin
 
 ```bash
 # From your plugin directory
-cd my-plugin
+cd my-awesome-plugin
+
+# Validate and generate a registry entry
 claude-plugins publish
 ```
 
-This validates your plugin and generates a registry entry. Submit a PR to [claude-plugins-registry](https://github.com/biggora/claude-plugins-registry) to list it.
+The `publish` command validates your plugin structure and outputs a JSON entry. Submit a PR to [claude-plugins-registry](https://github.com/biggora/claude-plugins-registry) to list your plugin.
 
 ## Plugin Structure
 
@@ -72,10 +187,10 @@ my-plugin/
   .claude-plugin/
     plugin.json       # Required: name, version, description
   README.md           # Required
-  commands/           # Slash commands
-  agents/             # Agent definitions
-  skills/             # Skill files
-  hooks/              # Hook definitions
+  commands/           # Slash commands (optional)
+  agents/             # Agent definitions (optional)
+  skills/             # Skill files (optional)
+  hooks/              # Hook definitions (optional)
 ```
 
 ### plugin.json
@@ -84,29 +199,68 @@ my-plugin/
 {
   "name": "my-plugin",
   "version": "1.0.0",
-  "description": "What it does",
-  "author": { "name": "you", "url": "https://github.com/you" },
-  "repository": "https://github.com/you/my-plugin",
+  "description": "Short description of what it does",
+  "author": {
+    "name": "your-name",
+    "url": "https://github.com/your-name"
+  },
+  "repository": "https://github.com/your-name/my-plugin",
   "keywords": ["keyword1", "keyword2"],
   "license": "MIT"
 }
 ```
 
+## Skill Structure
+
+Skills are simpler than plugins — just a SKILL.md file with optional supporting files:
+
+```
+my-skill/
+  SKILL.md            # Required: skill instructions with YAML frontmatter
+  references/         # Reference docs (optional)
+  scripts/            # Helper scripts (optional)
+```
+
+### SKILL.md
+
+```markdown
+---
+name: my-skill
+description: What this skill teaches Claude to do
+---
+
+# My Skill
+
+Instructions for Claude Code...
+```
+
 ## Registry
 
-The plugin registry is hosted at [github.com/biggora/claude-plugins-registry](https://github.com/biggora/claude-plugins-registry). The CLI fetches it on demand and caches for 15 minutes.
+The plugin registry is a GitHub-hosted JSON file at [biggora/claude-plugins-registry](https://github.com/biggora/claude-plugins-registry).
 
-To add your plugin to the registry:
+- The CLI fetches the registry on demand and caches it locally for 15 minutes
+- Falls back to cached version if GitHub is unreachable
+- Falls back to bundled registry if no cache exists
 
-1. Ensure your plugin is on GitHub
-2. Run `claude-plugins publish` to validate and generate a registry entry
-3. Submit a PR adding the entry to `registry.json`
+### Adding a Plugin to the Registry
+
+1. Create your plugin and push it to a public GitHub repository
+2. Run `claude-plugins publish` from your plugin directory to validate
+3. Copy the generated registry entry
+4. Submit a PR to [claude-plugins-registry](https://github.com/biggora/claude-plugins-registry) adding the entry to `registry/registry.json`
 
 ## How It Works
 
-- Plugins are installed to `~/.claude/plugins/<name>` via `git clone`
-- Updates use `git pull --ff-only`
-- Claude Code automatically discovers plugins in `~/.claude/plugins/`
+- **Plugins** are installed via `git clone` to `~/.claude/plugins/<name>`
+- **Skills** are installed via `git clone` + copy to `~/.claude/skills/<name>`
+- Updates use `git pull --ff-only` to safely fast-forward
+- Claude Code automatically discovers plugins and skills in `~/.claude/`
+- Restart Claude Code after installing or removing plugins/skills
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Git (for install/update operations)
 
 ## License
 

package/bin/cli.js

@@ -76,4 +76,43 @@ program
     await publish();
   });
 
+const skills = program
+  .command('skills')
+  .description('Manage Claude Code skills');
+
+skills
+  .command('add <source>')
+  .description('Install a skill from a Git URL or registry name')
+  .option('--skill <name>', 'Select a specific skill from a multi-skill repo')
+  .action(async (source, options) => {
+    const { add } = await import('../src/commands/skills/add.js');
+    await add(source, options);
+  });
+
+skills
+  .command('list')
+  .alias('ls')
+  .description('List installed skills')
+  .action(async () => {
+    const { list } = await import('../src/commands/skills/list.js');
+    await list();
+  });
+
+skills
+  .command('remove <name>')
+  .alias('rm')
+  .description('Remove an installed skill')
+  .action(async (name) => {
+    const { remove } = await import('../src/commands/skills/remove.js');
+    await remove(name);
+  });
+
+skills
+  .command('update [name]')
+  .description('Update one or all installed skills')
+  .action(async (name) => {
+    const { update } = await import('../src/commands/skills/update.js');
+    await update(name);
+  });
+
 program.parse();

package/package.json

@@ -1,17 +1,7 @@
 {
   "name": "@biggora/claude-plugins",
-  "publishConfig": {
-    "access": "public"
-  },
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "CLI marketplace for discovering, installing, and managing Claude Code plugins",
-  "main": "src/index.js",
-  "bin": {
-    "claude-plugins": "bin/cli.js"
-  },
-  "scripts": {
-    "test": "node bin/cli.js --help"
-  },
   "keywords": [
     "claude",
     "claude-code",
@@ -19,22 +9,45 @@
     "marketplace",
     "cli"
   ],
-  "author": {
-    "name": "biggora",
-    "url": "https://github.com/biggora"
+  "homepage": "https://github.com/biggora/claude-plugins-registry#readme",
+  "bugs": {
+    "url": "https://github.com/biggora/claude-plugins-registry/issues"
   },
-  "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/biggora/claude-plugins"
+    "url": "git+https://github.com/biggora/claude-plugins-registry.git"
+  },
+  "license": "MIT",
+  "author": "biggora (https://github.com/biggora)",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "claude-plugins": "bin/cli.js"
+  },
+  "directories": {
+    "test": "tests"
+  },
+  "scripts": {
+    "test": "node --test tests/unit/*.test.js tests/commands/*.test.js tests/skills/*.test.js tests/validation/*.test.js tests/integration/*.test.js",
+    "test:unit": "node --test tests/unit/*.test.js",
+    "test:commands": "node --test tests/commands/*.test.js",
+    "test:skills": "node --test tests/skills/*.test.js",
+    "test:validation": "node --test tests/validation/*.test.js",
+    "test:integration": "node --test tests/integration/*.test.js",
+    "test:functional": "node --test tests/functional/*.test.js",
+    "test:all": "node --test tests/unit/*.test.js tests/commands/*.test.js tests/skills/*.test.js tests/validation/*.test.js tests/integration/*.test.js tests/functional/*.test.js",
+    "test:coverage": "node --test --experimental-test-coverage tests/unit/*.test.js tests/commands/*.test.js tests/skills/*.test.js tests/validation/*.test.js tests/integration/*.test.js"
   },
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "ora": "^8.1.0"
   },
+  "devDependencies": {},
   "engines": {
     "node": ">=18.0.0"
   },
-  "type": "module"
+  "publishConfig": {
+    "access": "public"
+  }
 }