[Feat]: Add metadata field to AgentSkill as a generic extension point #1395
Description
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:
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:
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 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)
{
"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
{
"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
{
"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 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, 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
- I agree to follow this project's Code of Conduct