# Skill Domain Model

A `Skill` is a namespaced, reusable collection of tools in CleverAgents.
Skills are registered via YAML config and provide actors with a flattened
set of tools from multiple sources.

## Skill Name

Skills use a `namespace/short_name` naming pattern:

```
local/code-tools
devops/deploy-tools
```

The name is the unique identifier, validated against the pattern
`^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$`.

## Sub-models

### SkillToolRef

Reference to a named tool in the Tool Registry.

| Field  | Type  | Description                     |
|--------|-------|---------------------------------|
| `name` | `str` | Namespaced tool name reference  |

### SkillInclude

Reference to another skill to include (recursive composition).

| Field       | Type               | Default | Description                    |
|-------------|--------------------|---------|--------------------------------|
| `name`      | `str`              | (req.)  | Namespaced skill name          |
| `overrides` | `dict \| None`     | `None`  | Per-tool metadata overrides    |

### SkillInlineTool

Anonymous inline tool definition embedded in a skill.

| Field           | Type                    | Default | Description                    |
|-----------------|-------------------------|---------|--------------------------------|
| `description`   | `str`                   | (req.)  | Description of the inline tool |
| `source`        | `ToolSource`            | (req.)  | Source type                    |
| `code`          | `str \| None`           | `None`  | Inline code                    |
| `input_schema`  | `dict \| None`          | `None`  | JSON Schema for inputs         |
| `output_schema` | `dict \| None`          | `None`  | JSON Schema for outputs        |
| `capability`    | `ToolCapability \| None`| `None`  | Capability metadata            |
| `resource_slots`| `list[ResourceSlot]`    | `[]`    | Resource slot declarations     |
| `timeout`       | `int`                   | `300`   | Execution timeout (>= 1)       |

### SkillMcpSource

MCP server source for a skill.

| Field    | Type                | Default | Description                     |
|----------|---------------------|---------|---------------------------------|
| `server` | `str`               | (req.)  | MCP server command or URI       |
| `tools`  | `list[str] \| None` | `None`  | Specific tools (None = all)     |
| `env`    | `dict \| None`      | `None`  | Environment variables           |

### SkillAgentSource

Agent Skills Standard folder source.

| Field  | Type  | Description                            |
|--------|-------|----------------------------------------|
| `path` | `str` | Path to Agent Skills Standard folder   |

### SkillCapabilitySummary

Aggregated capability summary computed after resolution.

| Field                  | Type   | Default | Description                        |
|------------------------|--------|---------|------------------------------------|
| `total_tools`          | `int`  | `0`     | Total number of tools              |
| `read_only_tools`      | `int`  | `0`     | Number of read-only tools          |
| `write_tools`          | `int`  | `0`     | Number of write-capable tools      |
| `checkpointable_tools` | `int`  | `0`     | Number of checkpointable tools     |
| `has_side_effects`     | `bool` | `False` | Whether any tool has side effects  |
| `mcp_sources`          | `int`  | `0`     | Number of MCP server sources       |
| `agent_skill_sources`  | `int`  | `0`     | Number of Agent Skill sources      |

## Skill Fields

| Field             | Type                           | Default | Description                     |
|-------------------|--------------------------------|---------|---------------------------------|
| `name`            | `str`                          | (req.)  | `namespace/short_name` format   |
| `description`     | `str`                          | (req.)  | Short description               |
| `tool_refs`       | `list[str]`                    | `[]`    | Named tool references           |
| `includes`        | `list[SkillInclude]`           | `[]`    | Included skills                 |
| `anonymous_tools` | `list[SkillInlineTool]`        | `[]`    | Inline tool definitions         |
| `mcp_servers`     | `list[SkillMcpSource]`         | `[]`    | MCP server sources              |
| `agent_skills`    | `list[SkillAgentSource]`       | `[]`    | Agent Skill folder sources      |
| `overrides`       | `dict[str, dict[str, Any]]`    | `{}`    | Per-tool metadata overrides     |

## Class Methods

- `Skill.from_config(config: dict)` -- Create from a YAML config dict
- `skill.as_cli_dict()` -- Stable ordered dict for CLI rendering

## Properties

- `skill.namespace` -- Extracted namespace from name
- `skill.short_name` -- Extracted short name from name