# `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/ADR-012-skill-system.md),
[ADR-028](../adr/ADR-028-agent-skills-standard.md), and
[ADR-030](../adr/ADR-030-skill-abstraction-definition.md) for design rationale.

---

## Schema

### `SkillConfigSchema`

```python
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`

```python
class SkillDefinition(BaseModel):
    name: str
    version: str
    description: str
    tools: list[SkillToolDescriptor]
    metadata: SkillMetadata
```

Canonical in-memory representation of a skill.

### `SkillResult`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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.

```python
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.