# Skill: example

## Metadata

| Field | Value |
|-------|-------|
| **Name** | `example` |
| **Version** | `1.0.0` |
| **Package** | `oclawma-skill-example` |
| **Category** | `utilities` |
| **Author** | `Your Name <you@example.com>` |
| **License** | `MIT` |
| **Python** | `>=3.9` |

## Description

An example skill demonstrating the OCLAWMA skill packaging format. This skill provides basic greeting and echo functionality to illustrate how to create pip-installable skills.

## Installation

```bash
pip install oclawma-skill-example
```

Or install from source:

```bash
git clone https://github.com/yourusername/oclawma-skill-example.git
cd oclawma-skill-example
pip install -e .
```

## Configuration

No configuration required. This skill works out of the box.

Optional environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `EXAMPLE_GREETING_PREFIX` | `"Hello"` | Prefix used in greetings |

## Tools

### `greet`

Generate a personalized greeting message.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `name` | `string` | No | `"World"` | Name to greet |
| `enthusiastic` | `boolean` | No | `false` | Add exclamation marks |

**Returns:** `string`

**Example:**
```python
# Simple greeting
result = await registry.execute_tool("example", "greet")
# Returns: {"success": true, "output": "Hello, World!"}

# Personalized greeting
result = await registry.execute_tool("example", "greet", name="Alice")
# Returns: {"success": true, "output": "Hello, Alice!"}

# Enthusiastic greeting
result = await registry.execute_tool("example", "greet", name="Bob", enthusiastic=True)
# Returns: {"success": true, "output": "Hello, Bob!!!"}
```

### `echo`

Echo back the provided message.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `message` | `string` | Yes | - | Message to echo |
| `uppercase` | `boolean` | No | `false` | Convert to uppercase |

**Returns:** `string`

**Example:**
```python
result = await registry.execute_tool("example", "echo", message="Hello World")
# Returns: {"success": true, "output": "Hello World"}

result = await registry.execute_tool("example", "echo", message="Hello World", uppercase=True)
# Returns: {"success": true, "output": "HELLO WORLD"}
```

### `info`

Get information about this skill.

**Parameters:**

None

**Returns:** `object`

**Example:**
```python
result = await registry.execute_tool("example", "info")
# Returns:
# {
#   "success": true,
#   "output": {
#     "name": "example",
#     "version": "1.0.0",
#     "author": "Your Name",
#     "tools": ["greet", "echo", "info"]
#   }
# }
```

## Dependencies

- `oclawma>=0.1.0` - Core OCLAWMA framework

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `EXAMPLE_GREETING_PREFIX` | No | Custom greeting prefix (default: "Hello") |

## Error Handling

All tools return a standardized result dictionary:

```python
{
    "success": bool,      # True if operation succeeded
    "output": any,        # Result data on success
    "error": str | None,  # Error message on failure
}
```

Common error conditions:
- Missing required parameters return `{"success": false, "error": "Missing required parameter: message"}`
- Invalid parameter types return `{"success": false, "error": "Invalid type for parameter: ..."}`

## Testing

Run the test suite:

```bash
pytest tests/ -v
```

## Development

```bash
# Clone the repository
git clone https://github.com/yourusername/oclawma-skill-example.git
cd oclawma-skill-example

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
black src tests
ruff check src tests
mypy src
```

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
