Revise and remove A2A

artberger · artberger · commit 79a7830f1cd7 · 2025-11-24T09:40:04.000-05:00
Signed-off-by: Art Berger &lt;art.berger@solo.io&gt;
diff --git a/src/app/docs/kagent/concepts/agents/page.mdx b/src/app/docs/kagent/concepts/agents/page.mdx
@@ -50,11 +50,11 @@ Kagent comes with a set of built-in tools that you can use to interact with your
 
 ## Skills
 
-Skills are descriptions of the capabilities that an agent has to act more autonomously. They make the LLM's responses more than just reactions to prompts by orienting them toward goals.
+Skills are descriptions or even executable implementations of the capabilities that an agent has to act more autonomously. They make the LLM's responses more than just reactions to prompts by orienting them toward goals.
 
 In some frameworks, skills are expressed as wrapped functions, reusable prompt templates, or even a synonym for a tool.
 
-In kagent, think of skills like a catalog that expresses what the agent is capable of doing for a user. Unlike tools, skills are not a specific function that produces an output, like "fetch a website" or "tell the weather." Unlike system instructions, they are not rules that apply to all interactions, such as "Follow my company's style guide."
+Think of skills like a catalog that expresses what the agent is capable of doing for a user. Unlike tools, skills are not a specific function that produces an output, like "fetch a website" or "tell the weather." Unlike system instructions, they are not rules that apply to all interactions, such as "Follow my company's style guide."
 
 Instead, skills are building blocks that guide the agent's tool usage and planning. They help the agent understand what its goals are, and when and how to use tools effectively.
 
@@ -63,13 +63,50 @@ For example, two agents may share the same tools but use them differently based
 - A troubleshooting agent might use a `describe` tool to check the events of a crashing pod before taking a recovery action, such as restarting the pod.
 - A research agent might use the same `describe` tool to gather details about a pod in order to answer a user's question.
 
-Kagent supports two types of skills:
+Skills can refer to two broad types:
 
-1. **A2A skills** (metadata): Structured descriptions of capabilities defined in `a2aConfig.skills`. These consist of a description, examples, ID, and tags that help guide the agent's behavior. The description and examples provide context for both humans and the agent itself, often incorporated into system instructions. The ID and tags help you manage skills, such as by making it simpler to compare and reuse them across agents.
+* **A2A skills**: Metadata-based skills that are defined inline in the agent specification.
+* **Kagent's container-based skills**: Executable skills packaged as container images and loaded from registries, for reuse across agents. You can use the [agentregistry project](https://github.com/agentregistry-dev/agentregistry) to build and push skills to a registry.
 
-2. **Container-based skills**: Executable skill implementations packaged as container images. These skills contain instructions, scripts, and resources that are loaded from container registries and made available to the agent at runtime. You can build and push skills as container images, then reference them in `spec.skills.refs` to load them into your agents.
+### A2A skills metadata
 
-Skills in kagent are similar to [Claude's Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview), but with a key advantage: any agent can use skills, regardless of the LLM provider. You're not limited to Anthropic Claude. You can use skills with OpenAI, Google Vertex AI, Azure OpenAI, Ollama, and any other LLM provider that kagent supports.
+Actions-to-actions (A2A) skills are metadata—structured descriptions of capabilities, not executable code. Think of A2A skills as a machine-readable catalog entry about what a tool can do.
+
+A2A skills metadata describes:
+
+- What a capability is
+- What the capability can do
+- The inputs and outputs
+- Safety requirements
+- How a model should think about the capability
+
+A2A skills metadata does not:
+
+- Provide runtime code
+- Execute actions
+- Bundle actual logic for performing the skill
+
+In kagent, you define A2A skills in `a2aConfig.skills`. These consist of a description, examples, ID, and tags that help guide the agent's behavior. The description and examples provide context for both humans and the agent itself, often incorporated into system instructions. The ID and tags help you manage skills, such as by making it simpler to compare and reuse them across agents.
+
+A2A skills are instructions about capabilities, not the capabilities themselves. That is why A2A is sometimes described as "just metadata"—it's descriptive information, not executable code.
+
+### Container-based skills
+
+Kagent's container-based skills are executable skill implementations packaged as container images. These are runnable procedural logic that the agent can use as an extension of itself.
+
+Container-based skills include:
+
+- Executable code snippets or procedures
+- Behavior modules that the agent can call at inference time
+- Validation and step-by-step behaviors
+- Reusable functions
+- Direct execution capabilities
+
+These skills contain instructions, scripts, and resources that are loaded from container registries and made available to the agent at runtime. You can build and push skills as container images, then reference them in `spec.skills.refs` to load them into your agents.
+
+Container-based skills are actual, callable capabilities—not just descriptions of capabilities.
+
+Kagent's skills are similar to [Claude's Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview), but with a key advantage: any agent can use skills, regardless of the LLM provider. You're not limited to Anthropic Claude. You can use skills with OpenAI, Google Vertex AI, Azure OpenAI, Ollama, and any other LLM provider that kagent supports.
 
 ### Best practices for skills
 
diff --git a/src/app/docs/kagent/examples/skills/page.mdx b/src/app/docs/kagent/examples/skills/page.mdx
@@ -14,123 +14,21 @@ export const metadata = {
 
 Skills are descriptions of capabilities that help agents act more autonomously. They guide the agent's tool usage and planning by orienting responses toward goals rather than just reacting to prompts.
 
-In this guide, you learn how to add skills to your agents in kagent. Kagent supports two types of skills:
+In this guide, you learn how to add container-based skills to your agents in kagent. 
 
-1. **A2A skills** (metadata): Structured descriptions of capabilities defined inline the agent specification in the `a2aConfig.skills` field.
-2. **Container-based skills**: Executable skills packaged as container images and loaded from registries, for reuse across agents. You can use the [agentregistry project](https://github.com/agentregistry-dev/agentregistry) to build and push skills to a registry.
+<Aside type="tip">
+Want to containerize and manage your skills? Try out the [agentregistry project](https://github.com/agentregistry-dev/agentregistry) to build and push skills to a secure, AI-first container registry. Agentregistry also has a [repo of example skills](https://github.com/agentregistry-dev/skills) based on Claude Skills that you can use as a starting point.
+</Aside>
 
 ## Before you begin
 
 1. Install kagent by following the [quick start](/docs/kagent/getting-started/quickstart) guide.
 
 2. Review the concepts of [agents and skills](/docs/kagent/concepts/agents) in kagent.
 
-## Inline A2A skills metadata
-
-Create an agent that uses skills to guide its behavior. This example creates a Kubernetes troubleshooting agent with skills for diagnosing and fixing issues.
-
-Skills are defined under `a2aConfig` in the agent specification. Even if you're not exposing your agent via the A2A protocol, defining skills under `a2aConfig` helps guide the agent's behavior and tool usage in all conversations.
-
-```yaml
-kubectl apply -f - <<EOF
-apiVersion: kagent.dev/v1alpha2
-kind: Agent
-metadata:
-  name: k8s-troubleshooting-agent
-  namespace: kagent
-spec:
-  description: A Kubernetes agent specialized in troubleshooting cluster issues
-  type: Declarative
-  declarative:
-    modelConfig: default-model-config
-    systemMessage: |-
-      You are a Kubernetes troubleshooting expert. Use your skills to diagnose
-      and resolve issues in the cluster. When investigating problems, follow a
-      systematic approach: gather information, identify root causes, and propose
-      solutions.
-    tools:
-      - type: McpServer
-        mcpServer:
-          name: kagent-tool-server
-          kind: RemoteMCPServer
-          toolNames:
-            - k8s_get_resources
-            - k8s_describe_resource
-            - k8s_get_logs
-            - k8s_get_events
-    a2aConfig:
-      skills:
-      - id: diagnose-pod-issues
-        name: Diagnose Pod Issues
-        description: Investigate and diagnose problems with Kubernetes pods, including crashes, restarts, and resource constraints
-        inputModes:
-          - text
-        outputModes:
-          - text
-        tags:
-          - troubleshooting
-          - pods
-          - diagnostics
-        examples:
-          - "Why is my pod crashing?"
-          - "Investigate the pod restarts in the production namespace"
-          - "Check why the pod is not starting"
-          - "Diagnose resource issues with my deployment"
-      - id: analyze-cluster-health
-        name: Analyze Cluster Health
-        description: Assess the overall health and status of the Kubernetes cluster
-        inputModes:
-          - text
-        outputModes:
-          - text
-        tags:
-          - cluster
-          - health
-          - monitoring
-        examples:
-          - "What's the health status of my cluster?"
-          - "Check if there are any issues in the cluster"
-          - "Analyze cluster resource usage"
-          - "Review cluster events for problems"
-EOF
-```
-
-### Understand the A2A skills metadata configuration
-
-Review the following table to understand the A2A skills metadata configuration.
-
-| Field | Description | `diagnose-pod-issues` skill | `analyze-cluster-health` skill |
-|-------|------------|----------------------|-------------------------|
-| **id** | A unique identifier for the skill | `diagnose-pod-issues` | `analyze-cluster-health` |
-| **name** | A human-readable name for the skill | Diagnose Pod Issues | Analyze Cluster Health |
-| **description** | What the skill enables the agent to do | Investigate and diagnose problems with Kubernetes pods, including crashes, restarts, and resource constraints | Assess the overall health and status of the Kubernetes cluster |
-| **inputModes** | The data types that the skill accepts as input | `text` | `text` |
-| **outputModes** | The data types that the skill produces as output | `text` | `text` |
-| **tags** | Categories for organizing and filtering skills | `troubleshooting`, `pods`, `diagnostics` | `cluster`, `health`, `monitoring` |
-| **examples** | Sample queries that trigger this skill | "Why is my pod crashing?"<br/>"Investigate the pod restarts in the production namespace"<br/>"Check why the pod is not starting"<br/>"Diagnose resource issues with my deployment" | "What's the health status of my cluster?"<br/>"Check if there are any issues in the cluster"<br/>"Analyze cluster resource usage"<br/>"Review cluster events for problems" |
-
-### Test A2A skills
-
-For agents with A2A skills metadata, test with queries that match the skill examples.
-
-```bash
-kagent invoke --agent k8s-troubleshooting-agent --task "Can you find any unhealthy pods in the kagent namespace?"
-```
-
-Example output: The agent uses its "Diagnose Pod Issues" skill to systematically investigate the problem.
-
-```json
-{"artifacts":[{"artifactId":"b626f5ea-1994-48e0-8266-0141bda3322d","parts":[{"kind":"text","text":"All the pods in the kagent namespace appear to be healthy. They are all in the \"Running\" status with all containers ready (1/1) and no restarts reported. There are no unhealthy pods in the kagent namespace at this time. Is there anything specific you would like me to check or troubleshoot further?"}]}],
-...
-```
-
 ## Container-based skills
 
-Container-based skills are executable skill implementations packaged as container images. These skills contain instructions, scripts, and other resources that the agent can discover and use at runtime. This way, you can reuse skills across agents. You might pair the inline metadata skills with more general purpose, container-based skills depending on your agent's needs.
-
-<Aside type="tip">
-You can use the [agentregistry project](https://github.com/agentregistry-dev/agentregistry) to build and push skills to a registry. Agentregistry also has a [repo of example skills](https://github.com/agentregistry-dev/skills) based on Claude Skills that you can use as a starting point.
-</Aside>
+Container-based skills are executable skill implementations packaged as container images. These skills contain instructions, scripts, and other resources that the agent can discover and use at runtime. This way, you can reuse skills across agents.
 
 ### Step 1: Build a skill container
 
