Skill: marcusy2k/plugin-integration (version 1.0.1)

# Plugin Integration Development Skill ## **Overview** This skill enables users to create, develop, and integrate their own plugins, tools, and commands into OpenClaw. It provides guidelines, templates, and examples to streamline the development process. ## **Purpose** - Guide users through creating OpenClaw plugins, tools, and commands. - Provide best practices for development, testing, and integration. - Offer examples and utilities to simplify the process. ## **Key Features** - **Plugin Templates**: Predefined templates for plugins, tools, and commands. - **Validation Scripts**: Utilities to validate plugin structure and metadata. - **Example Plugins**: Ready-to-use examples for quick experimentation. - **API Reference**: Documentation for OpenClaw's plugin API. ## **Getting Started** ### **1. Initialize a New Plugin** Use the `init-plugin.sh` script to create a new plugin scaffold: ```bash ~/.openclaw/skills/plugin-integration/scripts/init-plugin.sh <plugin-name> ``` ### **2. Develop Your Plugin** Follow the structure in the `examples/` directory to develop your plugin. Key files: - `manifest.json`: Metadata for the plugin (name, version, description, etc.). - `plugin.js` or `command.js`: Main logic for the plugin or command. - `README.md`: Documentation for the plugin. ### **3. Validate Your Plugin** Use the `validate-plugin.sh` script to ensure your plugin meets OpenClaw's requirements: ```bash ~/.openclaw/skills/plugin-integration/scripts/validate-plugin.sh <plugin-directory> ``` ### **4. Integrate Your Plugin** Place your plugin in the OpenClaw plugins directory (e.g., `~/.openclaw/plugins/`) and restart OpenClaw to load it. ## **Example Plugins** ### **Hello World Plugin** A simple plugin that logs "Hello World" to the console. - **Directory**: `examples/hello-world/` - **Files**: `plugin.js`, `manifest.json`, `README.md` ### **Custom Command** A custom command that greets the user by name. - **Directory**: `examples/custom-command/` - **Files**: `command.js`, `manifest.json`, `README.md` ## **API Reference** Refer to `references/api-reference.md` for detailed documentation on OpenClaw's plugin API. ## **CLI Reference** Refer to `references/cli-reference.md` for OpenClaw CLI commands related to plugin management. ## **Best Practices** - **Modularity**: Keep plugins small and focused on a single task. - **Documentation**: Document every plugin with a `README.md` file. - **Validation**: Always validate your plugin before integration. - **Testing**: Test plugins in a development environment before deploying them. ## **Troubleshooting** - **Plugin Not Loading**: Ensure the `manifest.json` file is correctly formatted and the plugin is placed in the correct directory. - **Errors in Logic**: Use `console.log` or OpenClaw's logging utilities to debug issues. ## **Contributing** Contributions to this skill are welcome! Submit improvements via pull requests or issues on the OpenClaw GitHub repository.

path: AGENTS.md
content: # AGENTS.md - Plugin Integration Development Skill

## **Purpose**
This file provides guidelines for agents using the **Plugin Integration Development** skill to assist users in creating, developing, and integrating plugins, tools, and commands into OpenClaw.

## **When to Use This Skill**
Invoke this skill when:
- A user wants to create a new OpenClaw plugin, tool, or command.
- A user asks for help with plugin development or integration.
- A user needs examples or templates for OpenClaw plugins.
- A user wants to validate their plugin structure.

## **How to Use This Skill**
### **1. Guide Users Through Plugin Creation**
- Use the `init-plugin.sh` script to create a scaffold for the user’s plugin.
- Explain the purpose of each file in the scaffold (e.g., `manifest.json`, `plugin.js`).

### **2. Provide Examples**
- Direct users to the `examples/` directory for practical demonstrations.
- Explain how the examples work and how they can be modified.

### **3. Validate Plugins**
- Use the `validate-plugin.sh` script to ensure the user’s plugin meets OpenClaw’s requirements.
- Provide feedback on any issues found during validation.

### **4. Integrate Plugins**
- Guide users on placing their plugins in the correct directory (e.g., `~/.openclaw/plugins/`).
- Explain how to restart OpenClaw to load the plugin.

## **Key Files and Directories**
| Path                          | Purpose                                                                                     |
|-------------------------------|---------------------------------------------------------------------------------------------|
| `SKILL.md`                    | Main documentation for the skill.                                                          |
| `SOUL.md`                     | Defines the persona and tone for the skill.                                                |
| `examples/`                   | Contains example plugins and commands.                                                     |
| `scripts/init-plugin.sh`      | Script to initialize a new plugin scaffold.                                                |
| `scripts/validate-plugin.sh`  | Script to validate plugin structure and metadata.                                          |
| `references/api-reference.md` | Documentation for OpenClaw's plugin API.                                                   |
| `references/cli-reference.md` | Documentation for OpenClaw CLI commands related to plugin management.                     |

## **Best Practices for Agents**
- **Encourage Experimentation**: Remind users that examples are meant to be modified.
- **Emphasize Documentation**: Ensure users document their plugins with a `README.md` file.
- **Validate Early**: Encourage users to validate their plugins before integration.
- **Provide Context**: Explain why certain files or structures are necessary.

## **Troubleshooting**
- **Plugin Not Loading**: Check the `manifest.json` file for errors and ensure the plugin is in the correct directory.
- **Errors in Logic**: Use `console.log` or OpenClaw’s logging utilities to debug issues.
- **Validation Failures**: Provide specific feedback on what failed and how to fix it.

## **Contributing**
Agents are encouraged to contribute improvements to this skill by submitting pull requests or issues on the OpenClaw GitHub repository.

path: examples/custom-command/README.md
content: # Custom Command Plugin

## **Overview**
A custom command that greets the user by name. This example demonstrates how to create a command that accepts arguments.

## **Files**
| File            | Purpose                                                                 |
|-----------------|-------------------------------------------------------------------------|
| `command.js`    | Contains the command logic.                                             |
| `manifest.json` | Metadata for the command (name, version, description, etc.).           |

## **How It Works**
1. The command exports a `run` function.
2. OpenClaw calls the `run` function with arguments when the command is invoked.
3. The `run` function logs a greeting to the console.

## **Usage**
1. Place the command in the OpenClaw plugins directory (e.g., `~/.openclaw/plugins/`).
2. Restart OpenClaw to load the command.
3. Run the command in OpenClaw:
   ```
   /greet [name]
   ```
   Example:
   ```
   /greet Alice
   ```
   Output:
   ```
   Hello, Alice!
   ```

path: examples/custom-command/command.js
content: // Custom Command
// Greets the user by name.

module.exports = {
  name: "greet",
  description: "Greets the user by name.",
  run: (args) => {
    const name = args[0] || "there";
    console.log(`Hello, ${name}!`);
  },
};

path: examples/custom-command/manifest.json
content: {
  "name": "custom-command",
  "version": "1.0.0",
  "description": "A custom command that greets the user by name.",
  "author": "OpenClaw",
  "main": "command.js",
  "keywords": ["example", "command", "greet"]
}

path: examples/hello-world/README.md
content: # Hello World Plugin

## **Overview**
A simple plugin that logs "Hello World" to the console when loaded. This is a basic example to demonstrate how to create an OpenClaw plugin.

## **Files**
| File            | Purpose                                                                 |
|-----------------|-------------------------------------------------------------------------|
| `plugin.js`     | Contains the plugin logic.                                              |
| `manifest.json` | Metadata for the plugin (name, version, description, etc.).            |

## **How It Works**
1. The plugin exports an `init` function.
2. OpenClaw calls the `init` function when the plugin is loaded.
3. The `init` function logs "Hello World" to the console.

## **Usage**
1. Place the plugin in the OpenClaw plugins directory (e.g., `~/.openclaw/plugins/`).
2. Restart OpenClaw to load the plugin.
3. Check the console for the "Hello World!" message.

path: examples/hello-world/manifest.json
content: {
  "name": "hello-world",
  "version": "1.0.0",
  "description": "A simple plugin that logs 'Hello World' to the console.",
  "author": "OpenClaw",
  "main": "plugin.js",
  "keywords": ["example", "hello-world"]
}

path: examples/hello-world/plugin.js
content: // Hello World Plugin
// Logs "Hello World" to the console when loaded.

module.exports = {
  init: () => {
    console.log("Hello World!");
  },
};

path: references/api-reference.md
content: # OpenClaw Plugin API Reference

## **Overview**
This document provides a reference for OpenClaw's plugin API. Plugins can extend OpenClaw's functionality by adding new tools, commands, or integrations.

## **Plugin Structure**
A plugin consists of:
- An `openclaw.plugin.json` file containing metadata.
- A main JavaScript file (e.g., `index.js`).

### **`openclaw.plugin.json`**
| Field        | Type     | Description                                                                                     |
|--------------|----------|-------------------------------------------------------------------------------------------------|
| `name`       | string   | Name of the plugin (lowercase, hyphens only).                                                   |
| `version`    | string   | Version of the plugin (semver, e.g., `1.0.0`).                                                   |
| `description`| string   | Description of the plugin.                                                                      |
| `main`       | string   | Path to the main JavaScript file (default: `index.js`).                                         |
| `author`     | string   | Author of the plugin (optional).                                                                 |
| `license`    | string   | License (e.g., `MIT`, optional).                                                                  |
| `keywords`   | array    | Keywords for the plugin (optional).                                                              |
| `openclaw`   | object   | OpenClaw-specific configuration (optional).                                                       |

### **OpenClaw Configuration Object**
```json
{
  "openclaw": {
    "minVersion": "1.0.0",
    "permissions": ["network", "filesystem"]
  }
}
```

## **Plugin Lifecycle**

### **Entry Point**
```javascript
module.exports = {
  name: 'my-plugin',
  
  /**
   * Called when the plugin is loaded
   * @param {Object} context - OpenClaw context object
   */
  async onLoad(context) {
    this.context = context;
    // Initialize plugin
  },
  
  /**
   * Called when the plugin is activated
   */
  async onActivate() {
    // Plugin is now active
  },
  
  /**
   * Called when the plugin is deactivated
   */
  async onDeactivate() {
    // Clean up resources
  },
  
  /**
   * Register commands, tools, or handlers
   * @param {Object} registry - OpenClaw registry object
   */
  register(registry) {
    // Register commands, tools, etc.
  }
};
```

## **Context Object**
The `context` object passed to `onLoad` provides access to OpenClaw features:

```javascript
// Available properties depend on OpenClaw version
// Check the OpenClaw documentation for the current API

// Example context structure:
context = {
  version: '1.0.0',
  config: { ... },
  // Additional context properties
};
```

## **Registry Object**
The `registry` object passed to `register` allows registering plugin features:

```javascript
register(registry) {
  // Example: Register a command (check OpenClaw docs for current API)
  // registry.command('mycommand', this.myCommand.bind(this));
  
  // Example: Register a tool (check OpenClaw docs for current API)
  // registry.tool('mytool', this.myTool.bind(this));
}
```

> **Note**: The registry API is subject to change. Check the OpenClaw documentation for the current plugin API.

## **Best Practices**
- **Modularity**: Keep plugins small and focused on a single task.
- **Documentation**: Include a `README.md` explaining your plugin's purpose and usage.
- **Validation**: Run the validation script before installation:
  ```bash
  ~/.openclaw/skills/plugin-integration/scripts/validate-plugin.sh <plugin-dir>
  ```
- **Testing**: Test your plugin in a development environment before deploying.
- **Versioning**: Use semantic versioning (semver) for your plugin versions.

## **Example Plugin**
See `examples/hello-world/` for a complete example plugin.

## **Getting Help**
- OpenClaw Documentation: https://docs.openclaw.ai
- OpenClaw GitHub: https://github.com/openclaw/openclaw
- OpenClaw Discord: https://discord.gg/clawd

path: references/cli-reference.md
content: # OpenClaw CLI Reference for Plugin Management

## **Overview**
This document provides a reference for OpenClaw CLI commands related to plugin management.

## **Commands**
### **1. Install a Plugin**
Install a plugin into OpenClaw:
```bash
openclaw plugins install <plugin-directory>
```

### **2. Remove a Plugin**
Remove a plugin from OpenClaw:
```bash
openclaw plugins remove <plugin-name>
```

### **3. List Plugins**
List all installed plugins:
```bash
openclaw plugins list
```

### **4. Validate a Plugin**
Validate a plugin's structure and metadata using this skill's script:
```bash
~/.openclaw/skills/plugin-integration/scripts/validate-plugin.sh <plugin-directory>
```

## **Examples**
### **Install a Plugin**
```bash
openclaw plugins install ~/.openclaw/plugins/hello-world
```

### **Remove a Plugin**
```bash
openclaw plugins remove hello-world
```

### **List Plugins**
```bash
openclaw plugins list
```
Output:
```
Installed Plugins:
- hello-world (1.0.0)
- custom-command (1.0.0)
```

### **Validate a Plugin**
```bash
~/.openclaw/skills/plugin-integration/scripts/validate-plugin.sh ~/.openclaw/plugins/my-plugin
```

## **Plugin Manifest**
OpenClaw plugins use `openclaw.plugin.json` (not `manifest.json` or `manifest.yaml`):

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A description of your plugin",
  "main": "index.js",
  "author": "Your Name",
  "license": "MIT",
  "openclaw": {
    "minVersion": "1.0.0",
    "permissions": []
  }
}
```

## **Best Practices**
- **Validate Before Installing**: Always validate a plugin before installing:
```bash
~/.openclaw/skills/plugin-integration/scripts/validate-plugin.sh <plugin-directory>
```
- **Use Correct Manifest**: Use `openclaw.plugin.json`, not `manifest.json` or `manifest.yaml`
- **Include Documentation**: Add a `README.md` explaining your plugin's purpose and usage
- **Use Absolute Paths**: When installing plugins, use absolute paths to avoid issues

path: scripts/init-plugin.sh
content: #!/bin/bash

# Initialize a new OpenClaw plugin with the correct structure
# Creates openclaw.plugin.json (not manifest.json)

set -e

if [ -z "$1" ]; then
  echo "Usage: $0 <plugin-name> [output-dir]"
  echo "Example: $0 my-plugin"
  echo "         $0 my-plugin ~/.openclaw/plugins"
  exit 1
fi

PLUGIN_NAME="$1"
OUTPUT_DIR="${2:-.}"

# Validate plugin name
if [[ ! "$PLUGIN_NAME" =~ ^[a-z0-9-]+$ ]]; then
  echo "Error: Plugin name must be lowercase letters, numbers, and hyphens only."
  echo "Example: my-plugin, hello-world, data-processor"
  exit 1
fi

PLUGIN_DIR="$OUTPUT_DIR/$PLUGIN_NAME"

if [ -d "$PLUGIN_DIR" ]; then
  echo "Error: Directory $PLUGIN_DIR already exists."
  exit 1
fi

echo "🦞 Creating OpenClaw plugin: $PLUGIN_NAME"
echo ""

# Create directory structure
mkdir -p "$PLUGIN_DIR"

# Create openclaw.plugin.json (correct manifest for OpenClaw plugins)
cat > "$PLUGIN_DIR/openclaw.plugin.json" << EOF
{
  "name": "$PLUGIN_NAME",
  "version": "1.0.0",
  "description": "A new OpenClaw plugin",
  "main": "index.js",
  "author": "",
  "license": "MIT",
  "keywords": ["openclaw", "plugin"],
  "openclaw": {
    "minVersion": "1.0.0",
    "permissions": []
  }
}
EOF

# Create main entry point
cat > "$PLUGIN_DIR/index.js" << 'EOF'
/**
 * OpenClaw Plugin Entry Point
 * 
 * This file is loaded when the plugin is activated.
 */

module.exports = {
  name: '{{PLUGIN_NAME}}',
  
  /**
   * Called when the plugin is loaded
   */
  async onLoad(context) {
    this.context = context;
    console.log(`{{PLUGIN_NAME}} plugin loaded`);
  },
  
  /**
   * Called when the plugin is activated
   */
  async onActivate() {
    console.log(`{{PLUGIN_NAME}} plugin activated`);
  },
  
  /**
   * Called when the plugin is deactivated
   */
  async onDeactivate() {
    console.log(`{{PLUGIN_NAME}} plugin deactivated`);
  },
  
  /**
   * Register commands or tools
   */
  register(registry) {
    // Example: registry.command('hello', this.hello.bind(this));
    // Example: registry.tool('myTool', this.myTool.bind(this));
  },
  
  /**
   * Example command implementation
   */
  hello(args) {
    return `Hello from {{PLUGIN_NAME}}!`;
  }
};
EOF

# Replace placeholder with actual plugin name
sed -i "s/{{PLUGIN_NAME}}/$PLUGIN_NAME/g" "$PLUGIN_DIR/index.js"

# Create README
cat > "$PLUGIN_DIR/README.md" << EOF
# $PLUGIN_NAME

An OpenClaw plugin.

## Installation

\`\`\`bash
openclaw plugins install $PLUGIN_NAME
\`\`\`

## Usage

\`\`\`
openclaw $PLUGIN_NAME
\`\`\`

## Development

1. Edit \`index.js\` to add your plugin logic
2. Update \`openclaw.plugin.json\` with your plugin details
3. Test with \`openclaw plugins validate $PLUGIN_NAME\`

## License

MIT
EOF

# Create .gitignore
cat > "$PLUGIN_DIR/.gitignore" << 'EOF'
node_modules/
*.log
.env
.DS_Store
EOF

echo "✅ Plugin created successfully!"
echo ""
echo "📁 Created files:"
echo "   $PLUGIN_DIR/"
echo "   ├── openclaw.plugin.json  (manifest)"
echo "   ├── index.js              (entry point)"
echo "   ├── README.md             (documentation)"
echo "   └── .gitignore             (git ignore file)"
echo ""
echo "Next steps:"
echo "   1. Edit $PLUGIN_DIR/openclaw.plugin.json"
echo "   2. Implement your plugin in $PLUGIN_DIR/index.js"
echo "   3. Validate: ~/.openclaw/skills/plugin-integration/scripts/validate-plugin.sh $PLUGIN_DIR"
echo "   4. Install: openclaw plugins install $PLUGIN_DIR"

path: scripts/validate-plugin.sh
content: #!/bin/bash

# Validate plugin structure and metadata for OpenClaw plugins
# OpenClaw plugins use openclaw.plugin.json, not manifest.json

set -e

if [ -z "$1" ]; then
  echo "Usage: $0 <plugin-directory>"
  echo "Example: $0 ~/.openclaw/plugins/my-plugin"
  exit 1
fi

PLUGIN_DIR="$1"

if [ ! -d "$PLUGIN_DIR" ]; then
  echo "Error: Directory $PLUGIN_DIR does not exist."
  exit 1
fi

PLUGIN_NAME=$(basename "$PLUGIN_DIR")
echo "🔍 Validating plugin: $PLUGIN_NAME"
echo ""

# Check for openclaw.plugin.json (the correct manifest file for OpenClaw plugins)
MANIFEST_FILE="$PLUGIN_DIR/openclaw.plugin.json"
if [ ! -f "$MANIFEST_FILE" ]; then
  echo "❌ Error: openclaw.plugin.json not found in $PLUGIN_DIR"
  echo "   OpenClaw plugins require an openclaw.plugin.json manifest file."
  echo ""
  echo "Example manifest structure:"
  echo '{'
  echo '  "name": "my-plugin",'
  echo '  "version": "1.0.0",'
  echo '  "description": "My awesome plugin",'
  echo '  "main": "index.js",'
  echo '  "author": "Your Name"'
  echo '}'
  exit 1
fi

# Validate JSON syntax
if ! jq empty "$MANIFEST_FILE" 2>/dev/null; then
  echo "❌ Error: openclaw.plugin.json is not valid JSON."
  echo "   Run: jq . $MANIFEST_FILE"
  exit 1
fi

echo "✅ Manifest file is valid JSON"

# Check for required fields
REQUIRED_FIELDS=("name" "version")
MISSING_FIELDS=()

for field in "${REQUIRED_FIELDS[@]}"; do
  if [ "$(jq -r "has(\"$field\")" "$MANIFEST_FILE")" != "true" ]; then
    MISSING_FIELDS+=("$field")
  fi
done

if [ ${#MISSING_FIELDS[@]} -gt 0 ]; then
  echo "❌ Error: Missing required fields: ${MISSING_FIELDS[*]}"
  exit 1
fi

echo "✅ Required fields present: name, version"

# Check for main file if specified
MAIN_FILE=$(jq -r '.main // "index.js"' "$MANIFEST_FILE")
if [ -n "$MAIN_FILE" ] && [ "$MAIN_FILE" != "null" ]; then
  if [ ! -f "$PLUGIN_DIR/$MAIN_FILE" ]; then
    echo "⚠️  Warning: Main file '$MAIN_FILE' not found in $PLUGIN_DIR"
    echo "   The plugin may not load correctly."
  else
    echo "✅ Main file found: $MAIN_FILE"
  fi
fi

# Display plugin info
echo ""
echo "📋 Plugin Information:"
echo "   Name: $(jq -r '.name' "$MANIFEST_FILE")"
echo "   Version: $(jq -r '.version' "$MANIFEST_FILE")"
DESCRIPTION=$(jq -r '.description // "No description"' "$MANIFEST_FILE")
echo "   Description: $DESCRIPTION"

# Check for optional but recommended files
RECOMMENDED_FILES=("README.md" "LICENSE")
for file in "${RECOMMENDED_FILES[@]}"; do
  if [ -f "$PLUGIN_DIR/$file" ]; then
    echo "   ✅ Has $file"
  else
    echo "   ⚠️  Missing $file (recommended)"
  fi
done

echo ""
echo "✅ Plugin validation successful!"
echo "   Plugin appears ready for installation."

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal:  | SkillSpector: clean (LOW)