cleveragents-core/docs/reference/skill_registry.md

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

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