freemo
e9c96c3d0c
CI / build (push) Successful in 17s
CI / lint (push) Failing after 19s
CI / helm (push) Successful in 34s
CI / security (push) Failing after 42s
CI / quality (push) Has been cancelled
CI / unit_tests (push) Has been cancelled
CI / e2e_tests (push) Has been cancelled
CI / integration_tests (push) Has been cancelled
CI / typecheck (push) Has been cancelled
CI / benchmark-publish (push) Has been cancelled
CI / coverage (push) Has been cancelled
CI / benchmark-regression (push) Has been cancelled
CI / docker (push) Has been cancelled
CI / status-check (push) Has been cancelled
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
178 lines
3.8 KiB
Markdown
178 lines
3.8 KiB
Markdown
# `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.
|