forked from cleveragents/cleveragents-core
CoreRasurae
92 lines
3.3 KiB
Markdown
92 lines
3.3 KiB
Markdown
# 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 |
|