# Design

## Architecture

```text
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:

```yaml
---
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:

```java
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`.