cleveragents/cleveragents-core

Fork 3

feat(skill): integrate agent skills discovery #161

New issue

Closed

opened 2026-02-22 23:39:43 +00:00 by freemo · 2 comments

freemo commented

2026-02-22 23:39:43 +00:00

Owner

Metadata

Commit Message: feat(skill): integrate agent skills discovery
Branch: feature/m3-agent-skills-registry

Background

Agent Skills are discovered from configurable paths (skills.agent_skills_paths) and registered in ToolRegistry with source=agent_skills and source metadata. The agents skill tools CLI command shows discovered tools. A refresh hook in SkillRegistryService re-scans paths on demand.

Acceptance Criteria

Add config key skills.agent_skills_paths with default discovery path and allow multiple folders.
Register Agent Skills tools in ToolRegistry with source=agent_skills and include source metadata in agents skill tools output.
Add discovery refresh hook in SkillRegistryService and CLI agents skill tools to optionally re-scan Agent Skills paths.
Add explicit conflict handling when Agent Skills names collide with existing ToolRegistry entries.
Update docs/reference/skill_registry.md and CLI reference with Agent Skills discovery behavior and output fields.

Definition of Done

This issue is complete when:

All subtasks below are completed and checked off.
A Git commit is created where the first line of the commit message matches
the Commit Message in Metadata exactly, followed by a blank line, then
additional lines providing relevant details about the implementation. The
commit body should be appropriate in size for a commit message and relatively
complete in describing what was done.
The commit is pushed to the remote on the branch matching the Branch in
Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and
merged before this issue is marked done.

Subtasks

Add config key skills.agent_skills_paths with default discovery path and allow multiple folders.
Register Agent Skills tools in ToolRegistry with source=agent_skills and include source metadata in agents skill tools output.
Add discovery refresh hook in SkillRegistryService and CLI agents skill tools to optionally re-scan Agent Skills paths.
Add explicit conflict handling when Agent Skills names collide with existing ToolRegistry entries.
Update docs/reference/skill_registry.md and CLI reference with Agent Skills discovery behavior and output fields.
Tests (Behave): Add scenarios for discovery, refresh, and source metadata rendering.
Tests (Robot): Add Robot test covering Agent Skills discovery, refresh, and registration.
Tests (ASV): Add benchmarks/agent_skills_registry_bench.py for discovery scan overhead.
Verify coverage >=97% via nox -s coverage_report. If coverage is <97% then review the current unit test coverage report at build/coverage.xml and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun nox -s coverage_report to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
Run nox (all default sessions, including benchmark), fix any errors if needed ensuring nox passes across entire code base, do not ignore any failure even if it seems unrelated to this commit, fix it.

Section: #### M2: Actor Graphs + Tool Sources (Day 14)
Status: In Review

## Metadata - **Commit Message**: `feat(skill): integrate agent skills discovery` - **Branch**: `feature/m3-agent-skills-registry` ## Background Agent Skills are discovered from configurable paths (`skills.agent_skills_paths`) and registered in ToolRegistry with `source=agent_skills` and source metadata. The `agents skill tools` CLI command shows discovered tools. A refresh hook in SkillRegistryService re-scans paths on demand. ## Acceptance Criteria - [x] Add config key `skills.agent_skills_paths` with default discovery path and allow multiple folders. - [x] Register Agent Skills tools in ToolRegistry with `source=agent_skills` and include source metadata in `agents skill tools` output. - [x] Add discovery refresh hook in SkillRegistryService and CLI `agents skill tools` to optionally re-scan Agent Skills paths. - [x] Add explicit conflict handling when Agent Skills names collide with existing ToolRegistry entries. - [x] Update `docs/reference/skill_registry.md` and CLI reference with Agent Skills discovery behavior and output fields. ## Definition of Done This issue is complete when: - All subtasks below are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. The commit body should be appropriate in size for a commit message and relatively complete in describing what was done. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. ## Subtasks - [x] Add config key `skills.agent_skills_paths` with default discovery path and allow multiple folders. - [x] Register Agent Skills tools in ToolRegistry with `source=agent_skills` and include source metadata in `agents skill tools` output. - [x] Add discovery refresh hook in SkillRegistryService and CLI `agents skill tools` to optionally re-scan Agent Skills paths. - [x] Add explicit conflict handling when Agent Skills names collide with existing ToolRegistry entries. - [x] Update `docs/reference/skill_registry.md` and CLI reference with Agent Skills discovery behavior and output fields. - [x] Tests (Behave): Add scenarios for discovery, refresh, and source metadata rendering. - [x] Tests (Robot): Add Robot test covering Agent Skills discovery, refresh, and registration. - [x] Tests (ASV): Add `benchmarks/agent_skills_registry_bench.py` for discovery scan overhead. - [x] Verify coverage >=97% via `nox -s coverage_report`. If coverage is <97% then review the current unit test coverage report at `build/coverage.xml` and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `nox -s coverage_report` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. - [x] Run `nox` (all default sessions, including benchmark), fix any errors if needed ensuring nox passes across **entire** code base, do not ignore any failure even if it seems unrelated to this commit, fix it. **Section**: #### M2: Actor Graphs + Tool Sources (Day 14) **Status**: In Review

freemo added this to the v3.1.0 milestone

2026-02-22 23:39:43 +00:00

freemo added the

labels

2026-02-22 23:39:43 +00:00

freemo self-assigned this

2026-02-22 23:39:43 +00:00

freemo added a new dependency

2026-02-22 23:54:03 +00:00

#356 Epic: Actor Graphs + Tool Sources (M2)

freemo commented

2026-02-23 18:30:49 +00:00

Author

Owner

Expected completion updated (Day 15 rebaseline): Day 21 / 2026-03-01 (previously Day 18 / 2026-02-26)

**Expected completion updated (Day 15 rebaseline):** Day 21 / 2026-03-01 (previously Day 18 / 2026-02-26)

freemo added the due date 2026-02-25

2026-02-23 18:41:25 +00:00

freemo removed a dependency

2026-02-23 20:33:16 +00:00

#356 Epic: Actor Graphs + Tool Sources (M2)

freemo added a new dependency

2026-02-23 20:35:22 +00:00

#393 Epic: Skill & Tool Lifecycle

freemo referenced this issue

2026-02-24 03:27:10 +00:00

Build an automated multi-agent system that generates domain-specific RDF #29

freemo referenced this issue

2026-02-24 03:42:29 +00:00

Epic: Skill & Tool Lifecycle #393

freemo referenced this issue from a commit

2026-02-24 12:38:37 +00:00

feat(skill): integrate agent skills discovery

~~freemo referenced this issue 2026-02-24 12:38:51 +00:00~~

feat(skill): integrate agent skills discovery #414

freemo added

and removed

labels

2026-02-24 12:39:02 +00:00

freemo commented

2026-02-24 12:39:33 +00:00

Author

Owner

Implementation Complete — PR #414

Summary

Full agent skills discovery system implemented in skills/discovery.py (~290 lines) with the following components:

Files Changed (13 files, +1738 lines)

New source files:

src/cleveragents/skills/discovery.py — Core discovery module with DiscoveredAgentSkill, DiscoveryConflict, DiscoveryResult dataclasses; parse_agent_skills_paths(), scan_directory(), discover_agent_skills(), build_tool_spec(), register_discovered_skills() functions; SKILL.md YAML front-matter parsing; conflict strategies (skip/error/replace)

Modified source files:

src/cleveragents/application/services/config_service.py — Added skills.agent_skills_paths config key in _build_catalog()
src/cleveragents/tool/runtime.py — Added source (str, default "builtin") and source_metadata (dict) fields to ToolSpec
src/cleveragents/tool/registry.py — Added source: str | None = None parameter to list_tools() with filtering
src/cleveragents/application/services/skill_registry_service.py — Rewritten with discover_and_register() and refresh_agent_skills() hooks
src/cleveragents/cli/commands/skill.py — Added --refresh flag to tools command, source metadata in JSON output
src/cleveragents/skills/__init__.py — Added discovery module exports

New test files:

features/skill_discovery.feature — 27 Behave scenarios (config key, path parsing, discovery, ToolSpec building, registration, conflict handling, refresh, edge cases, source metadata)
features/steps/skill_discovery_steps.py — Step definitions (~530 lines)
robot/skill_discovery.robot — 10 Robot Framework integration tests
robot/helper_skill_discovery.py — Robot helper keywords
benchmarks/agent_skills_registry_bench.py — ASV benchmarks (ParsePaths, ScanDirectory, BuildToolSpec, Register suites)

Documentation:

docs/reference/skill_registry.md — Agent Skills Discovery section added

Quality Gates

Gate	Status
Lint (ruff)	PASS
Typecheck (pyright strict)	PASS — 0 errors, 0 warnings
Unit tests (Behave)	PASS — 27 new + 95 related scenarios
Integration tests (Robot)	PASS — 662/662
Coverage (discovery.py)	97%
Security scan (bandit+vulture)	PASS
Dead code (vulture)	PASS
Docs (mkdocs)	PASS
Build (wheel)	PASS
Benchmark (ASV)	PASS

Branch & Commit

Branch: feature/m3-agent-skills-registry
Commit: 3a18251 — feat(skill): integrate agent skills discovery
PR: #414

## Implementation Complete — PR #414 ### Summary Full agent skills discovery system implemented in `skills/discovery.py` (~290 lines) with the following components: ### Files Changed (13 files, +1738 lines) **New source files:** - `src/cleveragents/skills/discovery.py` — Core discovery module with `DiscoveredAgentSkill`, `DiscoveryConflict`, `DiscoveryResult` dataclasses; `parse_agent_skills_paths()`, `scan_directory()`, `discover_agent_skills()`, `build_tool_spec()`, `register_discovered_skills()` functions; SKILL.md YAML front-matter parsing; conflict strategies (skip/error/replace) **Modified source files:** - `src/cleveragents/application/services/config_service.py` — Added `skills.agent_skills_paths` config key in `_build_catalog()` - `src/cleveragents/tool/runtime.py` — Added `source` (str, default "builtin") and `source_metadata` (dict) fields to `ToolSpec` - `src/cleveragents/tool/registry.py` — Added `source: str | None = None` parameter to `list_tools()` with filtering - `src/cleveragents/application/services/skill_registry_service.py` — Rewritten with `discover_and_register()` and `refresh_agent_skills()` hooks - `src/cleveragents/cli/commands/skill.py` — Added `--refresh` flag to `tools` command, source metadata in JSON output - `src/cleveragents/skills/__init__.py` — Added discovery module exports **New test files:** - `features/skill_discovery.feature` — 27 Behave scenarios (config key, path parsing, discovery, ToolSpec building, registration, conflict handling, refresh, edge cases, source metadata) - `features/steps/skill_discovery_steps.py` — Step definitions (~530 lines) - `robot/skill_discovery.robot` — 10 Robot Framework integration tests - `robot/helper_skill_discovery.py` — Robot helper keywords - `benchmarks/agent_skills_registry_bench.py` — ASV benchmarks (ParsePaths, ScanDirectory, BuildToolSpec, Register suites) **Documentation:** - `docs/reference/skill_registry.md` — Agent Skills Discovery section added ### Quality Gates | Gate | Status | |------|--------| | Lint (ruff) | PASS | | Typecheck (pyright strict) | PASS — 0 errors, 0 warnings | | Unit tests (Behave) | PASS — 27 new + 95 related scenarios | | Integration tests (Robot) | PASS — 662/662 | | Coverage (discovery.py) | 97% | | Security scan (bandit+vulture) | PASS | | Dead code (vulture) | PASS | | Docs (mkdocs) | PASS | | Build (wheel) | PASS | | Benchmark (ASV) | PASS | ### Branch & Commit - Branch: `feature/m3-agent-skills-registry` - Commit: `3a18251` — `feat(skill): integrate agent skills discovery` - PR: #414

freemo referenced this issue from a pull request that will close it,

2026-02-24 14:27:07 +00:00

feat(skill): integrate agent skills discovery #414

freemo added a new dependency

2026-02-24 14:27:10 +00:00

#414 feat(skill): integrate agent skills discovery

freemo referenced this issue from a commit

2026-02-24 14:33:57 +00:00

feat(skill): integrate agent skills discovery

freemo referenced this issue from a commit

2026-02-24 15:02:17 +00:00

feat(skill): integrate agent skills discovery