cleveragents/cleveragents-core

Fork 3

UAT: Agent Skills metadata not injected into actor system prompt in spec-required XML format — `<available_agent_skills>` block is never generated #2131

New issue

Open

opened 2026-04-03 04:19:41 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 04:19:41 +00:00

Owner

Metadata

Branch: fix/agent-skill-system-prompt-xml-injection
Commit Message: fix(skills): implement to_system_prompt_xml() on AgentSkillToolDescriptor and inject <available_agent_skills> block into actor system prompt
Milestone: v3.7.0
Parent Epic: #392

Background and Context

The project specification (§AgentSkillAdapter) defines that when an actor has Agent Skills available, their metadata must be injected into the actor's system prompt in a specific XML format. This injection mechanism — the Tier 1 progressive disclosure step — is not implemented anywhere in the codebase.

Code-level analysis of src/cleveragents/skills/agent_skills_loader.py, src/cleveragents/skills/discovery.py, and src/cleveragents/domain/models/core/skill.py was performed against the docs/specification.md AgentSkillAdapter section.

Current Behavior

The AgentSkillLoader.discover() method returns an AgentSkillToolDescriptor with name, description, and other metadata, but there is no code anywhere in the codebase that:

Generates the <available_agent_skills> XML block
Injects this XML into the actor's system prompt
Formats individual <agent_skill> entries with <name>, <description>, and <tool> sub-elements

The AgentSkillToolDescriptor model has all the necessary data fields, but there is no serialization method that produces the spec-required XML format. The actor runtime does not call any method to generate or inject this XML.

Steps to reproduce:

loader = AgentSkillLoader.from_folder(Path("./skills/deploy-to-staging"))
descriptor = loader.discover()
# Try to get XML for system prompt injection:
xml = descriptor.to_system_prompt_xml()  # AttributeError: no such method

Observed: AttributeError: 'AgentSkillToolDescriptor' object has no attribute 'to_system_prompt_xml'

Code locations:

src/cleveragents/skills/agent_skills_loader.py, AgentSkillLoader.discover() — returns descriptor but no XML generation
src/cleveragents/skills/agent_skills_loader.py, AgentSkillToolDescriptor — no to_system_prompt_xml() or equivalent method
No actor runtime code injects Agent Skills metadata into system prompts

Expected Behavior

Per docs/specification.md (§AgentSkillAdapter), during discover(), Agent Skills metadata must be injected into the agent's system prompt in this structured XML format:

<available_agent_skills>
  <agent_skill>
    <name>deploy-to-staging</name>
    <description>Deploy the current branch to the staging environment.</description>
    <tool>local/deploy-staging</tool>
  </agent_skill>
</available_agent_skills>

The spec states: "This metadata is injected into the agent's system prompt in a structured format so the LLM can decide when the skill is relevant." The spec notes this is "low-cost — only ~50–100 tokens per Agent Skill for metadata."

Acceptance Criteria

AgentSkillToolDescriptor has a to_system_prompt_xml() method that returns a correctly formatted <agent_skill> XML fragment with <name>, <description>, and <tool> sub-elements
A collection-level helper (e.g., build_available_agent_skills_xml(descriptors)) wraps multiple <agent_skill> entries in an <available_agent_skills> block
The actor runtime calls this XML generation and injects the resulting block into the actor's system prompt when Agent Skills are available
The injected XML matches the spec-required format exactly
BDD scenarios cover: single skill injection, multiple skills injection, no skills (no block injected), and XML format correctness
All nox quality gates pass
Coverage ≥ 97%

Supporting Information

Affected files: src/cleveragents/skills/agent_skills_loader.py (AgentSkillToolDescriptor, AgentSkillLoader.discover()); actor runtime system prompt assembly code
Spec reference: §AgentSkillAdapter — progressive disclosure Tier 1 (metadata injection), system prompt XML format
Severity: Medium — Without system prompt injection, the LLM agent cannot discover available Agent Skills and decide when to use them. The progressive disclosure model (Tier 1 metadata injection) is non-functional.

Subtasks

Write a @tdd_expected_fail-tagged Behave scenario in features/ demonstrating that AgentSkillToolDescriptor has no to_system_prompt_xml() method (issue-capture test per bug-fix workflow)
Write a @tdd_expected_fail-tagged Behave scenario demonstrating that the actor runtime does not inject the <available_agent_skills> block into the system prompt
Add to_system_prompt_xml() -> str method to AgentSkillToolDescriptor in src/cleveragents/skills/agent_skills_loader.py that returns a correctly formatted <agent_skill> XML fragment
Add a module-level build_available_agent_skills_xml(descriptors: list[AgentSkillToolDescriptor]) -> str helper that wraps all fragments in <available_agent_skills>...</available_agent_skills>
Identify the actor runtime system prompt assembly location and inject the <available_agent_skills> block when Agent Skills are present
Add static type annotations to all new methods and verify with nox -e typecheck (Pyright — no # type: ignore permitted)
Remove @tdd_expected_fail tags and ensure both issue-capture scenarios now pass
Add additional Behave unit test scenarios covering: single skill, multiple skills, no skills (no block emitted), XML format correctness, and round-trip parse
Write Robot Framework integration test in robot/ verifying end-to-end: discover Agent Skill → assert <available_agent_skills> block appears in actor system prompt
Update docstrings for AgentSkillToolDescriptor and AgentSkillLoader.discover() to document the XML injection contract
Verify nox -e coverage_report reports ≥ 97% coverage
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
AgentSkillToolDescriptor.to_system_prompt_xml() is implemented and produces spec-compliant XML.
build_available_agent_skills_xml() correctly wraps multiple descriptors in the <available_agent_skills> block.
The actor runtime injects the <available_agent_skills> block into the system prompt when Agent Skills are available.
All Behave unit test scenarios pass (nox -e unit_tests).
Robot Framework integration test passes (nox -e integration_tests).
Pyright type checking passes with no suppressions (nox -e typecheck).
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(skills): implement to_system_prompt_xml() on AgentSkillToolDescriptor and inject <available_agent_skills> block into actor system prompt), 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 (fix/agent-skill-system-prompt-xml-injection).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage ≥ 97%.

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

## Metadata - **Branch**: `fix/agent-skill-system-prompt-xml-injection` - **Commit Message**: `fix(skills): implement to_system_prompt_xml() on AgentSkillToolDescriptor and inject <available_agent_skills> block into actor system prompt` - **Milestone**: v3.7.0 - **Parent Epic**: #392 ## Background and Context The project specification (§AgentSkillAdapter) defines that when an actor has Agent Skills available, their metadata must be injected into the actor's system prompt in a specific XML format. This injection mechanism — the Tier 1 progressive disclosure step — is not implemented anywhere in the codebase. Code-level analysis of `src/cleveragents/skills/agent_skills_loader.py`, `src/cleveragents/skills/discovery.py`, and `src/cleveragents/domain/models/core/skill.py` was performed against the `docs/specification.md` AgentSkillAdapter section. ## Current Behavior The `AgentSkillLoader.discover()` method returns an `AgentSkillToolDescriptor` with name, description, and other metadata, but there is no code anywhere in the codebase that: 1. Generates the `<available_agent_skills>` XML block 2. Injects this XML into the actor's system prompt 3. Formats individual `<agent_skill>` entries with `<name>`, `<description>`, and `<tool>` sub-elements The `AgentSkillToolDescriptor` model has all the necessary data fields, but there is no serialization method that produces the spec-required XML format. The actor runtime does not call any method to generate or inject this XML. **Steps to reproduce:** ```python loader = AgentSkillLoader.from_folder(Path("./skills/deploy-to-staging")) descriptor = loader.discover() # Try to get XML for system prompt injection: xml = descriptor.to_system_prompt_xml() # AttributeError: no such method ``` **Observed:** `AttributeError: 'AgentSkillToolDescriptor' object has no attribute 'to_system_prompt_xml'` **Code locations:** - `src/cleveragents/skills/agent_skills_loader.py`, `AgentSkillLoader.discover()` — returns descriptor but no XML generation - `src/cleveragents/skills/agent_skills_loader.py`, `AgentSkillToolDescriptor` — no `to_system_prompt_xml()` or equivalent method - No actor runtime code injects Agent Skills metadata into system prompts ## Expected Behavior Per `docs/specification.md` (§AgentSkillAdapter), during `discover()`, Agent Skills metadata must be injected into the agent's system prompt in this structured XML format: ```xml <available_agent_skills> <agent_skill> <name>deploy-to-staging</name> <description>Deploy the current branch to the staging environment.</description> <tool>local/deploy-staging</tool> </agent_skill> </available_agent_skills> ``` The spec states: *"This metadata is injected into the agent's system prompt in a structured format so the LLM can decide when the skill is relevant."* The spec notes this is *"low-cost — only ~50–100 tokens per Agent Skill for metadata."* ## Acceptance Criteria - [ ] `AgentSkillToolDescriptor` has a `to_system_prompt_xml()` method that returns a correctly formatted `<agent_skill>` XML fragment with `<name>`, `<description>`, and `<tool>` sub-elements - [ ] A collection-level helper (e.g., `build_available_agent_skills_xml(descriptors)`) wraps multiple `<agent_skill>` entries in an `<available_agent_skills>` block - [ ] The actor runtime calls this XML generation and injects the resulting block into the actor's system prompt when Agent Skills are available - [ ] The injected XML matches the spec-required format exactly - [ ] BDD scenarios cover: single skill injection, multiple skills injection, no skills (no block injected), and XML format correctness - [ ] All nox quality gates pass - [ ] Coverage ≥ 97% ## Supporting Information - **Affected files**: `src/cleveragents/skills/agent_skills_loader.py` (`AgentSkillToolDescriptor`, `AgentSkillLoader.discover()`); actor runtime system prompt assembly code - **Spec reference**: §AgentSkillAdapter — progressive disclosure Tier 1 (metadata injection), system prompt XML format - **Severity**: Medium — Without system prompt injection, the LLM agent cannot discover available Agent Skills and decide when to use them. The progressive disclosure model (Tier 1 metadata injection) is non-functional. ## Subtasks - [ ] Write a `@tdd_expected_fail`-tagged Behave scenario in `features/` demonstrating that `AgentSkillToolDescriptor` has no `to_system_prompt_xml()` method (issue-capture test per bug-fix workflow) - [ ] Write a `@tdd_expected_fail`-tagged Behave scenario demonstrating that the actor runtime does not inject the `<available_agent_skills>` block into the system prompt - [ ] Add `to_system_prompt_xml() -> str` method to `AgentSkillToolDescriptor` in `src/cleveragents/skills/agent_skills_loader.py` that returns a correctly formatted `<agent_skill>` XML fragment - [ ] Add a module-level `build_available_agent_skills_xml(descriptors: list[AgentSkillToolDescriptor]) -> str` helper that wraps all fragments in `<available_agent_skills>...</available_agent_skills>` - [ ] Identify the actor runtime system prompt assembly location and inject the `<available_agent_skills>` block when Agent Skills are present - [ ] Add static type annotations to all new methods and verify with `nox -e typecheck` (Pyright — no `# type: ignore` permitted) - [ ] Remove `@tdd_expected_fail` tags and ensure both issue-capture scenarios now pass - [ ] Add additional Behave unit test scenarios covering: single skill, multiple skills, no skills (no block emitted), XML format correctness, and round-trip parse - [ ] Write Robot Framework integration test in `robot/` verifying end-to-end: discover Agent Skill → assert `<available_agent_skills>` block appears in actor system prompt - [ ] Update docstrings for `AgentSkillToolDescriptor` and `AgentSkillLoader.discover()` to document the XML injection contract - [ ] Verify `nox -e coverage_report` reports ≥ 97% coverage - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - [ ] All subtasks above are completed and checked off. - [ ] `AgentSkillToolDescriptor.to_system_prompt_xml()` is implemented and produces spec-compliant XML. - [ ] `build_available_agent_skills_xml()` correctly wraps multiple descriptors in the `<available_agent_skills>` block. - [ ] The actor runtime injects the `<available_agent_skills>` block into the system prompt when Agent Skills are available. - [ ] All Behave unit test scenarios pass (`nox -e unit_tests`). - [ ] Robot Framework integration test passes (`nox -e integration_tests`). - [ ] Pyright type checking passes with no suppressions (`nox -e typecheck`). - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(skills): implement to_system_prompt_xml() on AgentSkillToolDescriptor and inject <available_agent_skills> block into actor system prompt`), 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 (`fix/agent-skill-system-prompt-xml-injection`). - [ ] The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - [ ] All nox stages pass. - [ ] Coverage ≥ 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added this to the v3.7.0 milestone

2026-04-03 04:19:44 +00:00

freemo referenced this issue

2026-04-03 04:20:11 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo added a new dependency

2026-04-03 04:21:17 +00:00

#392 Epic: Actor YAML & Compiler

freemo referenced this issue

2026-04-03 04:21:38 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 721 — v3.7.0 #2138

freemo referenced this issue

2026-04-03 04:22:00 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 04:31:47 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 731 — v3.7.0 #2157

freemo self-assigned this

2026-04-03 16:58:03 +00:00

freemo commented

2026-04-03 18:27:32 +00:00

Author

Owner

MoSCoW classification: Should Have

Rationale: This issue addresses an important spec requirement or quality improvement. The project should include this fix but it is not strictly essential for the milestone.

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

MoSCoW classification: **Should Have** Rationale: This issue addresses an important spec requirement or quality improvement. The project should include this fix but it is not strictly essential for the milestone. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner