From agent-almanac
Designs an A2A Agent Card (.well-known/agent.json) manifest describing agent capabilities, skills, authentication, and content types for multi-agent discovery and orchestration.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-almanac:design-a2a-agent-cardThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Create a standards-compliant A2A Agent Card that advertises an agent's identity, skills, authentication requirements, and capabilities for discovery by other agents.
Create a standards-compliant A2A Agent Card that advertises an agent's identity, skills, authentication requirements, and capabilities for discovery by other agents.
none, oauth2, oidc, api-key)text/plain (e.g., image/png, application/json)1.1. Choose the agent identity fields:
{
"name": "data-analysis-agent",
"description": "Performs statistical analysis, data visualization, and report generation on tabular datasets.",
"url": "https://agent.example.com",
"provider": {
"organization": "Example Corp",
"url": "https://example.com"
},
"version": "1.0.0"
}
1.2. Write a clear, actionable description that answers:
1.3. Set the canonical URL where the Agent Card will be served at /.well-known/agent.json.
Expected: A complete identity block with name, description, URL, provider, and version.
On failure: If the agent serves multiple domains, consider whether it should be one agent with many skills or multiple agents with focused scopes. A2A favors focused agents with clear boundaries.
2.1. Define each skill the agent can perform:
{
"skills": [
{
"id": "analyze-dataset",
"name": "Analyze Dataset",
"description": "Run descriptive statistics, correlation analysis, or hypothesis tests on a CSV dataset.",
"tags": ["statistics", "data-analysis", "csv"],
"examples": [
"Analyze the correlation between columns A and B in my dataset",
"Run a t-test comparing group 1 and group 2"
],
"inputModes": ["text/plain", "application/json"],
"outputModes": ["text/plain", "application/json", "image/png"]
},
{
"id": "generate-chart",
"name": "Generate Chart",
"description": "Create bar, line, scatter, or histogram charts from tabular data.",
"tags": ["visualization", "charts"],
"examples": [
"Create a scatter plot of height vs weight",
"Generate a histogram of the age column"
],
"inputModes": ["text/plain", "application/json"],
"outputModes": ["image/png", "image/svg+xml"]
}
]
}
2.2. For each skill, provide:
2.3. Ensure skill boundaries are clear and non-overlapping. Each task should map to exactly one skill.
Expected: A skills array where each entry has id, name, description, tags, examples, and I/O modes.
On failure: If skills overlap significantly, merge them into a single broader skill with more examples. If a skill is too broad, split it into focused sub-skills.
3.1. Define the authentication scheme based on deployment context:
No authentication (local/trusted network):
{
"authentication": {
"schemes": []
}
}
OAuth 2.0 (recommended for production):
{
"authentication": {
"schemes": ["oauth2"],
"credentials": {
"oauth2": {
"authorizationUrl": "https://auth.example.com/authorize",
"tokenUrl": "https://auth.example.com/token",
"scopes": {
"agent:invoke": "Invoke agent skills",
"agent:read": "Read task status"
}
}
}
}
}
API Key (simple shared-secret):
{
"authentication": {
"schemes": ["apiKey"],
"credentials": {
"apiKey": {
"headerName": "X-API-Key"
}
}
}
}
3.2. Choose the minimum viable authentication for the deployment environment:
noneapiKeyoauth2 or oidc3.3. Document the token/key provisioning process in the Agent Card's provider section or external documentation.
Expected: An authentication block matching the deployment security requirements.
On failure: If OAuth 2.0 infrastructure is not available, start with API key authentication and plan migration. Never deploy a public agent with none authentication.
4.1. Declare what protocol features the agent supports:
{
"capabilities": {
"streaming": true,
"pushNotifications": false,
"stateTransitionHistory": true
}
}
4.2. Set each capability flag based on implementation readiness:
true if the agent supports SSE streaming via tasks/sendSubscribe. Enables real-time progress updates for long-running tasks.true if the agent can send webhook callbacks when task state changes. Requires the agent to store and call back webhook URLs.true if the agent maintains a full history of task state transitions (submitted, working, completed, etc.). Useful for audit trails.4.3. Only set capabilities to true if the implementation fully supports them. Advertising unsupported capabilities breaks interoperability.
Expected: A capabilities object with boolean flags matching actual implementation.
On failure: If unsure whether a capability will be implemented, set it to false. Capabilities can be added in future versions. Removing a capability is a breaking change.
5.1. Assemble the complete Agent Card:
{
"name": "data-analysis-agent",
"description": "Performs statistical analysis and visualization on tabular datasets.",
"url": "https://agent.example.com",
"version": "1.0.0",
"provider": {
"organization": "Example Corp",
"url": "https://example.com"
},
"authentication": {
"schemes": ["oauth2"],
"credentials": { ... }
},
"capabilities": {
"streaming": true,
"pushNotifications": false,
"stateTransitionHistory": true
},
"skills": [ ... ],
"defaultInputModes": ["text/plain"],
"defaultOutputModes": ["text/plain"]
}
5.2. Validate the Agent Card:
/.well-known/agent.json5.3. Publish the Agent Card:
https://<agent-url>/.well-known/agent.jsonContent-Type: application/json5.4. Test discovery by fetching the card:
curl -s https://agent.example.com/.well-known/agent.json | python3 -m json.tool
Expected: A valid JSON Agent Card served at the well-known URL, parseable by any A2A client.
On failure: If JSON validation fails, use a JSON linter to identify syntax errors. If the URL is not reachable, check DNS, SSL certificates, and web server configuration. If CORS is needed, add Access-Control-Allow-Origin headers.
/.well-known/agent.json with correct Content-Typestreaming: true or pushNotifications: true without implementation causes client failures when those features are used. Be conservative.defaultInputModes and defaultOutputModes are omitted, clients may not know what content types to send.implement-a2a-server - implement the server behind the Agent Cardtest-a2a-interop - validate Agent Card conformance and interoperabilitybuild-custom-mcp-server - MCP server as alternative/complement to A2Aconfigure-mcp-server - MCP configuration patterns applicable to A2A setupnpx claudepluginhub pjt222/agent-almanacCreates and configures A2A Agent Cards—JSON discovery documents detailing agent identity, capabilities, skills, authentication schemes, and endpoints for agent-to-agent delegation.
A2A agent card JSON templates with schema validation and examples for different agent types. Use when creating agent cards, implementing A2A protocol discovery, setting up agent metadata, configuring authentication schemes, defining agent capabilities, or when user mentions agent card, agent discovery, A2A metadata, service endpoint configuration, or agent authentication setup.
Agent-to-Agent (A2A) protocol implementation patterns for Google ADK - exposing agents via A2A, consuming external agents, multi-agent communication, and protocol configuration. Use when building multi-agent systems, implementing A2A protocol, exposing agents as services, consuming remote agents, configuring agent cards, or when user mentions A2A, agent-to-agent, multi-agent collaboration, remote agents, or agent orchestration.