cleveragents/cleveragents-core

Fork 3

UAT: `agents skill add/list/show --format json` output missing spec-required nested data structure (`skill`, `includes`, `tool_sources`, `summary`, `direct_tools`, `referenced_by` keys) #6857

New issue

Open

opened 2026-04-10 03:40:02 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-10 03:40:02 +00:00

Owner

Background and Context

The spec (§ "agents skill add", "agents skill list", "agents skill show") defines specific JSON schemas for these commands under --format json. Code analysis of src/cleveragents/cli/commands/skill.py shows all three commands produce incorrect/flat output schemas that do not match the spec.

Current Behavior

agents skill add --format json (line 508–511 of skill.py):

data = _skill_spec_dict(skill, service)
data["is_new"] = is_new
typer.echo(format_output(data, fmt))

_skill_spec_dict() returns a flat dict with name, namespace, short_name, description, config_path, tool_refs, includes (list of name strings), mcp_servers, agent_skills, sources. This does NOT match the spec schema.

agents skill list --format json (line 676–695 of skill.py):
Outputs a flat array where each element is the same flat _skill_spec_dict() result with added tool_count and capability_summary keys. Missing required top-level skills array and summary object.

agents skill show --format json (line 775–792 of skill.py):
Outputs the same flat _skill_spec_dict() dict. Missing required nested structure.

Expected Behavior

agents skill add --format json must produce (per spec):

{
  "data": {
    "skill": { "name": "...", "description": "...", "config": "...", "created": "..." },
    "includes": [{ "name": "...", "status": "registered" }],
    "tool_sources": [{ "source": "builtin", "count": 14, "details": "..." }],
    "total_tools": 23,
    "mcp_servers": [{ "name": "linear", "status": "validated", "tools": 2 }]
  }
}

agents skill list --format json must produce (per spec):

{
  "data": {
    "skills": [
      { "name": "local/file-ops", "tools": 9, "includes": 0, "sources": ["builtin"] }
    ],
    "summary": { "total": 5, "local": 5, "server": 0, "total_tools": 28 }
  }
}

agents skill show --format json must produce (per spec):

{
  "data": {
    "skill": { "name": "...", "description": "...", "config": "...", "created": "...", "updated": "..." },
    "includes": [{ "name": "...", "tools": 9, "source": "builtin" }],
    "direct_tools": [{ "name": "...", "source": "...", "writes": true, "checkpoint": "..." }],
    "mcp_servers": [{ "name": "...", "transport": "stdio", "tools": 2, "status": "connected" }],
    "capability_summary": { "total_tools": 23, "read_only": 10, "writes": 13, "checkpointable": 10, "has_side_effects": 3, "requires_approval": 1 },
    "referenced_by": { "actors": [...], "skills": [...] }
  }
}

Note: spec uses read_only/writes/checkpointable in capability_summary, but code uses read_only_tools/write_tools/checkpointable_tools. Also referenced_by key is absent.

Acceptance Criteria

agents skill add --format json outputs data.skill, data.includes (array of objects with name+status), data.tool_sources (array of objects with source+count+details), data.total_tools, data.mcp_servers
agents skill list --format json outputs data.skills (array of {name, tools, includes, sources}), data.summary ({total, local, server, total_tools})
agents skill show --format json outputs data.skill, data.includes (with tools+source per entry), data.direct_tools, data.mcp_servers, data.capability_summary (with spec field names: read_only, writes, checkpointable, has_side_effects, requires_approval), data.referenced_by

Supporting Information

Spec: docs/specification.md §§ "agents skill add", "agents skill list", "agents skill show" (JSON tab examples)
Code: src/cleveragents/cli/commands/skill.py lines 508–511, 676–695, 775–792

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

## Background and Context The spec (§ "agents skill add", "agents skill list", "agents skill show") defines specific JSON schemas for these commands under `--format json`. Code analysis of `src/cleveragents/cli/commands/skill.py` shows all three commands produce incorrect/flat output schemas that do not match the spec. ## Current Behavior **`agents skill add --format json`** (line 508–511 of `skill.py`): ```python data = _skill_spec_dict(skill, service) data["is_new"] = is_new typer.echo(format_output(data, fmt)) ``` `_skill_spec_dict()` returns a flat dict with `name`, `namespace`, `short_name`, `description`, `config_path`, `tool_refs`, `includes` (list of name strings), `mcp_servers`, `agent_skills`, `sources`. This does NOT match the spec schema. **`agents skill list --format json`** (line 676–695 of `skill.py`): Outputs a flat array where each element is the same flat `_skill_spec_dict()` result with added `tool_count` and `capability_summary` keys. Missing required top-level `skills` array and `summary` object. **`agents skill show --format json`** (line 775–792 of `skill.py`): Outputs the same flat `_skill_spec_dict()` dict. Missing required nested structure. ## Expected Behavior **`agents skill add --format json`** must produce (per spec): ```json { "data": { "skill": { "name": "...", "description": "...", "config": "...", "created": "..." }, "includes": [{ "name": "...", "status": "registered" }], "tool_sources": [{ "source": "builtin", "count": 14, "details": "..." }], "total_tools": 23, "mcp_servers": [{ "name": "linear", "status": "validated", "tools": 2 }] } } ``` **`agents skill list --format json`** must produce (per spec): ```json { "data": { "skills": [ { "name": "local/file-ops", "tools": 9, "includes": 0, "sources": ["builtin"] } ], "summary": { "total": 5, "local": 5, "server": 0, "total_tools": 28 } } } ``` **`agents skill show --format json`** must produce (per spec): ```json { "data": { "skill": { "name": "...", "description": "...", "config": "...", "created": "...", "updated": "..." }, "includes": [{ "name": "...", "tools": 9, "source": "builtin" }], "direct_tools": [{ "name": "...", "source": "...", "writes": true, "checkpoint": "..." }], "mcp_servers": [{ "name": "...", "transport": "stdio", "tools": 2, "status": "connected" }], "capability_summary": { "total_tools": 23, "read_only": 10, "writes": 13, "checkpointable": 10, "has_side_effects": 3, "requires_approval": 1 }, "referenced_by": { "actors": [...], "skills": [...] } } } ``` Note: spec uses `read_only`/`writes`/`checkpointable` in `capability_summary`, but code uses `read_only_tools`/`write_tools`/`checkpointable_tools`. Also `referenced_by` key is absent. ## Acceptance Criteria - [ ] `agents skill add --format json` outputs `data.skill`, `data.includes` (array of objects with `name`+`status`), `data.tool_sources` (array of objects with `source`+`count`+`details`), `data.total_tools`, `data.mcp_servers` - [ ] `agents skill list --format json` outputs `data.skills` (array of `{name, tools, includes, sources}`), `data.summary` (`{total, local, server, total_tools}`) - [ ] `agents skill show --format json` outputs `data.skill`, `data.includes` (with `tools`+`source` per entry), `data.direct_tools`, `data.mcp_servers`, `data.capability_summary` (with spec field names: `read_only`, `writes`, `checkpointable`, `has_side_effects`, `requires_approval`), `data.referenced_by` ## Supporting Information - Spec: `docs/specification.md` §§ "agents skill add", "agents skill list", "agents skill show" (JSON tab examples) - Code: `src/cleveragents/cli/commands/skill.py` lines 508–511, 676–695, 775–792 --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-10 03:40:16 +00:00

HAL9000 added this to the v3.4.0 milestone

2026-04-10 04:39:50 +00:00

HAL9000 added the

MoSCoW

Must have

label

2026-04-10 04:45:44 +00:00

HAL9000 commented

2026-04-10 04:47:41 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: High — Skill JSON output format non-compliance breaks automated tooling. The spec defines precise nested structures for skill data.
Milestone: v3.4.0 — Skill management is an M5 feature (Actor/Skill/Tool track)
MoSCoW: Must Have — Per policy, all bugs are Must Have. This is part of a batch of actor/skill/tool format compliance bugs (#6857, #6858, #6859, #6861, #6862).

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

Issue triaged by project owner: - **State**: Verified - **Priority**: High — Skill JSON output format non-compliance breaks automated tooling. The spec defines precise nested structures for skill data. - **Milestone**: v3.4.0 — Skill management is an M5 feature (Actor/Skill/Tool track) - **MoSCoW**: Must Have — Per policy, all bugs are Must Have. This is part of a batch of actor/skill/tool format compliance bugs (#6857, #6858, #6859, #6861, #6862). --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added the

Points

label

2026-04-10 06:04:39 +00:00

HAL9000 self-assigned this

2026-04-10 06:06:36 +00:00