# OCLAWMA Skill Examples

This directory contains example implementations and templates for OCLAWMA skills.

## Contents

### `skill-template/` - Complete Skill Template

A fully-functional example skill that demonstrates all aspects of the OCLAWMA skill packaging format. Use this as a starting point for your own skills.

**Features:**
- Proper `oclawma-skill-*` naming convention
- Entry point registration in `pyproject.toml`
- Complete `SKILL.md` documentation
- Tool schema definitions
- Comprehensive test suite
- Error handling patterns

**Quick Start:**
```bash
cd skill-template
pip install -e ".[dev]"
pytest
```

### Template Structure

```
skill-template/
├── pyproject.toml              # Package configuration with entry point
├── README.md                   # General documentation
├── SKILL.md                    # Required skill specification
├── LICENSE                     # MIT License
├── src/
│   └── oclawma_skill_example/
│       ├── __init__.py         # Exports ExampleSkill
│       └── skill.py            # Skill implementation
└── tests/
    └── test_skill.py           # Test suite
```

### Key Files Explained

#### `pyproject.toml`
The most important file - defines the entry point for skill discovery:

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

#### `SKILL.md`
Required documentation file following the standard format. See the template for the complete structure.

#### `src/oclawma_skill_example/skill.py`
The skill implementation inheriting from `LazySkill`:

```python
from oclawma.skills import LazySkill, SkillMetadata

class ExampleSkill(LazySkill):
    def _load(self) -> None:
        """Initialize tools when first accessed."""
        self._tools = {
            "greet": self._greet,
            "echo": self._echo,
            "info": self._info,
        }
        self._loaded = True
    
    async def _greet(self, name: str = "World") -> dict:
        return {
            "success": True,
            "output": f"Hello, {name}!"
        }
```

## Creating Your Own Skill

1. **Copy the template:**
   ```bash
   cp -r skill-template oclawma-skill-myskill
   cd oclawma-skill-myskill
   ```

2. **Update names:**
   - Replace `example` with your skill name
   - Replace `oclawma_skill_example` with `oclawma_skill_myskill`
   - Update `ExampleSkill` to `Myskill`

3. **Update `pyproject.toml`:**
   ```toml
   name = "oclawma-skill-myskill"
   
   [project.entry-points."oclawma.skills"]
   myskill = "oclawma_skill_myskill:Myskill"
   ```

4. **Implement your tools** in `src/oclawma_skill_myskill/skill.py`

5. **Update `SKILL.md`** with your tool documentation

6. **Test and publish:**
   ```bash
   pytest
   python -m build
   python -m twine upload dist/*
   ```

## Publishing Checklist

Before publishing your skill to PyPI:

- [ ] Package name follows `oclawma-skill-*` convention
- [ ] Entry point is registered in `pyproject.toml`
- [ ] `SKILL.md` is included in package root
- [ ] All tools have proper error handling
- [ ] Tests pass with good coverage
- [ ] README includes installation and usage instructions
- [ ] License file is included
- [ ] Version is set appropriately

## See Also

- [Skill Packaging Documentation](../docs/SKILL_PACKAGING.md)
- [Main Skills README](../src/oclawma/skills/README.md)
