UAT: Actor `skills` field in YAML config is stored but never resolved at runtime — skill tools not injected into actor #3818

New issue

Open

opened 2026-04-06 06:43:07 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 06:43:07 +00:00

Owner

Metadata

Branch: fix/backlog-actor-yaml-skills-not-resolved
Commit Message: fix(actor): resolve skills from actor YAML config and inject tools at runtime
Milestone: (backlog — see note below)
Parent Epic: #392

Backlog note: This issue was discovered during autonomous operation
on milestone v3.8.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Summary

The skills field in actor YAML configuration files is defined in the schema (ActorConfigSchema) and stored in the database, but it is never automatically resolved at runtime. When an actor with a skills list runs, the tools from those skills are NOT injected into the actor's tool surface.

Specification

Per docs/specification.md line 20404:

skills | list[string] | No | List of skill names this actor can use. Each entry is a namespaced skill name (e.g., local/file-ops). Skills provide tool capabilities to the actor.

Per line 23036:

Referenced by actors: Actors reference skills by fully-qualified name. The actor's graph gains access to all tools within the referenced skills.

Per line 23095:

When an actor references a skill, it gains access to the flattened set of all tools — named tool references, anonymous tools, tools from MCP/Agent Skills/builtins, and those inherited from included child skills.

Actual Behavior

ActorConfigSchema (in src/cleveragents/actor/schema.py) defines the skills field:

skills: list[str] = Field(
    default_factory=list,
    description="Namespaced skill references (e.g. local/file-ops)",
)

However, ActorConfiguration (in src/cleveragents/actor/config.py) — the model used for parsing actor configs in the registry — does NOT have a skills field. Skills are silently dropped during config parsing.

ReactiveCleverAgentsApp (in src/cleveragents/reactive/application.py) only resolves skills when passed via the --skill CLI option at runtime:

def __init__(self, ..., skill_names: list[str] | None = None):
    self._skill_names = list(skill_names or [])
    if self._skill_names:
        self._resolve_skills()

The actor's YAML-defined skills list is never read from the config blob and passed to _resolve_skills().

Expected Behavior

When an actor with a skills list runs:

The skills field from the actor's config blob should be read
Those skills should be resolved via SkillService.resolve_tools()
The resolved tools should be injected into the actor's tool surface alongside any --skill CLI-provided skills

Impact

Critical: Actors that declare skills in their YAML config get NO tools from those skills at runtime
The skills field in actor YAML is effectively a no-op
Users who configure actors with skills expecting tool access will find the tools unavailable
This breaks the core actor-skill capability composition model described in the spec

Steps to Reproduce

Create an actor YAML with a skills reference:

name: local/my-actor
type: llm
provider: openai
model: gpt-4
skills:
  - local/file-ops

Register the skill: agents skill add --config ./file-ops.yaml
Register the actor: agents actor add local/my-actor --config ./my-actor.yaml
Run the actor: agents actor run local/my-actor "list files"
Observe: The actor does NOT have access to tools from local/file-ops

Code Locations

src/cleveragents/actor/config.py — ActorConfiguration model missing skills field
src/cleveragents/reactive/application.py — ReactiveCleverAgentsApp.__init__() doesn't read skills from actor config blob
src/cleveragents/cli/commands/_resolve_actor.py — resolve_config_files() doesn't extract skills from actor config

Subtasks

Add skills field to ActorConfiguration model in config.py
In ReactiveCleverAgentsApp, read skills from the actor's config blob and merge with CLI-provided --skill names
Ensure skill resolution happens before agent registration
Add integration tests for actor-with-skills execution
Verify skill tools are available to the actor's LLM during tool-calling
Run nox (all default sessions), fix any errors
Verify coverage >= 97% via nox -s coverage_report

Definition of Done

An actor with skills: [local/file-ops] in its YAML config has access to local/file-ops tools at runtime
Skills from YAML config and --skill CLI option are merged (not exclusive)
Tests verify skill tool injection from actor YAML config
All subtasks above are completed and checked off
A Git commit is created where the first line matches the Commit Message in Metadata exactly
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/backlog-actor-yaml-skills-not-resolved` - **Commit Message**: `fix(actor): resolve skills from actor YAML config and inject tools at runtime` - **Milestone**: *(backlog — see note below)* - **Parent Epic**: #392 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.8.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Summary The `skills` field in actor YAML configuration files is defined in the schema (`ActorConfigSchema`) and stored in the database, but it is **never automatically resolved at runtime**. When an actor with a `skills` list runs, the tools from those skills are NOT injected into the actor's tool surface. ## Specification Per `docs/specification.md` line 20404: > `skills` | list[string] | No | List of skill names this actor can use. Each entry is a namespaced skill name (e.g., `local/file-ops`). Skills provide tool capabilities to the actor. Per line 23036: > **Referenced by actors**: Actors reference skills by fully-qualified name. The actor's graph gains access to all tools within the referenced skills. Per line 23095: > When an actor references a skill, it gains access to the **flattened set of all tools** — named tool references, anonymous tools, tools from MCP/Agent Skills/builtins, and those inherited from included child skills. ## Actual Behavior 1. `ActorConfigSchema` (in `src/cleveragents/actor/schema.py`) defines the `skills` field: ```python skills: list[str] = Field( default_factory=list, description="Namespaced skill references (e.g. local/file-ops)", ) ``` 2. However, `ActorConfiguration` (in `src/cleveragents/actor/config.py`) — the model used for parsing actor configs in the registry — does **NOT** have a `skills` field. Skills are silently dropped during config parsing. 3. `ReactiveCleverAgentsApp` (in `src/cleveragents/reactive/application.py`) only resolves skills when passed via the `--skill` CLI option at runtime: ```python def __init__(self, ..., skill_names: list[str] | None = None): self._skill_names = list(skill_names or []) if self._skill_names: self._resolve_skills() ``` 4. The actor's YAML-defined `skills` list is never read from the config blob and passed to `_resolve_skills()`. ## Expected Behavior When an actor with a `skills` list runs: 1. The `skills` field from the actor's config blob should be read 2. Those skills should be resolved via `SkillService.resolve_tools()` 3. The resolved tools should be injected into the actor's tool surface alongside any `--skill` CLI-provided skills ## Impact - **Critical**: Actors that declare skills in their YAML config get NO tools from those skills at runtime - The `skills` field in actor YAML is effectively a no-op - Users who configure actors with skills expecting tool access will find the tools unavailable - This breaks the core actor-skill capability composition model described in the spec ## Steps to Reproduce 1. Create an actor YAML with a skills reference: ```yaml name: local/my-actor type: llm provider: openai model: gpt-4 skills: - local/file-ops ``` 2. Register the skill: `agents skill add --config ./file-ops.yaml` 3. Register the actor: `agents actor add local/my-actor --config ./my-actor.yaml` 4. Run the actor: `agents actor run local/my-actor "list files"` 5. Observe: The actor does NOT have access to tools from `local/file-ops` ## Code Locations - `src/cleveragents/actor/config.py` — `ActorConfiguration` model missing `skills` field - `src/cleveragents/reactive/application.py` — `ReactiveCleverAgentsApp.__init__()` doesn't read skills from actor config blob - `src/cleveragents/cli/commands/_resolve_actor.py` — `resolve_config_files()` doesn't extract skills from actor config ## Subtasks - [ ] Add `skills` field to `ActorConfiguration` model in `config.py` - [ ] In `ReactiveCleverAgentsApp`, read `skills` from the actor's config blob and merge with CLI-provided `--skill` names - [ ] Ensure skill resolution happens before agent registration - [ ] Add integration tests for actor-with-skills execution - [ ] Verify skill tools are available to the actor's LLM during tool-calling - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done - An actor with `skills: [local/file-ops]` in its YAML config has access to `local/file-ops` tools at runtime - Skills from YAML config and `--skill` CLI option are merged (not exclusive) - Tests verify skill tool injection from actor YAML config - All subtasks above are completed and checked off - A Git commit is created where the first line matches the Commit Message in Metadata exactly - The commit is pushed to the remote on the branch matching the Branch in Metadata exactly - The commit is submitted as a pull request to `master`, reviewed, and merged before this issue is marked done - All nox stages pass - Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 06:43:22 +00:00

#392 Epic: Actor YAML & Compiler

freemo referenced this issue

2026-04-06 06:44:13 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo added the

Points

label

2026-04-06 06:50:03 +00:00

freemo referenced this issue

2026-04-06 06:51:25 +00:00