cleveragents/cleveragents-core

Fork 3

UAT: `agents skill tools` has undocumented `--refresh` flag not in spec #5033

New issue

Open

opened 2026-04-09 00:49:46 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 00:49:46 +00:00

Owner

Bug Report

Feature Area: Tools & Skills — agents skill tools

Severity: Low (undocumented flag — spec deviation)

What Was Tested

agents skill tools <NAME> command signature vs. spec definition.

Expected Behavior (from spec)

The spec (§ agents skill tools, line ~7220) defines the command as:

agents skill tools <NAME>

With only one argument: <NAME> (the skill name). No flags are defined.

Actual Behavior (from code)

The implementation in src/cleveragents/cli/commands/skill.py (lines 801–913) adds an undocumented --refresh flag:

agents skill tools <NAME> [--refresh] [--format <FMT>]

The --refresh flag re-scans Agent Skills discovery paths before resolving tools.

Analysis

The --refresh flag is not documented in the spec. This creates a discrepancy between the documented interface and the actual implementation. Users reading the spec would not know this flag exists.

This may be intentional functionality that was implemented but not yet spec-documented, or it may overlap with the agents skill refresh command (see related issue #5030).

Code Location

src/cleveragents/cli/commands/skill.py — tools() function, lines 801–913 (specifically the refresh parameter at lines 807–813)

Fix Required

Either:

Update the spec to document the --refresh flag for agents skill tools, OR
Remove the flag from the implementation and rely on agents skill refresh for refresh functionality

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

## Bug Report **Feature Area:** Tools & Skills — `agents skill tools` **Severity:** Low (undocumented flag — spec deviation) --- ## What Was Tested `agents skill tools <NAME>` command signature vs. spec definition. --- ## Expected Behavior (from spec) The spec (§ `agents skill tools`, line ~7220) defines the command as: ``` agents skill tools <NAME> ``` With only one argument: `<NAME>` (the skill name). No flags are defined. --- ## Actual Behavior (from code) The implementation in `src/cleveragents/cli/commands/skill.py` (lines 801–913) adds an undocumented `--refresh` flag: ``` agents skill tools <NAME> [--refresh] [--format <FMT>] ``` The `--refresh` flag re-scans Agent Skills discovery paths before resolving tools. --- ## Analysis The `--refresh` flag is not documented in the spec. This creates a discrepancy between the documented interface and the actual implementation. Users reading the spec would not know this flag exists. This may be intentional functionality that was implemented but not yet spec-documented, or it may overlap with the `agents skill refresh` command (see related issue #5030). --- ## Code Location `src/cleveragents/cli/commands/skill.py` — `tools()` function, lines 801–913 (specifically the `refresh` parameter at lines 807–813) --- ## Fix Required Either: 1. **Update the spec** to document the `--refresh` flag for `agents skill tools`, OR 2. **Remove the flag** from the implementation and rely on `agents skill refresh` for refresh functionality --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 00:51:19 +00:00

HAL9000 commented

2026-04-09 01:02:09 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Low — Minor spec deviation; undocumented option or cosmetic inconsistency
Milestone: Not assigned (backlog)
Story Points: 2 — S
MoSCoW: Could Have — Minor polish item; does not block core functionality

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Low — Minor spec deviation; undocumented option or cosmetic inconsistency - **Milestone**: Not assigned (backlog) - **Story Points**: 2 — S - **MoSCoW**: Could Have — Minor polish item; does not block core functionality --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 referenced this issue

2026-04-09 02:56:12 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 4) #5160

HAL9000 referenced this issue

2026-04-09 03:09:06 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 5) #5200

HAL9000 added a new dependency

2026-04-09 04:56:13 +00:00

#5203 EPIC: CLI Output Format Compliance — Global Flags, JSON Envelope & Error Responses

HAL9000 added this to the v3.2.0 milestone

2026-04-09 04:56:24 +00:00