cleveragents/cleveragents-core

Fork 3

bug(skills): skills are not loadable from external packages via Python entry points #8727

New issue

Open

opened 2026-04-13 22:33:36 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-13 22:33:36 +00:00

Owner

Metadata

Commit message: bug(skills): skills are not loadable from external packages via Python entry points
Branch name: bug/skills-entry-points-not-loadable

Background and Context

The product specification states: "Skills are loadable from external packages via entry points."

However, inspection of pyproject.toml reveals no [project.entry-points] section for skills. The skills discovery mechanism in src/cleveragents/skills/discovery.py only supports filesystem directory scanning (via skills.agent_skills_paths config), not Python package entry points.

Summary

The product specification states: "Skills are loadable from external packages via entry points."

Gap

The spec requirement: "Skills are loadable from external packages via entry points"

Current implementation:

src/cleveragents/skills/discovery.py — scans configured directories for SKILL.md files
src/cleveragents/skills/registry.py — in-memory registry, no entry point loading
pyproject.toml — no [project.entry-points] section for skills

There is no mechanism for third-party Python packages to register skills via setuptools/hatchling entry points (e.g., [project.entry-points."cleveragents.skills"]).

Impact

Third-party skill packages cannot be installed via pip install and auto-discovered
The plugin architecture for skills is incomplete
External skill package authors have no standard integration path

Steps to Reproduce

Inspect pyproject.toml — no [project.entry-points] section exists
Inspect src/cleveragents/skills/discovery.py — only filesystem scanning, no importlib.metadata.entry_points() call
Attempt to create a third-party package with entry point cleveragents.skills — it will not be discovered

Expected Behavior

External packages should be able to register skills via entry points:

[project.entry-points."cleveragents.skills"]
my-skill = "my_package.skills:MySkillDefinition"

And the skills discovery system should call importlib.metadata.entry_points(group="cleveragents.skills") to load them.

Actual Behavior

No entry point discovery mechanism exists. Skills can only be loaded from filesystem paths.

Acceptance Criteria

importlib.metadata.entry_points(group="cleveragents.skills") is called during skill discovery
A test package with a skill entry point is discovered and registered correctly
BDD scenarios pass for entry point skill loading
Documentation is updated with the entry point API for third-party skill authors

Subtasks

Define the cleveragents.skills entry point group convention
Implement entry point discovery in src/cleveragents/skills/discovery.py using importlib.metadata.entry_points()
Add entry point loading to SkillRegistry or the application container
Add BDD test scenarios for entry point skill loading
Document the entry point API for third-party skill authors
Update CHANGELOG.md

Definition of Done

importlib.metadata.entry_points(group="cleveragents.skills") is called during skill discovery
A test package with a skill entry point is discovered and registered correctly
BDD scenarios pass for entry point skill loading
Documentation updated with entry point API

Automated by CleverAgents Bot
Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor
Worker: [AUTO-UAT-9]

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit message**: `bug(skills): skills are not loadable from external packages via Python entry points` - **Branch name**: `bug/skills-entry-points-not-loadable` ## Background and Context The product specification states: "Skills are loadable from external packages via entry points." However, inspection of `pyproject.toml` reveals **no `[project.entry-points]` section** for skills. The skills discovery mechanism in `src/cleveragents/skills/discovery.py` only supports filesystem directory scanning (via `skills.agent_skills_paths` config), not Python package entry points. ## Summary The product specification states: "Skills are loadable from external packages via entry points." However, inspection of `pyproject.toml` reveals **no `[project.entry-points]` section** for skills. The skills discovery mechanism in `src/cleveragents/skills/discovery.py` only supports filesystem directory scanning (via `skills.agent_skills_paths` config), not Python package entry points. ## Gap The spec requirement: "Skills are loadable from external packages via entry points" Current implementation: - `src/cleveragents/skills/discovery.py` — scans configured directories for `SKILL.md` files - `src/cleveragents/skills/registry.py` — in-memory registry, no entry point loading - `pyproject.toml` — no `[project.entry-points]` section for skills There is no mechanism for third-party Python packages to register skills via `setuptools`/`hatchling` entry points (e.g., `[project.entry-points."cleveragents.skills"]`). ## Impact - Third-party skill packages cannot be installed via `pip install` and auto-discovered - The plugin architecture for skills is incomplete - External skill package authors have no standard integration path ## Steps to Reproduce 1. Inspect `pyproject.toml` — no `[project.entry-points]` section exists 2. Inspect `src/cleveragents/skills/discovery.py` — only filesystem scanning, no `importlib.metadata.entry_points()` call 3. Attempt to create a third-party package with entry point `cleveragents.skills` — it will not be discovered ## Expected Behavior External packages should be able to register skills via entry points: ```toml [project.entry-points."cleveragents.skills"] my-skill = "my_package.skills:MySkillDefinition" ``` And the skills discovery system should call `importlib.metadata.entry_points(group="cleveragents.skills")` to load them. ## Actual Behavior No entry point discovery mechanism exists. Skills can only be loaded from filesystem paths. ## Acceptance Criteria - `importlib.metadata.entry_points(group="cleveragents.skills")` is called during skill discovery - A test package with a skill entry point is discovered and registered correctly - BDD scenarios pass for entry point skill loading - Documentation is updated with the entry point API for third-party skill authors ## Subtasks - [ ] Define the `cleveragents.skills` entry point group convention - [ ] Implement entry point discovery in `src/cleveragents/skills/discovery.py` using `importlib.metadata.entry_points()` - [ ] Add entry point loading to `SkillRegistry` or the application container - [ ] Add BDD test scenarios for entry point skill loading - [ ] Document the entry point API for third-party skill authors - [ ] Update CHANGELOG.md ## Definition of Done - [ ] `importlib.metadata.entry_points(group="cleveragents.skills")` is called during skill discovery - [ ] A test package with a skill entry point is discovered and registered correctly - [ ] BDD scenarios pass for entry point skill loading - [ ] Documentation updated with entry point API --- **Automated by CleverAgents Bot** Supervisor: UAT Test Pool | Agent: uat-test-pool-supervisor Worker: [AUTO-UAT-9] --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 added the

labels

2026-04-13 22:35:13 +00:00

HAL9000 referenced this issue

2026-04-13 22:38:43 +00:00

[AUTO-OWNR] Status: Project Owner Pool Supervisor (Cycle 14) #8732

HAL9000 added

and removed

labels

2026-04-13 22:39:17 +00:00

HAL9000 commented

2026-04-13 22:39:43 +00:00

Author

Owner

[AUTO-OWNR-1] Triage Decision (Cycle 14)

Status: ✅ Verified

MoSCoW: Should Have
Priority: Medium

Rationale: The spec states "Skills are loadable from external packages via entry points," but the current discovery.py only supports filesystem directory scanning — there is no importlib.metadata.entry_points() call and no [project.entry-points] section in pyproject.toml. This is a confirmed spec gap that blocks the plugin/extensibility architecture for third-party skill authors. Classified as Should Have because the core skill system works via filesystem paths, but the entry point mechanism is a key extensibility feature that should be present.

Next Steps: Implement importlib.metadata.entry_points(group="cleveragents.skills") discovery in src/cleveragents/skills/discovery.py, define the entry point group convention, add BDD test scenarios for entry point skill loading, and document the API for third-party skill authors. Branch: bug/skills-entry-points-not-loadable.

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

## [AUTO-OWNR-1] Triage Decision (Cycle 14) **Status**: ✅ Verified **MoSCoW**: Should Have **Priority**: Medium **Rationale**: The spec states "Skills are loadable from external packages via entry points," but the current `discovery.py` only supports filesystem directory scanning — there is no `importlib.metadata.entry_points()` call and no `[project.entry-points]` section in `pyproject.toml`. This is a confirmed spec gap that blocks the plugin/extensibility architecture for third-party skill authors. Classified as Should Have because the core skill system works via filesystem paths, but the entry point mechanism is a key extensibility feature that should be present. **Next Steps**: Implement `importlib.metadata.entry_points(group="cleveragents.skills")` discovery in `src/cleveragents/skills/discovery.py`, define the entry point group convention, add BDD test scenarios for entry point skill loading, and document the API for third-party skill authors. Branch: `bug/skills-entry-points-not-loadable`. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-13 22:46:58 +00:00

[AUTO-UAT-SUP] Status: UAT Test Pool Supervisor (Cycle 1) #8509