UAT: `SkillService.add_skill` sets `description` to empty string when omitted, causing Pydantic `ValidationError` instead of a user-friendly error #2053

New issue

Open

opened 2026-04-03 03:42:53 +00:00 by freemo · 0 comments

freemo commented

2026-04-03 03:42:53 +00:00

Owner

Background and Context

A Skill is a composable, namespaced collection of tools in CleverAgents. Per the specification, the description field in a skill YAML configuration file is optional. However, a mismatch between the SkillConfigSchema (which allows description: str | None) and the Skill domain model (which requires description with min_length=1) causes a cryptic Pydantic ValidationError when a user omits the description field from their skill YAML.

This bug surfaces during agents skill add and affects any user who follows the spec-compliant pattern of omitting the optional description field.

Current Behavior

When a skill YAML omits the description field, SkillService._schema_to_skill_dict() sets data["description"] = "" (empty string). This is passed to Skill.from_config(), which attempts to construct a Skill domain model. Because Skill declares description: str = Field(..., min_length=1, ...), Pydantic raises a ValidationError with a cryptic min_length constraint message — not a user-friendly error.

Affected code locations:

src/cleveragents/application/services/skill_service.py, method _schema_to_skill_dict():

if config.description:
    data["description"] = config.description
else:
    data["description"] = ""  # BUG: empty string fails Skill validation

src/cleveragents/domain/models/core/skill.py, Skill model:
```
description: str = Field(..., min_length=1, ...)
```

Steps to reproduce:

Create a skill YAML file without a description field:

name: local/my-skill
tools:
  - name: builtin/read_file

Run agents skill add --config ./my-skill.yaml
Observe a Pydantic ValidationError about min_length constraint — not a helpful message.

Expected Behavior

When description is omitted from the skill YAML:

Either a sensible default is used (e.g., the skill's name value), OR
A clear, user-friendly error message is raised explaining that description is required.

Per the specification, description is optional in the YAML schema, so the preferred fix is to default to the skill's name when no description is provided:

data["description"] = config.description or config.name

Acceptance Criteria

agents skill add with a YAML missing description no longer raises a Pydantic ValidationError
The skill is created successfully using the skill's name as the default description when none is provided
A Behave unit test covers the case where description is omitted from the YAML config
A Behave unit test covers the case where description is explicitly provided and is used as-is
All nox stages pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e integration_tests)
Coverage remains >= 97%

Supporting Information

Severity: High — affects all users following the spec-compliant pattern of omitting description
Feature Area: Skill composition and management (agents skill add)
Root Cause: SkillConfigSchema.description is str | None (optional), but Skill.description requires str with min_length=1. The service bridges these with "", which violates the domain constraint.
Preferred Fix: Option 1 — use config.description or config.name as the default, keeping description optional in the YAML schema (non-breaking change).
Alternative Fix: Option 2 — make SkillConfigSchema.description required (breaking change to the schema, not preferred).
Spec Reference: The specification states description is optional in skill YAML configuration.

Metadata

Branch: fix/skill-service-empty-description-validation-error
Commit Message: fix(skill-service): default description to skill name when omitted in YAML config
Milestone: v3.7.0
Parent Epic: #936

Subtasks

Reproduce the bug locally with a minimal YAML fixture
Update SkillService._schema_to_skill_dict() to use config.description or config.name as the default
Write a Behave scenario: skill YAML without description → skill created with name as description
Write a Behave scenario: skill YAML with description → skill created with provided description
Run nox -e typecheck and resolve any type errors
Run nox -e unit_tests and confirm all tests pass
Run nox -e coverage_report and confirm coverage >= 97%
Run full nox suite and confirm all stages pass

Definition of Done

SkillService._schema_to_skill_dict() no longer sets description to ""
agents skill add with a description-less YAML succeeds and uses the skill name as the default description
Behave unit tests cover both the omitted and provided description cases
nox -e typecheck passes with no errors
nox -e unit_tests passes with no failures
All nox stages pass
Coverage >= 97%

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

## Background and Context A **Skill** is a composable, namespaced collection of tools in CleverAgents. Per the specification, the `description` field in a skill YAML configuration file is **optional**. However, a mismatch between the `SkillConfigSchema` (which allows `description: str | None`) and the `Skill` domain model (which requires `description` with `min_length=1`) causes a cryptic Pydantic `ValidationError` when a user omits the `description` field from their skill YAML. This bug surfaces during `agents skill add` and affects any user who follows the spec-compliant pattern of omitting the optional `description` field. ## Current Behavior When a skill YAML omits the `description` field, `SkillService._schema_to_skill_dict()` sets `data["description"] = ""` (empty string). This is passed to `Skill.from_config()`, which attempts to construct a `Skill` domain model. Because `Skill` declares `description: str = Field(..., min_length=1, ...)`, Pydantic raises a `ValidationError` with a cryptic `min_length` constraint message — not a user-friendly error. **Affected code locations:** - `src/cleveragents/application/services/skill_service.py`, method `_schema_to_skill_dict()`: ```python if config.description: data["description"] = config.description else: data["description"] = "" # BUG: empty string fails Skill validation ``` - `src/cleveragents/domain/models/core/skill.py`, `Skill` model: ```python description: str = Field(..., min_length=1, ...) ``` **Steps to reproduce:** 1. Create a skill YAML file without a `description` field: ```yaml name: local/my-skill tools: - name: builtin/read_file ``` 2. Run `agents skill add --config ./my-skill.yaml` 3. Observe a Pydantic `ValidationError` about `min_length` constraint — not a helpful message. ## Expected Behavior When `description` is omitted from the skill YAML: - Either a sensible default is used (e.g., the skill's `name` value), OR - A clear, user-friendly error message is raised explaining that `description` is required. Per the specification, `description` is optional in the YAML schema, so the preferred fix is to default to the skill's `name` when no description is provided: ```python data["description"] = config.description or config.name ``` ## Acceptance Criteria - [ ] `agents skill add` with a YAML missing `description` no longer raises a Pydantic `ValidationError` - [ ] The skill is created successfully using the skill's `name` as the default `description` when none is provided - [ ] A Behave unit test covers the case where `description` is omitted from the YAML config - [ ] A Behave unit test covers the case where `description` is explicitly provided and is used as-is - [ ] All nox stages pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e integration_tests`) - [ ] Coverage remains >= 97% ## Supporting Information - **Severity**: High — affects all users following the spec-compliant pattern of omitting `description` - **Feature Area**: Skill composition and management (`agents skill add`) - **Root Cause**: `SkillConfigSchema.description` is `str | None` (optional), but `Skill.description` requires `str` with `min_length=1`. The service bridges these with `""`, which violates the domain constraint. - **Preferred Fix**: Option 1 — use `config.description or config.name` as the default, keeping `description` optional in the YAML schema (non-breaking change). - **Alternative Fix**: Option 2 — make `SkillConfigSchema.description` required (breaking change to the schema, not preferred). - **Spec Reference**: The specification states `description` is optional in skill YAML configuration. ## Metadata - **Branch**: `fix/skill-service-empty-description-validation-error` - **Commit Message**: `fix(skill-service): default description to skill name when omitted in YAML config` - **Milestone**: v3.7.0 - **Parent Epic**: #936 ## Subtasks - [ ] Reproduce the bug locally with a minimal YAML fixture - [ ] Update `SkillService._schema_to_skill_dict()` to use `config.description or config.name` as the default - [ ] Write a Behave scenario: skill YAML without `description` → skill created with `name` as description - [ ] Write a Behave scenario: skill YAML with `description` → skill created with provided description - [ ] Run `nox -e typecheck` and resolve any type errors - [ ] Run `nox -e unit_tests` and confirm all tests pass - [ ] Run `nox -e coverage_report` and confirm coverage >= 97% - [ ] Run full `nox` suite and confirm all stages pass ## Definition of Done - [ ] `SkillService._schema_to_skill_dict()` no longer sets `description` to `""` - [ ] `agents skill add` with a description-less YAML succeeds and uses the skill name as the default description - [ ] Behave unit tests cover both the omitted and provided `description` cases - [ ] `nox -e typecheck` passes with no errors - [ ] `nox -e unit_tests` passes with no failures - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.7.0 milestone

2026-04-03 03:42:58 +00:00

freemo added a new dependency

2026-04-03 03:43:26 +00:00

#936 Epic: Output Rendering Pipeline Integration — Wire Commands to OutputSession Framework

freemo referenced this issue

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

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

freemo referenced this issue

2026-04-03 03:51:15 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 691 — v3.7.0 #2079

freemo referenced this issue