Reorganize: Move all skills to skills/ folder
- Created skills/ directory - Moved 272 skills to skills/ subfolder - Kept agents/ at root level - Kept installation scripts and docs at root level Repository structure: - skills/ - All 272 skills from skills.sh - agents/ - Agent definitions - *.sh, *.ps1 - Installation scripts - README.md, etc. - Documentation Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
admin
@@ -1,450 +0,0 @@
|
||||
# Claude Code Plugin System
|
||||
|
||||
A Conduit-inspired plugin and hooks system for Claude Code, enabling extensible functionality through GitHub-based plugins, event-driven hooks, and secure sandboxed execution.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Features](#features)
|
||||
- [Installation](#installation)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Plugin Development](#plugin-development)
|
||||
- [Hooks System](#hooks-system)
|
||||
- [CLI Reference](#cli-reference)
|
||||
- [Security](#security)
|
||||
- [Examples](#examples)
|
||||
|
||||
## Features
|
||||
|
||||
### 🎯 Core Capabilities
|
||||
|
||||
- **GitHub-based Discovery**: Automatically discover plugins from GitHub repositories
|
||||
- **Zero-Configuration Install**: One-command installation from any GitHub repo
|
||||
- **Event-Driven Hooks**: Hook into any Claude Code event (pre/post execution)
|
||||
- **Security Sandboxing**: Isolated execution with permission validation
|
||||
- **Command Extensions**: Add custom commands to Claude Code
|
||||
- **Tool Extensions**: Extend Claude Code's built-in tools
|
||||
- **Version Management**: Track, update, and manage plugin versions
|
||||
- **Integrity Checking**: SHA-256 verification for plugin security
|
||||
|
||||
### 🔐 Security Features
|
||||
|
||||
- Permission-based access control
|
||||
- File system sandboxing
|
||||
- Command execution validation
|
||||
- Network access control
|
||||
- Code injection prevention
|
||||
- Binary integrity verification
|
||||
|
||||
## Installation
|
||||
|
||||
The plugin system is included with Claude Code. No additional installation required.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Discover Plugins
|
||||
|
||||
```bash
|
||||
# List all available plugins
|
||||
claude-plugin discover
|
||||
|
||||
# Search for specific plugins
|
||||
claude-plugin discover git
|
||||
claude-plugin discover docker
|
||||
```
|
||||
|
||||
### Install Plugins
|
||||
|
||||
```bash
|
||||
# Install from a marketplace
|
||||
claude-plugin install claude-plugins-official hookify
|
||||
|
||||
# Install directly from GitHub
|
||||
claude-plugin install-github username/my-plugin
|
||||
```
|
||||
|
||||
### Manage Plugins
|
||||
|
||||
```bash
|
||||
# View plugin information
|
||||
claude-plugin info hookify
|
||||
|
||||
# Enable/disable plugins
|
||||
claude-plugin enable hookify
|
||||
claude-plugin disable hookify
|
||||
|
||||
# Update plugins
|
||||
claude-plugin update hookify
|
||||
|
||||
# Uninstall plugins
|
||||
claude-plugin uninstall hookify
|
||||
```
|
||||
|
||||
## Plugin Development
|
||||
|
||||
### Plugin Structure
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json # Plugin metadata
|
||||
├── commands/ # Command handlers
|
||||
│ └── my-command.ts
|
||||
├── hooks/ # Hook handlers
|
||||
│ └── my-hook.ts
|
||||
├── skills/ # Skill definitions
|
||||
│ └── my-skill.md
|
||||
├── install.sh # Installation script (optional)
|
||||
└── uninstall.sh # Uninstallation script (optional)
|
||||
```
|
||||
|
||||
### Plugin Metadata
|
||||
|
||||
Create a `.claude-plugin/plugin.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"version": "1.0.0",
|
||||
"description": "My awesome plugin for Claude Code",
|
||||
"author": "Your Name",
|
||||
"license": "MIT",
|
||||
"repository": "https://github.com/username/my-plugin",
|
||||
"claude": {
|
||||
"minVersion": "1.0.0",
|
||||
"permissions": [
|
||||
"read:files",
|
||||
"write:files",
|
||||
"execute:commands"
|
||||
],
|
||||
"commands": [
|
||||
{
|
||||
"name": "my:command",
|
||||
"description": "Does something awesome",
|
||||
"handler": "commands/my-command.ts",
|
||||
"permissions": ["read:files"]
|
||||
}
|
||||
],
|
||||
"hooks": [
|
||||
{
|
||||
"event": "PostFileEdit",
|
||||
"handler": "hooks/my-hook.ts",
|
||||
"priority": 10
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Creating Commands
|
||||
|
||||
```typescript
|
||||
// commands/my-command.ts
|
||||
export interface MyCommandOptions {
|
||||
input: string
|
||||
option?: string
|
||||
}
|
||||
|
||||
export async function handle(
|
||||
args: MyCommandOptions,
|
||||
context: any
|
||||
): Promise<string> {
|
||||
const { input, option } = args
|
||||
|
||||
// Your logic here
|
||||
return `✓ Command executed with: ${input}`
|
||||
}
|
||||
|
||||
export default { handle }
|
||||
```
|
||||
|
||||
### Creating Hooks
|
||||
|
||||
```typescript
|
||||
// hooks/my-hook.ts
|
||||
export interface HookContext {
|
||||
event: string
|
||||
timestamp: string
|
||||
data: Record<string, any>
|
||||
}
|
||||
|
||||
export async function handle(
|
||||
context: HookContext
|
||||
): Promise<void> {
|
||||
console.log(`Hook triggered: ${context.event}`)
|
||||
console.log(`Data:`, context.data)
|
||||
|
||||
// Your logic here
|
||||
}
|
||||
|
||||
export default { handle }
|
||||
```
|
||||
|
||||
### Publishing Your Plugin
|
||||
|
||||
1. Create a GitHub repository with your plugin
|
||||
2. Add the `.claude-plugin/plugin.json` metadata file
|
||||
3. Push to GitHub
|
||||
4. Users can install with:
|
||||
```bash
|
||||
claude-plugin install-github username/your-plugin
|
||||
```
|
||||
|
||||
## Hooks System
|
||||
|
||||
### Available Hook Events
|
||||
|
||||
| Event | Description | When It Fires |
|
||||
|-------|-------------|---------------|
|
||||
| `UserPromptSubmit` | User submits a prompt | Before sending to Claude |
|
||||
| `PreToolUse` | Before tool execution | Tool about to be used |
|
||||
| `PostToolUse` | After tool execution | Tool completed |
|
||||
| `PreFileEdit` | Before file edit | File about to be modified |
|
||||
| `PostFileEdit` | After file edit | File was modified |
|
||||
| `PreCommand` | Before CLI command | Command about to run |
|
||||
| `PostCommand` | After CLI command | Command completed |
|
||||
| `SessionStart` | Session starts | New session begins |
|
||||
| `SessionEnd` | Session ends | Session closing |
|
||||
| `PluginLoad` | Plugin loads | Plugin loaded into memory |
|
||||
| `PluginUnload` | Plugin unloads | Plugin being unloaded |
|
||||
| `Error` | Error occurs | Any error happens |
|
||||
|
||||
### Hook Priority
|
||||
|
||||
Hooks execute in priority order (higher = earlier). Default priority is 0.
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "PostFileEdit",
|
||||
"handler": "hooks/auto-save.ts",
|
||||
"priority": 100
|
||||
}
|
||||
```
|
||||
|
||||
### Registering Hooks via Config
|
||||
|
||||
You can register hooks in your `.claude/hooks.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostFileEdit": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "/path/to/hook-script.sh",
|
||||
"timeout": 5
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## CLI Reference
|
||||
|
||||
### `claude-plugin discover [query]`
|
||||
List available plugins, optionally filtering by search query.
|
||||
|
||||
```bash
|
||||
claude-plugin discover
|
||||
claude-plugin discover git
|
||||
```
|
||||
|
||||
### `claude-plugin install <marketplace> [plugin-name]`
|
||||
Install a plugin from a marketplace.
|
||||
|
||||
```bash
|
||||
claude-plugin install claude-plugins-official hookify
|
||||
claude-plugin install claude-plugins-official # List all plugins
|
||||
```
|
||||
|
||||
### `claude-plugin install-github <repo>`
|
||||
Install a plugin directly from GitHub.
|
||||
|
||||
```bash
|
||||
claude-plugin install-github username/my-plugin
|
||||
```
|
||||
|
||||
### `claude-plugin uninstall <plugin-name> [marketplace]`
|
||||
Uninstall a plugin.
|
||||
|
||||
```bash
|
||||
claude-plugin uninstall hookify
|
||||
```
|
||||
|
||||
### `claude-plugin enable/disable <plugin-name> [marketplace]`
|
||||
Enable or disable a plugin without uninstalling.
|
||||
|
||||
```bash
|
||||
claude-plugin enable hookify
|
||||
claude-plugin disable hookify
|
||||
```
|
||||
|
||||
### `claude-plugin update <plugin-name> [marketplace]`
|
||||
Update a plugin to the latest version.
|
||||
|
||||
```bash
|
||||
claude-plugin update hookify
|
||||
```
|
||||
|
||||
### `claude-plugin info <plugin-name>`
|
||||
Show detailed information about a plugin.
|
||||
|
||||
```bash
|
||||
claude-plugin info hookify
|
||||
```
|
||||
|
||||
### `claude-plugin hooks [event]`
|
||||
List registered hooks.
|
||||
|
||||
```bash
|
||||
claude-plugin hooks # All hooks
|
||||
claude-plugin hooks PostFileEdit # Specific event
|
||||
```
|
||||
|
||||
### `claude-plugin add-marketplace <name> <github-url>`
|
||||
Add a new plugin marketplace.
|
||||
|
||||
```bash
|
||||
claude-plugin add-marketplace my-marketplace https://github.com/user/repo
|
||||
```
|
||||
|
||||
### `claude-plugin validate <path>`
|
||||
Validate a plugin structure and integrity.
|
||||
|
||||
```bash
|
||||
claude-plugin validate /path/to/plugin
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
### Permissions
|
||||
|
||||
Plugins request permissions in their `plugin.json`:
|
||||
|
||||
| Permission | Description |
|
||||
|------------|-------------|
|
||||
| `read:files` | Read files from the file system |
|
||||
| `write:files` | Write files to the file system |
|
||||
| `execute:commands` | Execute shell commands |
|
||||
| `network:request` | Make network requests |
|
||||
| `read:config` | Read Claude Code configuration |
|
||||
| `write:config` | Write Claude Code configuration |
|
||||
| `hook:events` | Register event hooks |
|
||||
| `read:secrets` | Access sensitive data (API keys, etc.) |
|
||||
|
||||
### Sandboxing
|
||||
|
||||
Plugins execute in a sandboxed environment with:
|
||||
|
||||
- **File System**: Access restricted to allowed paths
|
||||
- **Commands**: Dangerous patterns blocked (rm -rf /, etc.)
|
||||
- **Network**: Domain whitelist/blacklist enforcement
|
||||
- **Code**: Injection prevention and sanitization
|
||||
|
||||
### Integrity Verification
|
||||
|
||||
All plugins are verified with SHA-256 hashes:
|
||||
|
||||
```bash
|
||||
# View plugin integrity
|
||||
claude-plugin info my-plugin
|
||||
|
||||
# Verify manually
|
||||
claude-plugin validate /path/to/plugin
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Git Workflow Plugin
|
||||
|
||||
Commands:
|
||||
- `git:smart-commit` - Auto-stage and commit
|
||||
- `git:pr-create` - Create pull requests
|
||||
- `git:branch-cleanup` - Clean up merged branches
|
||||
|
||||
```bash
|
||||
claude-plugin install-github yourusername/git-workflow
|
||||
git:smart-commit --type feat --scope api
|
||||
git:pr-create --title "Add new feature" --base main
|
||||
```
|
||||
|
||||
### Example 2: Docker Helper Plugin
|
||||
|
||||
Commands:
|
||||
- `docker:deploy` - Deploy with zero-downtime
|
||||
- `docker:logs` - View and filter logs
|
||||
- `docker:cleanup` - Clean up resources
|
||||
- `docker:env` - Manage environment variables
|
||||
|
||||
```bash
|
||||
claude-plugin install-github yourusername/docker-helper
|
||||
docker:deploy --env production --no-downtime
|
||||
docker:logs --service app --tail 100 --follow
|
||||
docker:cleanup --containers --images --volumes
|
||||
```
|
||||
|
||||
### Example 3: Knowledge Base Plugin
|
||||
|
||||
Commands:
|
||||
- `knowledge:add` - Add knowledge entries
|
||||
- `knowledge:search` - Search knowledge base
|
||||
- `knowledge:list` - List all entries
|
||||
- `knowledge:export` - Export to JSON/Markdown/CSV
|
||||
|
||||
```bash
|
||||
claude-plugin install-github yourusername/knowledge-base
|
||||
knowledge:add --content "How to deploy to production" --tags deploy,ops
|
||||
knowledge:search --query "deploy" --category ops
|
||||
knowledge:export --format markdown
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Claude Code Core │
|
||||
└─────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────┼─────────────┐
|
||||
│ │ │
|
||||
┌───────▼──────┐ ┌───▼────┐ ┌─────▼─────┐
|
||||
│ Plugin │ │ Hook │ │ Security │
|
||||
│ Manager │ │ System │ │ Manager │
|
||||
└──────────────┘ └────────┘ └───────────┘
|
||||
│ │ │
|
||||
└─────────────┼─────────────┘
|
||||
│
|
||||
┌───────▼───────┐
|
||||
│ Plugins │
|
||||
│ (Sandboxed) │
|
||||
└───────────────┘
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
1. **Installation**: Plugin downloaded from GitHub → Validation → Registration
|
||||
2. **Loading**: Plugin metadata read → Security context created → Hooks registered
|
||||
3. **Execution**: Command/tool called → Permission check → Sandboxed execution
|
||||
4. **Hooks**: Event fires → Hooks executed by priority → Results collected
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions! Please see our contributing guidelines for more information.
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see LICENSE file for details
|
||||
|
||||
## Support
|
||||
|
||||
- GitHub Issues: https://github.com/anthropics/claude-code/issues
|
||||
- Documentation: https://docs.anthropic.com
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
Inspired by [Conduit](https://github.com/conduit-ui/conduit) - the developer liberation platform.
|
||||
Reference in New Issue
Block a user