cleveragents/cleveragents-core

Fork 3

UAT: `SkillService._schema_to_skill_dict()` silently drops tool reference override fields — description, writes, checkpointable overrides lost on skill registration #2891

New issue

Open

opened 2026-04-05 02:42:52 +00:00 by freemo · 2 comments

freemo commented

2026-04-05 02:42:52 +00:00

Owner

Metadata

Branch: fix/skill-service-tool-ref-override-fields
Commit Message: fix(skills): preserve tool reference override fields in SkillService._schema_to_skill_dict()
Milestone: v3.7.0
Parent Epic: #374

Background

The SkillService._schema_to_skill_dict() method in
src/cleveragents/application/services/skill_service.py silently discards
tool reference override fields when a skill is registered. The skill YAML
schema (docs/schema/skill.schema.yaml) explicitly defines that tool
references may include per-skill override fields — description, writes,
and checkpointable — and the SkillToolRefSchema model in
src/cleveragents/skills/schema.py correctly captures all three. However,
the mapping step reduces each tool reference to only its name, causing
silent data loss.

Expected Behavior

When a skill YAML contains tool reference overrides such as:

name: local/safe-git
description: "Git operations with write protection"
tools:
  - name: builtin/git_commit
    writes: false
    description: "Read-only git commit viewer"

…the writes: false and description override must be preserved through
registration and be visible in agents skill show local/safe-git. The
SkillToolRefSchema already captures these fields; _schema_to_skill_dict()
must propagate them.

Actual Behavior

In src/cleveragents/application/services/skill_service.py,
_schema_to_skill_dict() maps tools as:

if config.tools:
    data["tools"] = [t.name for t in config.tools]

Only the tool name is preserved. The description, writes, and
checkpointable override fields are silently dropped. Consequences:

Users cannot override a tool's description within a skill context.
Users cannot override a tool's writes capability flag within a skill context.
Users cannot override a tool's checkpointable flag within a skill context.

These are spec-defined features that are accepted by the schema validator but
silently discarded during registration — a correctness bug with no error or
warning surfaced to the user.

Steps to Reproduce

Create a skill YAML with tool reference overrides:

name: local/safe-git
description: "Git operations with write protection"
tools:
  - name: builtin/git_commit
    writes: false
    description: "Read-only git commit viewer"

Register: agents skill add --config safe-git.yaml
Inspect: agents skill show local/safe-git
Observe that writes: false and the description override are absent from
the stored skill.

Affected Code Locations

File	Symbol	Issue
`src/cleveragents/application/services/skill_service.py`	`_schema_to_skill_dict()`	Reduces tool refs to name-only list
`src/cleveragents/skills/schema.py`	`SkillToolRefSchema`	Correctly captures all override fields (no change needed)
`docs/schema/skill.schema.yaml`	tool reference definition	Spec source of truth for override fields

Severity

High — Tool reference overrides are a spec-defined feature for
customising tool behaviour within a skill context. Silent data loss during
registration is a correctness bug; users receive no error and cannot detect
the loss without inspecting stored state.

Subtasks

Reproduce the bug with a failing Behave scenario (TDD — write test first)
Update _schema_to_skill_dict() to emit a dict per tool ref (preserving name, description, writes, checkpointable) instead of a plain name string
Update any downstream consumers of data["tools"] that currently expect a list of strings to handle the new list-of-dicts format
Verify SkillToolRefSchema round-trips correctly through serialisation/deserialisation
Add/update Behave unit test scenarios covering all three override fields (description, writes, checkpointable) — both set and unset (None) cases
Add Robot Framework integration test: register a skill with overrides, assert overrides are present in agents skill show output
Run nox -e typecheck — ensure no new Pyright errors
Run nox -e lint — ensure no new lint violations
Run nox -e coverage_report — confirm coverage ≥ 97%
Update docs/schema/skill.schema.yaml or inline docstrings if any clarification is needed

Definition of Done

All subtasks above are checked
A skill registered with description, writes, and checkpointable overrides on a tool ref retains those values after registration
agents skill show displays the overrides correctly
No silent data loss — if a field is present in the YAML it must be present in the stored skill
All nox stages pass (lint, typecheck, unit_tests, integration_tests, coverage_report)
Coverage ≥ 97%
Commit message matches: fix(skills): preserve tool reference override fields in SkillService._schema_to_skill_dict()
PR is linked to this issue and this issue is closed on merge

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

## Metadata - **Branch**: `fix/skill-service-tool-ref-override-fields` - **Commit Message**: `fix(skills): preserve tool reference override fields in SkillService._schema_to_skill_dict()` - **Milestone**: v3.7.0 - **Parent Epic**: #374 ## Background The `SkillService._schema_to_skill_dict()` method in `src/cleveragents/application/services/skill_service.py` silently discards tool reference override fields when a skill is registered. The skill YAML schema (`docs/schema/skill.schema.yaml`) explicitly defines that tool references may include per-skill override fields — `description`, `writes`, and `checkpointable` — and the `SkillToolRefSchema` model in `src/cleveragents/skills/schema.py` correctly captures all three. However, the mapping step reduces each tool reference to only its `name`, causing silent data loss. ## Expected Behavior When a skill YAML contains tool reference overrides such as: ```yaml name: local/safe-git description: "Git operations with write protection" tools: - name: builtin/git_commit writes: false description: "Read-only git commit viewer" ``` …the `writes: false` and `description` override must be preserved through registration and be visible in `agents skill show local/safe-git`. The `SkillToolRefSchema` already captures these fields; `_schema_to_skill_dict()` must propagate them. ## Actual Behavior In `src/cleveragents/application/services/skill_service.py`, `_schema_to_skill_dict()` maps tools as: ```python if config.tools: data["tools"] = [t.name for t in config.tools] ``` Only the tool `name` is preserved. The `description`, `writes`, and `checkpointable` override fields are **silently dropped**. Consequences: 1. Users cannot override a tool's description within a skill context. 2. Users cannot override a tool's `writes` capability flag within a skill context. 3. Users cannot override a tool's `checkpointable` flag within a skill context. These are spec-defined features that are accepted by the schema validator but silently discarded during registration — a correctness bug with no error or warning surfaced to the user. ## Steps to Reproduce 1. Create a skill YAML with tool reference overrides: ```yaml name: local/safe-git description: "Git operations with write protection" tools: - name: builtin/git_commit writes: false description: "Read-only git commit viewer" ``` 2. Register: `agents skill add --config safe-git.yaml` 3. Inspect: `agents skill show local/safe-git` 4. Observe that `writes: false` and the description override are absent from the stored skill. ## Affected Code Locations | File | Symbol | Issue | |---|---|---| | `src/cleveragents/application/services/skill_service.py` | `_schema_to_skill_dict()` | Reduces tool refs to name-only list | | `src/cleveragents/skills/schema.py` | `SkillToolRefSchema` | Correctly captures all override fields (no change needed) | | `docs/schema/skill.schema.yaml` | tool reference definition | Spec source of truth for override fields | ## Severity **High** — Tool reference overrides are a spec-defined feature for customising tool behaviour within a skill context. Silent data loss during registration is a correctness bug; users receive no error and cannot detect the loss without inspecting stored state. ## Subtasks - [ ] Reproduce the bug with a failing Behave scenario (TDD — write test first) - [ ] Update `_schema_to_skill_dict()` to emit a dict per tool ref (preserving `name`, `description`, `writes`, `checkpointable`) instead of a plain name string - [ ] Update any downstream consumers of `data["tools"]` that currently expect a list of strings to handle the new list-of-dicts format - [ ] Verify `SkillToolRefSchema` round-trips correctly through serialisation/deserialisation - [ ] Add/update Behave unit test scenarios covering all three override fields (`description`, `writes`, `checkpointable`) — both set and unset (None) cases - [ ] Add Robot Framework integration test: register a skill with overrides, assert overrides are present in `agents skill show` output - [ ] Run `nox -e typecheck` — ensure no new Pyright errors - [ ] Run `nox -e lint` — ensure no new lint violations - [ ] Run `nox -e coverage_report` — confirm coverage ≥ 97% - [ ] Update `docs/schema/skill.schema.yaml` or inline docstrings if any clarification is needed ## Definition of Done - [ ] All subtasks above are checked - [ ] A skill registered with `description`, `writes`, and `checkpointable` overrides on a tool ref retains those values after registration - [ ] `agents skill show` displays the overrides correctly - [ ] No silent data loss — if a field is present in the YAML it must be present in the stored skill - [ ] All nox stages pass (`lint`, `typecheck`, `unit_tests`, `integration_tests`, `coverage_report`) - [ ] Coverage ≥ 97% - [ ] Commit message matches: `fix(skills): preserve tool reference override fields in SkillService._schema_to_skill_dict()` - [ ] PR is linked to this issue and this issue is closed on merge --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.7.0 milestone

2026-04-05 02:43:03 +00:00

freemo added a new dependency

2026-04-05 02:43:14 +00:00

#374 Legendary: Actors, Skills & Tool Execution (Workstream C)

freemo referenced this issue

2026-04-05 02:44:00 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2875

freemo commented

2026-04-05 02:44:46 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: High (confirmed) — Tool reference override fields silently dropped means skill authors cannot customize tool behavior as the spec requires.
MoSCoW: Should Have — Spec-required tool override fields are important for skill customization but basic skill registration works.

Valid UAT finding.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: High (confirmed) — Tool reference override fields silently dropped means skill authors cannot customize tool behavior as the spec requires. - **MoSCoW**: Should Have — Spec-required tool override fields are important for skill customization but basic skill registration works. Valid UAT finding. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 02:47:49 +00:00

[CA-AUTO] Backlog Groomer — groomer-1 — Session Tracker #2771

freemo referenced this issue

2026-04-05 06:15:22 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo commented

2026-04-05 06:17:40 +00:00

Author

Owner

Starting implementation on branch fix/skill-service-tool-ref-override-fields.

Plan:

Write failing Behave scenario (TDD) to reproduce the bug
Fix _schema_to_skill_dict() to emit dicts with name, description, writes, checkpointable instead of plain strings
Update Skill.from_config() to handle the new list-of-dicts format for tool_refs
Add Robot Framework integration test
Run all quality gates

Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

Starting implementation on branch `fix/skill-service-tool-ref-override-fields`. **Plan:** 1. Write failing Behave scenario (TDD) to reproduce the bug 2. Fix `_schema_to_skill_dict()` to emit dicts with `name`, `description`, `writes`, `checkpointable` instead of plain strings 3. Update `Skill.from_config()` to handle the new list-of-dicts format for `tool_refs` 4. Add Robot Framework integration test 5. Run all quality gates --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker

freemo referenced this issue

2026-04-05 06:33:04 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094

freemo referenced this issue

2026-04-05 07:21:47 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094