Built-in skills (`local/file-ops`, `local/git-ops`) are not pre-seeded — `agents skill list` returns empty on a fresh install #11227

New issue

Open

opened 2026-05-15 09:22:21 +00:00 by hurui200320 · 1 comment

hurui200320 commented

2026-05-15 09:22:21 +00:00

Member

Metadata

Commit Message: feat(skill-registry): seed virtual built-in skills into SkillService at startup
Branch: feature/m3-builtin-skill-seeding

Background and Context

The spec (agents skill list example output, §"Built-in tools") shows local/file-ops and local/git-ops as always-present skills — they appear in the agents skill list output without any user action:

local/file-ops          9      0         builtin
local/git-ops           4      0         builtin

The spec also states: "Built-in tools: Core file operations… are provided as built-in tools grouped into built-in skills."

Currently, agents skill list returns "No skills found" on a fresh install. There is no mechanism that seeds local/file-ops or local/git-ops into the SkillService at startup. Skills only appear after a user explicitly runs agents skill add --config <file>, which means:

agents actor run --skill local/file-ops ... fails with "Skill not found" on a fresh install.
The spec's promise of always-available built-in tools is broken.
PR #11219 (which wires ToolCallingRuntime into actor run) is effectively unusable without first manually creating YAML files and running agents skill add.

The root cause is a missing virtual built-in skill layer in SkillService. The codebase already has cleveragents.skills.builtins with register_skill_file_tools() and register_skill_search_tools(), and cleveragents.tool.builtins with register_file_tools() / register_git_tools() — but neither is wired into the SkillService as a permanent, always-present skill.

A close analogy already exists: ResourceRegistryService.bootstrap_builtin_types() seeds built-in resource types (e.g. git-checkout, fs-directory) at startup without requiring user YAML files. The same pattern is needed for skills.

Proposed Solution

Rather than inserting YAML records into the database (which is fragile and requires migration management), implement virtual built-in skills that live entirely in code and are injected into SkillService at initialization time:

SkillService.__init__() (or a new _seed_builtin_skills() method called from there) registers a fixed set of Skill objects directly into self._skills — bypassing the database entirely.
These virtual skills are never persisted to the database; they are reconstructed from code on every startup.
agents skill list returns them alongside user-registered skills (they appear first or in a dedicated "built-in" section).
agents skill add --config <file> with a name that conflicts with a built-in raises a clear error ("Cannot overwrite built-in skill local/file-ops").
agents skill remove local/file-ops raises a clear error ("Cannot remove built-in skill").
The SkillResolver resolves their tool entries from the existing cleveragents.skills.builtins implementations.
ToolCallingAgent._build_tool_registry() in the reactive path resolves these skills' tools from _builtin_registry (already populated in ReactiveCleverAgentsApp.__init__()).

This approach mirrors how built-in automation profiles are handled: they are defined in code, always available, and cannot be removed.

Built-in skills to seed:

Skill name	Tools	Source
`local/file-ops`	`builtin/file-read`, `builtin/file-write`, `builtin/file-edit`, `builtin/file-delete`, `builtin/file-list`, `builtin/file-search`	`cleveragents.tool.builtins.file_tools`
`local/git-ops`	`builtin/git-status`, `builtin/git-diff`, `builtin/git-log`, `builtin/git-blame`	`cleveragents.tool.builtins.git_tools`

Current Behavior

$ agents skill list
No skills found.
Register one with 'agents skill add --config <file>'

$ agents actor run --skill local/file-ops anthropic/claude-sonnet-4-20250514 "List files"
Error: Skill 'local/file-ops' not found in registry

Expected Behavior

$ agents skill list

Skills
  Name           Tools  Includes  Sources
  -------------  -----  --------  -------
  local/file-ops     6         0  builtin
  local/git-ops      4         0  builtin

Summary
  Total: 2
  Local: 2 (built-in)
  Total Tools: 10

$ agents actor run --skill local/file-ops anthropic/claude-sonnet-4-20250514 "List files in src/"
... (LLM calls builtin/file-list, returns results) ...
Tool Calls: 1

Acceptance Criteria

agents skill list on a fresh install shows local/file-ops and local/git-ops without any user action.
agents actor run --skill local/file-ops <actor> <prompt> resolves the skill and makes its tools available to the LLM via ToolCallingAgent.
agents skill show local/file-ops displays the skill's tools and marks it as built-in.
agents skill add --config <file> with name: local/file-ops raises a clear error preventing overwrite of a built-in skill.
agents skill remove local/file-ops raises a clear error.
Built-in skills are never written to the database — they are reconstructed from code on every startup.
All existing agents skill BDD scenarios continue to pass.
New BDD scenarios cover: (A) built-in skills appear in skill list on fresh init, (B) built-in skill tools resolve correctly via SkillService.resolve_tools(), (C) overwrite/remove of built-in skill is rejected.
nox passes (lint, typecheck, unit tests, coverage ≥ 97%).

Supporting Information

Key files involved:

src/cleveragents/application/services/skill_service.py — SkillService.__init__(), add_skill(), list_skills() — add _seed_builtin_skills() here
src/cleveragents/tool/builtins/file_tools.py — ToolSpec definitions for builtin/file-*
src/cleveragents/tool/builtins/git_tools.py — ToolSpec definitions for builtin/git-*
src/cleveragents/skills/builtins/file_ops.py — existing register_skill_file_tools() (skill-layer tools)
src/cleveragents/application/services/resource_registry_service.py — bootstrap_builtin_types() — reference pattern for virtual built-in seeding
src/cleveragents/reactive/application.py — _builtin_registry already populated; ToolCallingAgent already looks up tool names here

Spec references:

§agents skill list (example output shows local/file-ops and local/git-ops as always-present)
§"Built-in tools" — "provided as built-in tools grouped into built-in skills"
§"Tool: Four Sources" — builtin source type

Related issues:

#11211 — agents actor run does not execute tool calls when a skill is attached (PR #11219 fixes the wiring but is blocked by this missing seeding)

Subtasks

ST-1 — Add _seed_builtin_skills() to SkillService: construct Skill domain objects for local/file-ops and local/git-ops from ToolSpec definitions in tool/builtins/; insert into self._skills at __init__ time; mark with a is_builtin: bool flag on the Skill model (or a separate _builtin_names: frozenset[str] set on the service).
ST-2 — Guard add_skill() and remove_skill() in SkillService: raise CleverAgentsException("Cannot overwrite/remove built-in skill '{name}'") when the target name is a built-in.
ST-3 — Update agents skill list CLI output: display built-in skills with a (built-in) marker or in a dedicated section; ensure they appear even when the database is empty.
ST-4 — Update agents skill show CLI output: display Source: built-in and Removable: no for built-in skills.
ST-5 — Write BDD scenarios in features/skill_builtin_seeding.feature: (A) skill list on fresh init returns local/file-ops and local/git-ops; (B) resolve_tools("local/file-ops") returns the expected tool entries; (C) add_skill with a built-in name raises an error; (D) remove_skill on a built-in raises an error.

Definition of Done

agents skill list shows local/file-ops and local/git-ops on a fresh install with no user action.
agents actor run --skill local/file-ops <actor> <prompt> successfully resolves the skill and enables LLM tool calling.
Built-in skills are never persisted to the database.
nox passes (lint, typecheck, unit tests, coverage ≥ 97%).
BDD scenarios added and passing.

## Metadata ``` Commit Message: feat(skill-registry): seed virtual built-in skills into SkillService at startup Branch: feature/m3-builtin-skill-seeding ``` ## Background and Context The spec (`agents skill list` example output, §"Built-in tools") shows `local/file-ops` and `local/git-ops` as always-present skills — they appear in the `agents skill list` output without any user action: ``` local/file-ops 9 0 builtin local/git-ops 4 0 builtin ``` The spec also states: *"Built-in tools: Core file operations… are provided as built-in tools **grouped into built-in skills**."* Currently, `agents skill list` returns **"No skills found"** on a fresh install. There is no mechanism that seeds `local/file-ops` or `local/git-ops` into the `SkillService` at startup. Skills only appear after a user explicitly runs `agents skill add --config <file>`, which means: 1. `agents actor run --skill local/file-ops ...` fails with "Skill not found" on a fresh install. 2. The spec's promise of always-available built-in tools is broken. 3. PR #11219 (which wires `ToolCallingRuntime` into `actor run`) is effectively unusable without first manually creating YAML files and running `agents skill add`. The root cause is a missing **virtual built-in skill layer** in `SkillService`. The codebase already has `cleveragents.skills.builtins` with `register_skill_file_tools()` and `register_skill_search_tools()`, and `cleveragents.tool.builtins` with `register_file_tools()` / `register_git_tools()` — but neither is wired into the `SkillService` as a permanent, always-present skill. A close analogy already exists: `ResourceRegistryService.bootstrap_builtin_types()` seeds built-in resource types (e.g. `git-checkout`, `fs-directory`) at startup without requiring user YAML files. The same pattern is needed for skills. ## Proposed Solution Rather than inserting YAML records into the database (which is fragile and requires migration management), implement **virtual built-in skills** that live entirely in code and are injected into `SkillService` at initialization time: - `SkillService.__init__()` (or a new `_seed_builtin_skills()` method called from there) registers a fixed set of `Skill` objects directly into `self._skills` — bypassing the database entirely. - These virtual skills are **never persisted** to the database; they are reconstructed from code on every startup. - `agents skill list` returns them alongside user-registered skills (they appear first or in a dedicated "built-in" section). - `agents skill add --config <file>` with a name that conflicts with a built-in raises a clear error ("Cannot overwrite built-in skill `local/file-ops`"). - `agents skill remove local/file-ops` raises a clear error ("Cannot remove built-in skill"). - The `SkillResolver` resolves their tool entries from the existing `cleveragents.skills.builtins` implementations. - `ToolCallingAgent._build_tool_registry()` in the reactive path resolves these skills' tools from `_builtin_registry` (already populated in `ReactiveCleverAgentsApp.__init__()`). This approach mirrors how built-in automation profiles are handled: they are defined in code, always available, and cannot be removed. **Built-in skills to seed:** | Skill name | Tools | Source | |---|---|---| | `local/file-ops` | `builtin/file-read`, `builtin/file-write`, `builtin/file-edit`, `builtin/file-delete`, `builtin/file-list`, `builtin/file-search` | `cleveragents.tool.builtins.file_tools` | | `local/git-ops` | `builtin/git-status`, `builtin/git-diff`, `builtin/git-log`, `builtin/git-blame` | `cleveragents.tool.builtins.git_tools` | ## Current Behavior ``` $ agents skill list No skills found. Register one with 'agents skill add --config <file>' $ agents actor run --skill local/file-ops anthropic/claude-sonnet-4-20250514 "List files" Error: Skill 'local/file-ops' not found in registry ``` ## Expected Behavior ``` $ agents skill list Skills Name Tools Includes Sources ------------- ----- -------- ------- local/file-ops 6 0 builtin local/git-ops 4 0 builtin Summary Total: 2 Local: 2 (built-in) Total Tools: 10 $ agents actor run --skill local/file-ops anthropic/claude-sonnet-4-20250514 "List files in src/" ... (LLM calls builtin/file-list, returns results) ... Tool Calls: 1 ``` ## Acceptance Criteria - [ ] `agents skill list` on a fresh install shows `local/file-ops` and `local/git-ops` without any user action. - [ ] `agents actor run --skill local/file-ops <actor> <prompt>` resolves the skill and makes its tools available to the LLM via `ToolCallingAgent`. - [ ] `agents skill show local/file-ops` displays the skill's tools and marks it as built-in. - [ ] `agents skill add --config <file>` with `name: local/file-ops` raises a clear error preventing overwrite of a built-in skill. - [ ] `agents skill remove local/file-ops` raises a clear error. - [ ] Built-in skills are never written to the database — they are reconstructed from code on every startup. - [ ] All existing `agents skill` BDD scenarios continue to pass. - [ ] New BDD scenarios cover: (A) built-in skills appear in `skill list` on fresh init, (B) built-in skill tools resolve correctly via `SkillService.resolve_tools()`, (C) overwrite/remove of built-in skill is rejected. - [ ] `nox` passes (lint, typecheck, unit tests, coverage ≥ 97%). ## Supporting Information Key files involved: - `src/cleveragents/application/services/skill_service.py` — `SkillService.__init__()`, `add_skill()`, `list_skills()` — add `_seed_builtin_skills()` here - `src/cleveragents/tool/builtins/file_tools.py` — `ToolSpec` definitions for `builtin/file-*` - `src/cleveragents/tool/builtins/git_tools.py` — `ToolSpec` definitions for `builtin/git-*` - `src/cleveragents/skills/builtins/file_ops.py` — existing `register_skill_file_tools()` (skill-layer tools) - `src/cleveragents/application/services/resource_registry_service.py` — `bootstrap_builtin_types()` — reference pattern for virtual built-in seeding - `src/cleveragents/reactive/application.py` — `_builtin_registry` already populated; `ToolCallingAgent` already looks up tool names here Spec references: - §`agents skill list` (example output shows `local/file-ops` and `local/git-ops` as always-present) - §"Built-in tools" — *"provided as built-in tools grouped into built-in skills"* - §"Tool: Four Sources" — `builtin` source type Related issues: - #11211 — `agents actor run` does not execute tool calls when a skill is attached (PR #11219 fixes the wiring but is blocked by this missing seeding) ## Subtasks - [ ] **ST-1** — Add `_seed_builtin_skills()` to `SkillService`: construct `Skill` domain objects for `local/file-ops` and `local/git-ops` from `ToolSpec` definitions in `tool/builtins/`; insert into `self._skills` at `__init__` time; mark with a `is_builtin: bool` flag on the `Skill` model (or a separate `_builtin_names: frozenset[str]` set on the service). - [ ] **ST-2** — Guard `add_skill()` and `remove_skill()` in `SkillService`: raise `CleverAgentsException("Cannot overwrite/remove built-in skill '{name}'")` when the target name is a built-in. - [ ] **ST-3** — Update `agents skill list` CLI output: display built-in skills with a `(built-in)` marker or in a dedicated section; ensure they appear even when the database is empty. - [ ] **ST-4** — Update `agents skill show` CLI output: display `Source: built-in` and `Removable: no` for built-in skills. - [ ] **ST-5** — Write BDD scenarios in `features/skill_builtin_seeding.feature`: (A) `skill list` on fresh init returns `local/file-ops` and `local/git-ops`; (B) `resolve_tools("local/file-ops")` returns the expected tool entries; (C) `add_skill` with a built-in name raises an error; (D) `remove_skill` on a built-in raises an error. ## Definition of Done - `agents skill list` shows `local/file-ops` and `local/git-ops` on a fresh install with no user action. - `agents actor run --skill local/file-ops <actor> <prompt>` successfully resolves the skill and enables LLM tool calling. - Built-in skills are never persisted to the database. - `nox` passes (lint, typecheck, unit tests, coverage ≥ 97%). - BDD scenarios added and passing.

hurui200320 added the

labels

2026-05-15 09:22:37 +00:00

hurui200320 added this to the v3.2.0 milestone

2026-05-15 09:22:53 +00:00

hurui200320 commented