UAT: Skill YAML `builtins:` section not implemented — `SkillConfigSchema` and `Skill` domain model have no `builtins` field #2490

New issue

Open

opened 2026-04-03 18:38:38 +00:00 by freemo · 2 comments

freemo commented

2026-04-03 18:38:38 +00:00

Owner

Metadata

Branch: feat/skill-builtins-section
Commit Message: feat(skills): add builtins: section support to SkillConfigSchema and Skill domain model
Milestone: v3.6.0
Parent Epic: #392

Summary

The specification defines a builtins: section in skill YAML configuration that allows skills to opt-in to built-in tool groups provided by CleverAgents (e.g., shell_operations, file_operations, git_operations). Neither SkillConfigSchema nor the Skill domain model implement this field. Skill YAML files using builtins: will fail with a validation error due to extra="forbid" on SkillConfigSchema.

Expected Behavior (from spec)

The specification (docs/specification.md, Skill Configuration section) shows:

skill:
  name: local/devops-toolkit
  
  # ── Built-in Tool Groups ─────────────────────────────────────────────────
  # Opt-in to built-in tool groups provided by CleverAgents.
  builtins:
    - group: shell_operations

The spec also shows the skill hierarchy example:

local/full-stack-dev
  ├── includes: local/file-ops
  │     └── builtins: file_operations, directory_operations
  ├── includes: local/git-ops
  │     └── builtins: git_operations

This indicates that builtins: is a first-class source of tools in a skill, alongside tools:, includes:, mcp_servers:, and agent_skills:.

Actual Behavior

SkillConfigSchema has no builtins field:

class SkillConfigSchema(BaseModel):
    name: str
    description: str | None
    tools: list[SkillToolRefSchema]
    inline_tools: list[SkillInlineToolSchema]
    includes: list[SkillIncludeSchema]
    mcp_servers: list[SkillMcpServerSchema]
    agent_skill_folders: list[SkillAgentFolderSchema]
    # ← No builtins field!

A skill YAML with builtins: fails:

pydantic.ValidationError: 1 validation error for SkillConfigSchema
builtins
  Extra inputs are not permitted [type=extra_forbidden]

The Skill domain model (src/cleveragents/domain/models/core/skill.py) also has no builtins field.

Code Locations

src/cleveragents/skills/schema.py — SkillConfigSchema missing builtins field
src/cleveragents/domain/models/core/skill.py — Skill domain model missing builtins field
src/cleveragents/skills/registry.py — SkillResolver.resolve_tools() does not handle builtin tool groups

Impact

Skills cannot reference built-in tool groups (file operations, git operations, shell operations, etc.) via the builtins: YAML key. This is a core capability of the skill system — built-in tools are how actors get access to standard file/git/shell operations without requiring external MCP servers.

Subtasks

Add SkillBuiltinGroupSchema model with group: str field
Add builtins: list[SkillBuiltinGroupSchema] field to SkillConfigSchema
Add builtins: list[SkillBuiltinSource] field to Skill domain model
Update SkillResolver.resolve_tools() to include builtin group tools in the flattened set (keyed as builtin:{group})
Update SkillCapabilitySummary to track builtin group count
Add Behave unit tests for skill YAML with builtins: section
Document available builtin group names (file_operations, directory_operations, git_operations, shell_operations, etc.)

Definition of Done

Skill YAML with builtins: - group: shell_operations parses correctly
SkillResolver includes builtin group tools in the flattened tool set
agents skill tools local/my-skill shows builtin tools
nox -e unit_tests passes

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

## Metadata - **Branch**: `feat/skill-builtins-section` - **Commit Message**: `feat(skills): add builtins: section support to SkillConfigSchema and Skill domain model` - **Milestone**: v3.6.0 - **Parent Epic**: #392 ## Summary The specification defines a `builtins:` section in skill YAML configuration that allows skills to opt-in to built-in tool groups provided by CleverAgents (e.g., `shell_operations`, `file_operations`, `git_operations`). Neither `SkillConfigSchema` nor the `Skill` domain model implement this field. Skill YAML files using `builtins:` will fail with a validation error due to `extra="forbid"` on `SkillConfigSchema`. ## Expected Behavior (from spec) The specification (`docs/specification.md`, Skill Configuration section) shows: ```yaml skill: name: local/devops-toolkit # ── Built-in Tool Groups ───────────────────────────────────────────────── # Opt-in to built-in tool groups provided by CleverAgents. builtins: - group: shell_operations ``` The spec also shows the skill hierarchy example: ``` local/full-stack-dev ├── includes: local/file-ops │ └── builtins: file_operations, directory_operations ├── includes: local/git-ops │ └── builtins: git_operations ``` This indicates that `builtins:` is a first-class source of tools in a skill, alongside `tools:`, `includes:`, `mcp_servers:`, and `agent_skills:`. ## Actual Behavior `SkillConfigSchema` has no `builtins` field: ```python class SkillConfigSchema(BaseModel): name: str description: str | None tools: list[SkillToolRefSchema] inline_tools: list[SkillInlineToolSchema] includes: list[SkillIncludeSchema] mcp_servers: list[SkillMcpServerSchema] agent_skill_folders: list[SkillAgentFolderSchema] # ← No builtins field! ``` A skill YAML with `builtins:` fails: ``` pydantic.ValidationError: 1 validation error for SkillConfigSchema builtins Extra inputs are not permitted [type=extra_forbidden] ``` The `Skill` domain model (`src/cleveragents/domain/models/core/skill.py`) also has no `builtins` field. ## Code Locations - `src/cleveragents/skills/schema.py` — `SkillConfigSchema` missing `builtins` field - `src/cleveragents/domain/models/core/skill.py` — `Skill` domain model missing `builtins` field - `src/cleveragents/skills/registry.py` — `SkillResolver.resolve_tools()` does not handle builtin tool groups ## Impact Skills cannot reference built-in tool groups (file operations, git operations, shell operations, etc.) via the `builtins:` YAML key. This is a core capability of the skill system — built-in tools are how actors get access to standard file/git/shell operations without requiring external MCP servers. ## Subtasks - [ ] Add `SkillBuiltinGroupSchema` model with `group: str` field - [ ] Add `builtins: list[SkillBuiltinGroupSchema]` field to `SkillConfigSchema` - [ ] Add `builtins: list[SkillBuiltinSource]` field to `Skill` domain model - [ ] Update `SkillResolver.resolve_tools()` to include builtin group tools in the flattened set (keyed as `builtin:{group}`) - [ ] Update `SkillCapabilitySummary` to track builtin group count - [ ] Add Behave unit tests for skill YAML with `builtins:` section - [ ] Document available builtin group names (file_operations, directory_operations, git_operations, shell_operations, etc.) ## Definition of Done - Skill YAML with `builtins: - group: shell_operations` parses correctly - `SkillResolver` includes builtin group tools in the flattened tool set - `agents skill tools local/my-skill` shows builtin tools - `nox -e unit_tests` passes --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo commented

2026-04-03 18:40:57 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: Should Have — Spec compliance or quality improvement that should be included in the milestone.

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: Should Have — Spec compliance or quality improvement that should be included in the milestone. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo commented

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

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Confirmed
MoSCoW: Should Have (already set)

Valid finding verified during batch triage.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Confirmed - **MoSCoW**: Should Have (already set) Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added this to the v3.7.0 milestone

2026-04-05 05:07:08 +00:00

freemo removed this from the v3.7.0 milestone

2026-04-07 00:49:35 +00:00