# Skill Registry

The Skill Registry provides persistent storage for skill definitions in
CleverAgents. Skills are namespaced, reusable collections of tools
registered via YAML config and persisted to the `skills` and
`skill_items` database tables.

## Registration Behavior

Skills are registered with a namespaced name (`namespace/short_name`)
as the unique identifier. The registry enforces:

- **Name uniqueness**: Duplicate names are rejected with
  `DuplicateSkillError`.
- **Name validation**: Names must match `^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$`.
- **Cascading deletes**: Removing a skill cascades to all child
  `skill_items` rows.

## Skill Items

Each skill stores its components as ordered items in the `skill_items`
table. The `item_type` discriminator distinguishes:

| item_type      | Description                              |
|----------------|------------------------------------------|
| `tool_ref`     | Reference to a named tool in the registry |
| `include`      | Recursive inclusion of another skill      |
| `inline_tool`  | Anonymous tool defined inline             |
| `mcp_source`   | MCP server tool source                    |
| `agent_source` | Agent Skills Standard folder source       |

Items are stored with a stable `item_order` to preserve definition
ordering across round-trips.

## Filters

The `SkillRegistryService.list_skills()` method supports:

- **Namespace filter**: Pass `namespace="local"` to list only skills
  in the `local` namespace.

## Service API

```python
from cleveragents.application.services import SkillRegistryService
from cleveragents.infrastructure.database.repositories import SkillRepository

svc = SkillRegistryService(skill_repo=SkillRepository(session_factory))

# Register
svc.add_skill(skill)

# Retrieve
skill = svc.get_skill("local/code-tools")

# List with filter
skills = svc.list_skills(namespace="local")

# Update
svc.update_skill(updated_skill)

# Remove
svc.remove_skill("local/code-tools")
```

## Database Schema

### skills

| Column         | Type         | Description                     |
|----------------|--------------|---------------------------------|
| name           | String(255)  | PK, namespaced name             |
| namespace      | String(100)  | Extracted namespace              |
| short_name     | String(150)  | Extracted short name             |
| description    | Text         | Skill description                |
| version        | String(50)   | Optional version string          |
| metadata_json  | Text         | JSON metadata (overrides, etc.)  |
| created_at     | String(30)   | ISO-8601 creation timestamp      |
| updated_at     | String(30)   | ISO-8601 update timestamp        |

### skill_items

| Column      | Type         | Description                          |
|-------------|--------------|--------------------------------------|
| id          | Integer      | Auto-increment PK                    |
| skill_name  | String(255)  | FK to skills.name (CASCADE)          |
| item_type   | String(30)   | Discriminator (tool_ref, etc.)       |
| item_name   | String(500)  | Item identifier or name              |
| item_config | Text         | Optional JSON configuration          |
| item_order  | Integer      | Stable ordering index                |
| created_at  | String(30)   | ISO-8601 creation timestamp          |