Design

Architecture

src/main/resources/skills/
  -> SKILL.md files
  -> ClasspathSkillRegistry bean
      -> loads classpath skills
      -> backs official read_skill
  -> PlannerSkillMetadataHook
      -> adds planner-only skill metadata messages
      -> does not expose read_skill
  -> SkillsAgentHook
      -> adds official read_skill ToolCallback for Executor / single-agent Chat
      -> adds SkillsInterceptor prompt augmentation outside Planner
  -> ChatService / AiOpsService
      -> Planner receives metadata only
      -> Executor and single-agent Chat receive official skill hook
      -> Verifier remains isolated

Skill Contract

Each skill folder contains a SKILL.md with YAML frontmatter:

---
name: diagnose-mysql-connection-pool
description: ...
---

The body contains:

Trigger conditions.
Required evidence.
Recommended tool order.
Query construction hints.
Stop conditions and low-confidence behavior.
Report requirements.
Eval anchor when one exists.

Prompt Injection

Planner agents receive a project-local PlannerSkillMetadataHook message that contains skill names and descriptions only. The message also requires selected_skill, selection_reason, and an ordered plan in the Planner output.

SkillsAgentHook provides SkillsInterceptor, which injects the official compact skill section containing skill names, descriptions, and loading instructions into model requests for:

Chat Executor prompt.
AIOps Executor prompt.
Single-agent Chat prompt.

Planner prompts are not augmented by SkillsAgentHook, so Planner cannot receive the official read_skill tool. Verifier prompt is not augmented.

Tool Exposure

Spring AI Alibaba's official ReadSkillTool exposes:

read_skill(skill_name)

The tool returns the full SKILL.md body for a known skill or a structured error for missing skills.

read_skill is supplied by SkillsAgentHook, not by local methodTools. Planner selects a skill from metadata and writes the selection into planner_plan; Executor reads the selected skill before executing scenario-specific evidence collection.

Trace Behavior

read_skill is a guidance tool, not an evidence tool. It does not write tool_invocation because the existing eval and verifier treat evidence tools as factual data sources. Actual diagnostic evidence must still come from lookup_knowledge, query_logs, query_metrics, and alert tools.

Fallback

If a skill is not found or cannot be read:

The tool returns a structured text error.
The agent must fall back to generic Executor prompt behavior.
It must not invent playbook content.

Alibaba Skills Integration

The implementation uses spring-ai-alibaba-agent-framework:1.1.2.0, where SkillsAgentHook lives in com.alibaba.cloud.ai.graph.agent.hook.skills and ClasspathSkillRegistry lives in com.alibaba.cloud.ai.graph.skills.registry.classpath.

2.9 KiB Raw Blame History