# OCLAWMA Skill: Example

An example skill demonstrating the OCLAWMA skill packaging format.

## Overview

This is a reference implementation showing how to create pip-installable skills for OCLAWMA. It provides simple greeting and echo functionality while demonstrating:

- Proper package structure
- Entry point registration
- Tool implementation patterns
- Error handling
- Testing approach

## Installation

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

## Usage

```python
from oclawma.skills import SkillRegistry

registry = SkillRegistry()
# Skill is automatically discovered via entry points

# Greet someone
result = await registry.execute_tool("example", "greet", name="Alice")
print(result)  # {'success': True, 'output': 'Hello, Alice!'}

# Echo a message
result = await registry.execute_tool("example", "echo", message="Hello World")
print(result)  # {'success': True, 'output': 'Hello World'}

# Get skill info
result = await registry.execute_tool("example", "info")
print(result)  # {'success': True, 'output': {...}}
```

## Development

```bash
# Clone and setup
git clone https://github.com/yourusername/oclawma-skill-example.git
cd oclawma-skill-example
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

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

## Package Structure

```
oclawma-skill-example/
├── pyproject.toml          # Package config with entry point
├── README.md               # This file
├── SKILL.md                # Skill specification (required)
├── src/
│   └── oclawma_skill_example/
│       ├── __init__.py     # Exports ExampleSkill
│       └── skill.py        # Skill implementation
└── tests/
    └── test_skill.py       # Test suite
```

## Key Concepts

### Entry Point Registration

The skill registers itself via `pyproject.toml`:

```toml
[project.entry-points."oclawma.skills"]
example = "oclawma_skill_example:ExampleSkill"
```

### Skill Class

Skills inherit from `LazySkill` and implement `_load()`:

```python
class ExampleSkill(LazySkill):
    def _load(self) -> None:
        self._tools = {
            "greet": self._greet,
            "echo": self._echo,
            "info": self._info,
        }
        self._loaded = True
```

### Tool Implementation

Tools return standardized result dictionaries:

```python
async def _greet(self, name: str = "World") -> dict[str, Any]:
    try:
        return {
            "success": True,
            "output": f"Hello, {name}!",
        }
    except Exception as e:
        return {
            "success": False,
            "error": str(e),
        }
```

## License

MIT License - see LICENSE file for details.
