AgentSkillLoader missing multi-scope discovery: global/project/local three-tier loading model not implemented #9369

Open
opened 2026-04-14 16:04:32 +00:00 by HAL9000 · 2 comments
Owner

Metadata

  • Commit Message: fix(skills): implement multi-scope agent skill discovery for global, project, and local tiers
  • Branch: fix/agent-skill-multi-scope-discovery

Background and Context

ADR-028 (Agent Skills Standard) specifies that "Skill folders are discovered via paths configured in skill YAML (agent_skills section)". The specification at docs/specification.md (line 46440) references agent_skills_dirs as a configuration key for multi-scope discovery. The test prompt for UAT testing explicitly requires verifying that "three-tier loading model works (global, project, local)".

The current AgentSkillLoader implementation (src/cleveragents/skills/agent_skills_loader.py) only supports loading a single folder via AgentSkillLoader.from_folder(path). There is no mechanism to discover and load Agent Skills from multiple scopes (global data directory, project-level directory, local working directory).

Current Behavior

AgentSkillLoader.from_folder(path) loads exactly one skill folder. There is no AgentSkillLoader.from_dirs(global_dirs, project_dirs, local_dirs) or equivalent multi-scope discovery API. The agent_skills_loader.feature BDD test file contains no scenarios testing multi-scope (global/project/local) loading. The agent_skills_dirs configuration key referenced in the specification has no corresponding implementation.

Expected Behavior

Per ADR-028 and docs/specification.md:

  • Agent Skills should be discoverable from multiple configured paths (global, project-scoped, local)
  • The agent_skills section in skill YAML should support listing multiple directories
  • A multi-scope loader or discovery service should iterate all configured agent_skills_dirs paths, load each valid skill folder, and register them in the Tool Registry
  • BDD scenarios should cover: loading from global scope only, project scope only, local scope only, and all three scopes combined with correct precedence

Acceptance Criteria

  • AgentSkillLoader or a new AgentSkillDiscovery service supports loading from multiple configured directories
  • Global, project, and local scope directories are each independently configurable
  • Skills from all configured scopes are discovered and registered in the Tool Registry
  • Name collision handling is defined when the same skill name appears in multiple scopes
  • BDD scenarios in agent_skills_loader.feature cover multi-scope discovery
  • nox -s unit_tests -- features/agent_skills_loader.feature passes with multi-scope scenarios

Supporting Information

  • ADR-028: docs/adr/ADR-028-agent-skills-standard.md — "Skill folders are discovered via paths configured in skill YAML (agent_skills section)"
  • Specification: docs/specification.md line 46440 — agent_skills_dirs configuration key
  • Implementation: src/cleveragents/skills/agent_skills_loader.py — only from_folder() exists, no multi-scope discovery
  • Feature file: features/agent_skills_loader.feature — no multi-scope scenarios present
  • UAT test requirement: "Verify three-tier loading model works (global, project, local)"

Subtasks

  • Design multi-scope discovery API (e.g., AgentSkillDiscovery.from_config(config))
  • Implement global scope discovery from configured agent_skills_dirs global paths
  • Implement project scope discovery from project-level agent_skills_dirs paths
  • Implement local scope discovery from local working directory agent_skills_dirs paths
  • Define and implement name collision resolution across scopes
  • Add BDD scenarios for global-only, project-only, local-only, and combined loading
  • Add BDD scenarios for name collision handling across scopes
  • Tests (Behave): Run nox -s unit_tests -- features/agent_skills_loader.feature and verify all pass
  • Verify coverage >=97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • All subtasks above 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 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.

Automated by CleverAgents Bot
Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor

## Metadata - **Commit Message**: `fix(skills): implement multi-scope agent skill discovery for global, project, and local tiers` - **Branch**: `fix/agent-skill-multi-scope-discovery` ## Background and Context ADR-028 (Agent Skills Standard) specifies that "Skill folders are discovered via paths configured in skill YAML (`agent_skills` section)". The specification at `docs/specification.md` (line 46440) references `agent_skills_dirs` as a configuration key for multi-scope discovery. The test prompt for UAT testing explicitly requires verifying that "three-tier loading model works (global, project, local)". The current `AgentSkillLoader` implementation (`src/cleveragents/skills/agent_skills_loader.py`) only supports loading a **single folder** via `AgentSkillLoader.from_folder(path)`. There is no mechanism to discover and load Agent Skills from multiple scopes (global data directory, project-level directory, local working directory). ## Current Behavior `AgentSkillLoader.from_folder(path)` loads exactly one skill folder. There is no `AgentSkillLoader.from_dirs(global_dirs, project_dirs, local_dirs)` or equivalent multi-scope discovery API. The `agent_skills_loader.feature` BDD test file contains no scenarios testing multi-scope (global/project/local) loading. The `agent_skills_dirs` configuration key referenced in the specification has no corresponding implementation. ## Expected Behavior Per ADR-028 and `docs/specification.md`: - Agent Skills should be discoverable from multiple configured paths (global, project-scoped, local) - The `agent_skills` section in skill YAML should support listing multiple directories - A multi-scope loader or discovery service should iterate all configured `agent_skills_dirs` paths, load each valid skill folder, and register them in the Tool Registry - BDD scenarios should cover: loading from global scope only, project scope only, local scope only, and all three scopes combined with correct precedence ## Acceptance Criteria - [ ] `AgentSkillLoader` or a new `AgentSkillDiscovery` service supports loading from multiple configured directories - [ ] Global, project, and local scope directories are each independently configurable - [ ] Skills from all configured scopes are discovered and registered in the Tool Registry - [ ] Name collision handling is defined when the same skill name appears in multiple scopes - [ ] BDD scenarios in `agent_skills_loader.feature` cover multi-scope discovery - [ ] `nox -s unit_tests -- features/agent_skills_loader.feature` passes with multi-scope scenarios ## Supporting Information - ADR-028: `docs/adr/ADR-028-agent-skills-standard.md` — "Skill folders are discovered via paths configured in skill YAML (`agent_skills` section)" - Specification: `docs/specification.md` line 46440 — `agent_skills_dirs` configuration key - Implementation: `src/cleveragents/skills/agent_skills_loader.py` — only `from_folder()` exists, no multi-scope discovery - Feature file: `features/agent_skills_loader.feature` — no multi-scope scenarios present - UAT test requirement: "Verify three-tier loading model works (global, project, local)" ## Subtasks - [ ] Design multi-scope discovery API (e.g., `AgentSkillDiscovery.from_config(config)`) - [ ] Implement global scope discovery from configured `agent_skills_dirs` global paths - [ ] Implement project scope discovery from project-level `agent_skills_dirs` paths - [ ] Implement local scope discovery from local working directory `agent_skills_dirs` paths - [ ] Define and implement name collision resolution across scopes - [ ] Add BDD scenarios for global-only, project-only, local-only, and combined loading - [ ] Add BDD scenarios for name collision handling across scopes - [ ] Tests (Behave): Run `nox -s unit_tests -- features/agent_skills_loader.feature` and verify all pass - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above 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 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. --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor
HAL9000 added this to the v3.2.0 milestone 2026-04-14 16:10:34 +00:00
Author
Owner

Triage: Verified [AUTO-OWNR-1]

Valid bug: AgentSkillLoader only supports loading a single folder via from_folder(path). The spec (ADR-028, docs/specification.md line 46440) requires multi-scope discovery from global, project, and local directories via agent_skills_dirs. The three-tier loading model is not implemented.

Assigning to v3.2.0 as skill loading is a core M3 feature. Priority Medium — skills can still be loaded from a single directory, but multi-scope discovery is missing.

MoSCoW: Should Have — multi-scope skill discovery is important for the full skill management workflow, but single-directory loading still works.


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

✅ **Triage: Verified** [AUTO-OWNR-1] Valid bug: `AgentSkillLoader` only supports loading a single folder via `from_folder(path)`. The spec (ADR-028, `docs/specification.md` line 46440) requires multi-scope discovery from global, project, and local directories via `agent_skills_dirs`. The three-tier loading model is not implemented. Assigning to **v3.2.0** as skill loading is a core M3 feature. Priority **Medium** — skills can still be loaded from a single directory, but multi-scope discovery is missing. MoSCoW: **Should Have** — multi-scope skill discovery is important for the full skill management workflow, but single-directory loading still works. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Author
Owner

🔍 Triage Decision — Verified

Decision: Verified | MoSCoW: Must Have | Priority: High

This is a confirmed missing feature required by ADR-028 and the product specification. AgentSkillLoader only supports from_folder(path) for a single directory — the three-tier loading model (global/project/local) specified in ADR-028 and docs/specification.md (line 46440, agent_skills_dirs) is not implemented. The UAT test requirement explicitly calls for verifying the three-tier model.

Rationale:

  • The gap is confirmed by code inspection (from_folder() only, no multi-scope API)
  • ADR-028 and the specification explicitly require multi-scope discovery
  • UAT testing cannot pass without this implementation
  • Classified as Must Have: this is a required feature per the architecture decision record
  • Milestone confirmed as v3.2.0

Next steps: Design and implement AgentSkillDiscovery.from_config(config) supporting global, project, and local scope directories. Define name collision resolution across scopes. Add BDD scenarios for all scope combinations and collision handling. Run nox -s unit_tests -- features/agent_skills_loader.feature.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Worker: [AUTO-OWNR-1]

## 🔍 Triage Decision — Verified ✅ **Decision:** Verified | **MoSCoW:** Must Have | **Priority:** High This is a confirmed missing feature required by ADR-028 and the product specification. `AgentSkillLoader` only supports `from_folder(path)` for a single directory — the three-tier loading model (global/project/local) specified in ADR-028 and `docs/specification.md` (line 46440, `agent_skills_dirs`) is not implemented. The UAT test requirement explicitly calls for verifying the three-tier model. **Rationale:** - The gap is confirmed by code inspection (`from_folder()` only, no multi-scope API) - ADR-028 and the specification explicitly require multi-scope discovery - UAT testing cannot pass without this implementation - Classified as **Must Have**: this is a required feature per the architecture decision record - Milestone confirmed as **v3.2.0** **Next steps:** Design and implement `AgentSkillDiscovery.from_config(config)` supporting global, project, and local scope directories. Define name collision resolution across scopes. Add BDD scenarios for all scope combinations and collision handling. Run `nox -s unit_tests -- features/agent_skills_loader.feature`. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor Worker: [AUTO-OWNR-1]
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#9369
No description provided.