freemo
e9c96c3d0c
Add docs/api/ with per-module API documentation for core, a2a, actor, skills, tool, mcp, resource, and config packages. Add docs/architecture.md with a developer-oriented system overview including component map, layer diagram, plan lifecycle, and key design decisions. Update mkdocs.yml nav to expose both new sections. ISSUES CLOSED: #N/A
3.8 KiB
cleveragents.skills — Skill Framework
The skills package implements the three-tier progressive disclosure model
for agent skills: discover → activate → deactivate. Skills are
composable, versioned capability bundles that expose one or more tools to
an actor.
See ADR-012, ADR-028, and ADR-030 for design rationale.
Schema
SkillConfigSchema
from cleveragents.skills import SkillConfigSchema
config = SkillConfigSchema.from_yaml_file("examples/skills/single-tool.yaml")
Pydantic model for loading, validating, and normalizing skill YAML configuration files.
Protocol Types
SkillDefinition
class SkillDefinition(BaseModel):
name: str
version: str
description: str
tools: list[SkillToolDescriptor]
metadata: SkillMetadata
Canonical in-memory representation of a skill.
SkillResult
class SkillResult(BaseModel):
success: bool
output: Any
error: SkillError | None = None
SkillError / SkillErrorType
Structured error from skill execution. SkillErrorType is an enum:
TOOL_NOT_FOUND, EXECUTION_FAILED, VALIDATION_FAILED,
PERMISSION_DENIED, TIMEOUT.
map_tool_error(exc) → SkillError
Converts a tool-layer exception into a SkillError.
Registry
SkillRegistry
from cleveragents.skills import SkillRegistry
registry = SkillRegistry()
registry.register(skill_definition)
skill = registry.get("deploy-to-staging")
Thread-safe in-memory registry. Supports namespace-qualified names.
SkillRefreshResult
Returned by SkillRegistry.refresh_all(). Contains counts of added,
updated, and removed skills.
Discovery
discover_agent_skills(paths) → DiscoveryResult
from cleveragents.skills import discover_agent_skills
result = discover_agent_skills([Path("./skills/")])
for skill in result.skills:
print(skill.name, skill.version)
Scans one or more directories for AgentSkills-compatible skill bundles.
DiscoveryResult
class DiscoveryResult:
skills: list[DiscoveredAgentSkill]
conflicts: list[DiscoveryConflict]
register_discovered_skills(result, registry)
Bulk-registers all discovered skills into a SkillRegistry, skipping
conflicting entries and logging warnings.
parse_agent_skills_paths(raw) → list[Path]
Parses a colon-separated path string (e.g. from an env var) into a list
of Path objects.
AgentSkills Loader
AgentSkillLoader
from cleveragents.skills import AgentSkillLoader
loader = AgentSkillLoader.from_folder(Path("./skills/deploy-to-staging"))
spec: AgentSkillSpec = loader.load()
Implements the AgentSkills.io standard for loading skill bundles from a directory.
AgentSkillSpec
class AgentSkillSpec(BaseModel):
name: str
version: str
steps: list[SkillStep]
tools: list[AgentSkillToolDescriptor]
resource_slots: list[AgentSkillResourceSlot]
Inline Executor
InlineToolExecutor
Executes skill steps that are implemented as inline Python callables rather than external tool calls.
from cleveragents.skills import InlineToolExecutor
executor = InlineToolExecutor()
result: InlineToolResult = await executor.execute(step, context)
Execution Context
SkillContext
Carries runtime state during skill execution: active session, bound resources, cancellation token, and invocation history.
ToolInvocationRecord
Immutable record of a single tool call made during skill execution, including inputs, outputs, duration, and error (if any).
SkillExecutionError
Raised when a skill step fails unrecoverably.