[Feat]: Add metadata field to AgentSkill as a generic extension point

### Is your feature request related to a problem? Please describe.

This proposal introduces `metadata` as a generic, optional, and non-semantic extension point, aligning `AgentSkill` with the broader A2A data model. As large-scale agent orchestration and agent-first ecosystems grow in size and diversity, `AgentSkill` increasingly serves as a **descriptive contract** rather than just a list of callable capabilities. Today, the model lacks a general-purpose extension point for non-semantic, per-skill attributes that do not belong in the core schema but are nevertheless important to producers and consumers.

This gap forces implementers to either overload existing fields, invent conventions, or maintain parallel systems, all of which reduce clarity and interoperability.

### Describe the solution you'd like

This feature proposal requests the addition of an optional `metadata` field to the `AgentSkill` interface to provide a general-purpose, non-semantic extension point for per-skill attributes, which can lead to enhanced skill discovery, classification, and client-side analysis capabilities. Currently, as it stands in version `0.3.0`, the `AgentSkill` interface provides a fixed set of descriptive fields (`id`, `name`, `description`, `tags`, ...) for basic categorization, communicating what a skill _is_ and _how it may be used_. While the existing shape is sufficient for basic representation, the model does not provide a _standardized_ way to attach additional structured information that producers and consumers frequently need *without expanding the core schema*.

Today, implementers must either overload `tags`, create custom private registries, or extend the type model - all of which are _brittle_, _non-scalable_, and _reduce interoperability across independently developed agents_. The A2A spec already supports metadata on multiple objects (e.g., `Task`, `Message`, `Part`, `Artifact`, etc.), and we believe `AgentSkill` should be fortified with metadata to be consistent with the broader model.

---

### Considerations

A2A should allow ecosystems to evolve _without_ repeatedly adding narrowly scoped first-class fields to core objects. A generic `metadata` map provides a stable extension point for **new** per-skill attributes. This proposal is purely _additive_, ensuring that _existing_ Agent Cards and clients remain valid, and schema validation remains straightforward.

This `metadata` field is intended to extend an `AgentSkill` and **MUST NOT** change the semantic meaning of the skill; clients **MAY** ignore it. This preserves interoperability and prevents optional fields from becoming protocol requirements.

While some implementations _may_ use this field for *classification*, *presentation hints*, *governance*, *analytics*, or *other domain-specific attributes*, the specification update does **NOT** prescribe any single use case.

---

### Proposed Change

As of the most current version, `0.3.0`, the AgentSkill has the shape:
```ts
export interface AgentSkill {
id: string;
name: string;
description: string;
tags: string[];
examples?: string[];
inputModes?: string[];
outputModes?: string[];
security?: { [scheme: string]: string[] }[];
}
```

With this change, we propose that the `AgentSkill` is **extended** to support a `metadata` field, similar to the existing `Task` object. **This could be represented as:**
```ts
export interface AgentSkill {
id: string;
name: string;
description: string;
tags: string[];
examples?: string[];
inputModes?: string[];
outputModes?: string[];
security?: { [scheme: string]: string[] }[];
/**
* Optional structured metadata associated with the skill for extensions.
* Values must be JSON-serializable, and MUST NOT alter skill semantics.
*/
metadata?: {
[key: string]: any;
};
}
```
This aligns with the spec’s [existing definition](https://a2a-protocol.org/v0.3.0/specification/#61-task-object) of metadata as a flexible JSON map and its existing role as an extension surface.

---

### Examples

Below we attempt to define and explicitly show the potential use cases, generally stemming from issues faced when defining enterprise-scale agentic systems, to illustrate the desire for such a field. Note that these skills are purely _illustratory_, and are **not** intended to assert a required vocabulary.

#### Hierarchical classification of skills (taxonomic)
```json
{
"id": "invoice-status",
"name": "Invoice Status Lookup",
"description": "Retrieves invoice status from enterprise platform by invoice ID.",
"tags": ["invoice", "ap", "status"],
"metadata": {
"taxonomy": {
"path": ["finance", "accounts-payable", "invoicing"],
"capabilityId": "FIN.AP.INVOICE.STATUS"
}
}
}
```
The metadata field in this simple example shows the potential for how clients can build a tree UI for faceted browsing (domain -> subdomain -> capability) without complex tag parsing.

#### Ownership, maturity, hints/subcapabilities
```json
{
"id": "deductions-create-case",
"name": "Create Deductions Case",
"description": "Creates a deductions case and returns the case ID.",
"tags": ["deductions", "claims", "case-management"],
"metadata": {
"taxonomy": { "path": ["finance", "deductions"] },
"owner": { "team": "fin-ops-automation", "onCall": "finops-oncall" },
"lifecycle": { "maturity": "beta", "deprecationDate": null },
"clientHints": {
"suggestedUiGroup": "Finance",
"requiresConfirmation": true
}
}
}
```
This metadata is a bit more complex than the first example, and is showing how the metadata can drive discovery UX, expand/improve governance and observability (potential feature-flagging/lifecycle staging), and enforce ruling on skills for clients to abide by (such as propagating that a skill will require human confirmation to be run).

#### Extensible and complex strongly-typed metadata for clients
```json
{
"id": "invoice-status",
"name": "Invoice Status Lookup",
"description": "Retrieves invoice status from enterprise platform by invoice ID.",
"tags": ["invoice", "ap", "status"],
"metadata": {
"taxonomy": {
"path": ["finance", "accounts-payable", "invoicing"],
"capabilityCode": "FIN.AP.INVOICE.STATUS",
"synonyms": ["invoice lookup", "check invoice", "payment status"]
},
"discovery": {
"facets": {
"domain": "Finance",
"process": "Accounts Payable",
"entity": "Invoice"
},
"searchBoost": 1.3
},
"ui": {
"icon": "PdfDocumentIcon",
"color": "#5B98F5",
"featured": true,
"badges": ["popular", "new"],
"thumbnail": "https://cdn.oursite.com/skills/invoice-status.png"
},
"presentation": {
"shortDescription": "Get invoices",
"callToAction": "Search Invoices",
"placeholderText": "are there any outstanding invoices?",
}
}
}
```
This last example is a purposefully complex, though still _non-semantic_, extending [the first example](#Hierarchical-classification-of-skills-(taxonomic)) showing how rich metadata can _holistically_ propel agent usage in a controlled enterprise ecosystem. In this example extend the use-case to include semantic relevance tagging to match specific terms even if the tag isn't explicitly defined.

As agent orchestrators scale out, their cognitive load due to agent-overloading or skill-overloading is something that can quickly cause degradation to a system. As shown in the [the example above](#Extensible-and-complex-strongly-typed-metadata-for-clients), defining custom metadata attributes on the `AgentSkill` object can help alleviate the burden by defining a granular taxonomic system by which skills can be correctly identified, even when superficially-duplicate skills exist across domains/agents (e.g., different agents that have skills to extract content from a PDF). We believe that this, when paired with the `examples` field and simple `tags` field, will help fortify large-scale agent orchestration in a way previously only achievable through complex mappings and architecture.

As stated previously, the examples show potential for _how_ `metadata` _may_ be used in `AgentSkill`, and does **NOT** prescribe any single use case.

---

### Interoperability, backwards compatibility, and non-goals

In order to comply with interoperability and backwards compatibility, we propose that the `metadata` field is strictly **optional** - ensuring existing agents/clients remain valid. Similarly, clients that do not understand or need metadata can ignore it safely.

Please note that our **non-goals** include: standardizing a universal taxonomy vocabulary in-core (we believe it should be left to implementations or extensions), as well as changing routing semantics or requiring clients to interpret metadata. We propose clear boundaries and an intentional design for these.

---

### TLDR

We believe a `metadata` field should be added to `AgentSkill` model to provide a _standardized_ way to attach additional structured information.

### Describe alternatives you've considered

We have attempted several ways to work around the lack of a `metadata` field. One such alternative was to overload tags, which works superficially, but forces clients to parse conventions, it's brittle, error-prone, and can't support multiple orthogonal dimensions. Another alternative was to create privatized registries/catalogs, but this breaks portability/interop across agents, as well as creates drift/complicates clients that want one-off discovery. Lastly, we tried to extend the type model, which solves the immediate problem but breaks schema compliance, increases friction, and reduces parity with external/third-party agents (and doesn't work well with statically-typed SDKs).

### Additional context

_No response_

### Code of Conduct

- [x] I agree to follow this project's Code of Conduct