# Skill Execution -- Technical Specification

**Version**: v1.0.0 | **Status**: Active | **Last Updated**: March 2026

## Overview

Provides runtime execution of skills with parameter validation, error handling, timeout enforcement, sequential chaining, and execution logging. Wraps skill calls with structured error reporting and timing.

## Architecture

Single-class design: `SkillExecutor` acts as a facade over skill execution, adding validation, logging, timing, and timeout capabilities. Timeout enforcement uses a single-thread `ThreadPoolExecutor`. Chaining passes each skill's output as `input=` to the next.

## Key Classes

### `SkillExecutor`

| Method | Parameters | Returns | Description |
|--------|-----------|---------|-------------|
| `__init__` | `max_workers: int = 4` | `None` | Initialize with max concurrent workers |
| `execute` | `skill, **kwargs` | `Any` | Validate params, execute, log result with timing |
| `execute_with_timeout` | `skill, timeout: float, **kwargs` | `Any` | Execute with timeout enforcement; raises `SkillExecutionError` on timeout |
| `execute_chain` | `skills: list, **kwargs` | `Any` | Sequential execution; first skill gets kwargs, rest get `input=previous_result` |
| `get_execution_log` | | `list[dict]` | Return copy of execution log entries |
| `clear_log` | | `None` | Clear all execution log entries |

### `SkillExecutionError` (Exception)

Raised when skill execution fails for any reason: parameter validation failure, runtime exception, or timeout.

### Execution Log Entry Format

| Field | Type | Description |
|-------|------|-------------|
| `skill` | `str` | Skill name from metadata |
| `status` | `str` | `"success"` or `"error"` |
| `elapsed` | `float` | Wall-clock execution time in seconds (`time.monotonic`) |
| `error` | `str` | Error message (only present on failure) |

## Dependencies

- **Internal**: `codomyrmex.logging_monitoring.core.logger_config`
- **External**: `time`, `concurrent.futures.ThreadPoolExecutor` (stdlib)

## Constraints

- `execute` calls `skill.validate_params(**kwargs)` if the method exists; validation errors raise `SkillExecutionError`.
- `execute_with_timeout` uses a `ThreadPoolExecutor(max_workers=1)` per call; `FuturesTimeoutError` is caught and re-raised as `SkillExecutionError`.
- `execute_chain` raises `SkillExecutionError` for empty skill lists.
- All timing uses `time.monotonic()` for accuracy.
- Zero-mock: real skill execution only, `NotImplementedError` for unimplemented paths.

## Error Handling

- All exceptions from skill execution are caught, logged, and re-raised as `SkillExecutionError` with the original exception chained via `from e`.
- `SkillExecutionError` from validation is re-raised directly without wrapping.
- All errors logged before propagation.

## Navigation

- **Self**: `SPEC.md`
- **Parent**: [../README.md](../README.md)
- **Readme**: [README.md](README.md)
- **Agents**: [AGENTS.md](AGENTS.md)
- **Repository Root**: [README.md](../../../../README.md)
