bug(skills): `SkillConfigSchema` uses `agent_skill_folders` field name instead of spec-required `agent_skills` — spec-compliant skill YAML files are rejected #2107

New issue

Open

opened 2026-04-03 04:07:23 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 04:07:23 +00:00

Owner

Metadata

Branch: fix/skill-config-schema-agent-skills-field-name
Commit Message: fix(skills): rename SkillConfigSchema field from agent_skill_folders to agent_skills per spec
Milestone: v3.7.0
Parent Epic: #392

Background

The SkillConfigSchema in src/cleveragents/skills/schema.py uses the field name agent_skill_folders for Agent Skills Standard folder references, but the specification defines this field as agent_skills. This means any skill YAML file written according to the specification will fail validation with a Pydantic extra="forbid" error.

Bug Report

What was tested:
Code-level analysis of src/cleveragents/skills/schema.py against docs/specification.md skill YAML configuration section.

Expected behavior (from spec):
The skill YAML configuration should accept agent_skills as the field name for Agent Skills Standard folder references:

skill:
  name: local/devops-toolkit
  agent_skills:
    - path: ./skills/code-review-checklist
      sandbox_policy: none

Actual behavior:
The SkillConfigSchema defines the field as agent_skill_folders:

agent_skill_folders: list[SkillAgentFolderSchema] = Field(
    default_factory=list,
    description="Agent Skills Standard folder references.",
)

The camelCase mapping is agentSkillFolders → agent_skill_folders. A skill YAML using agent_skills: (as the spec requires) will fail with a Pydantic validation error because extra="forbid" is set on SkillConfigSchema.

Code locations:

src/cleveragents/skills/schema.py, SkillConfigSchema class, agent_skill_folders field (line ~280)
src/cleveragents/skills/schema.py, _CAMEL_TO_SNAKE dict — maps agentSkillFolders → agent_skill_folders but spec uses agent_skills

Steps to reproduce:

Create a skill YAML file using the spec-compliant field name:

name: local/test-skill
description: Test skill
agent_skills:
  - path: ./skills/my-skill

Call SkillConfigSchema.from_yaml(yaml_content)
Observe: Pydantic raises ValidationError: Extra inputs are not permitted for the agent_skills field

Severity: High — Any user following the specification to write skill YAML files will have their files rejected. The field name mismatch is a fundamental schema incompatibility.

Subtasks

Rename agent_skill_folders field to agent_skills in SkillConfigSchema in src/cleveragents/skills/schema.py
Update _CAMEL_TO_SNAKE mapping dict: replace agentSkillFolders → agent_skill_folders with agentSkills → agent_skills
Search for all usages of agent_skill_folders across the codebase and update them to agent_skills
Update any existing Behave BDD scenarios in features/ that reference agent_skill_folders
Add a new Behave BDD scenario that validates a spec-compliant skill YAML with agent_skills is accepted without error
Add a regression scenario confirming agent_skill_folders is rejected (it is not a spec field)
Run nox -e typecheck and fix any Pyright errors introduced by the rename
Run nox -e unit_tests and confirm all scenarios pass
Run nox -e coverage_report and confirm coverage >= 97%
Run nox (all default sessions) and confirm clean pass

Definition of Done

SkillConfigSchema field is renamed from agent_skill_folders to agent_skills
_CAMEL_TO_SNAKE mapping updated to agentSkills → agent_skills
All usages of the old field name updated throughout the codebase
A spec-compliant skill YAML using agent_skills: is accepted by SkillConfigSchema.from_yaml() without error
A skill YAML using the old agent_skill_folders: field name is correctly rejected
Behave BDD regression test added covering both the fix and the rejection of the old field name
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `fix/skill-config-schema-agent-skills-field-name` - **Commit Message**: `fix(skills): rename SkillConfigSchema field from agent_skill_folders to agent_skills per spec` - **Milestone**: v3.7.0 - **Parent Epic**: #392 ## Background The `SkillConfigSchema` in `src/cleveragents/skills/schema.py` uses the field name `agent_skill_folders` for Agent Skills Standard folder references, but the specification defines this field as `agent_skills`. This means any skill YAML file written according to the specification will fail validation with a Pydantic `extra="forbid"` error. ## Bug Report **What was tested:** Code-level analysis of `src/cleveragents/skills/schema.py` against `docs/specification.md` skill YAML configuration section. **Expected behavior (from spec):** The skill YAML configuration should accept `agent_skills` as the field name for Agent Skills Standard folder references: ```yaml skill: name: local/devops-toolkit agent_skills: - path: ./skills/code-review-checklist sandbox_policy: none ``` **Actual behavior:** The `SkillConfigSchema` defines the field as `agent_skill_folders`: ```python agent_skill_folders: list[SkillAgentFolderSchema] = Field( default_factory=list, description="Agent Skills Standard folder references.", ) ``` The camelCase mapping is `agentSkillFolders` → `agent_skill_folders`. A skill YAML using `agent_skills:` (as the spec requires) will fail with a Pydantic validation error because `extra="forbid"` is set on `SkillConfigSchema`. **Code locations:** - `src/cleveragents/skills/schema.py`, `SkillConfigSchema` class, `agent_skill_folders` field (line ~280) - `src/cleveragents/skills/schema.py`, `_CAMEL_TO_SNAKE` dict — maps `agentSkillFolders` → `agent_skill_folders` but spec uses `agent_skills` **Steps to reproduce:** 1. Create a skill YAML file using the spec-compliant field name: ```yaml name: local/test-skill description: Test skill agent_skills: - path: ./skills/my-skill ``` 2. Call `SkillConfigSchema.from_yaml(yaml_content)` 3. Observe: Pydantic raises `ValidationError: Extra inputs are not permitted` for the `agent_skills` field **Severity:** High — Any user following the specification to write skill YAML files will have their files rejected. The field name mismatch is a fundamental schema incompatibility. ## Subtasks - [ ] Rename `agent_skill_folders` field to `agent_skills` in `SkillConfigSchema` in `src/cleveragents/skills/schema.py` - [ ] Update `_CAMEL_TO_SNAKE` mapping dict: replace `agentSkillFolders` → `agent_skill_folders` with `agentSkills` → `agent_skills` - [ ] Search for all usages of `agent_skill_folders` across the codebase and update them to `agent_skills` - [ ] Update any existing Behave BDD scenarios in `features/` that reference `agent_skill_folders` - [ ] Add a new Behave BDD scenario that validates a spec-compliant skill YAML with `agent_skills` is accepted without error - [ ] Add a regression scenario confirming `agent_skill_folders` is rejected (it is not a spec field) - [ ] Run `nox -e typecheck` and fix any Pyright errors introduced by the rename - [ ] Run `nox -e unit_tests` and confirm all scenarios pass - [ ] Run `nox -e coverage_report` and confirm coverage >= 97% - [ ] Run `nox` (all default sessions) and confirm clean pass ## Definition of Done - [ ] `SkillConfigSchema` field is renamed from `agent_skill_folders` to `agent_skills` - [ ] `_CAMEL_TO_SNAKE` mapping updated to `agentSkills` → `agent_skills` - [ ] All usages of the old field name updated throughout the codebase - [ ] A spec-compliant skill YAML using `agent_skills:` is accepted by `SkillConfigSchema.from_yaml()` without error - [ ] A skill YAML using the old `agent_skill_folders:` field name is correctly rejected - [ ] Behave BDD regression test added covering both the fix and the rejection of the old field name - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added this to the v3.7.0 milestone

2026-04-03 04:07:27 +00:00

freemo added a new dependency

2026-04-03 04:08:13 +00:00

#392 Epic: Actor YAML & Compiler

freemo referenced this issue

2026-04-03 04:22:00 +00:00

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

freemo self-assigned this

2026-04-03 16:58:06 +00:00

freemo commented

2026-04-03 18:28:16 +00:00

Author

Owner

MoSCoW classification: Should Have

Rationale: This issue addresses a spec requirement or important quality improvement. It should be included in the milestone if possible.

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

MoSCoW classification: **Should Have** Rationale: This issue addresses a spec requirement or important quality improvement. It should be included in the milestone if possible. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner