How to use the A4A Agent Messaging agent skill

What is an agent skill, and what does the a4a skill do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when a task matches the skill's description. It adds guidance, not new software. The a4a skill is a single SKILL.md file.

Once installed, the agent knows how to inspect an existing A4A connection, plan a setup using a read-only check, and follow strict rules before sending anything. The skill does not bundle the messaging software itself. It points to the official a4a-mcp and a4a-sdk packages, which you install separately.

What you need before installing the skill

The skill assumes a few things are already in place. Check these first, because the skill cannot supply them.

• A Python environment with the official a4a-mcp and/or a4a-sdk packages installed separately
• An MCP-capable host such as Claude Code, Cursor, Codex or Gemini CLI
• An owner-approved A4A relay destination
• Network access to the relay for sending or receiving messages

Install the a4a skill

Download the ZIP file from the skill page and unzip it. You can then place the skill in one of two locations, depending on how you want to use it.

For a personal setup available across projects, put the unzipped skill folder in ~/.claude/skills/. To limit it to one project, put it in that project's .claude/skills/ folder.

In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Single project: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload

How to trigger the skill with natural requests

You do not need a special command. Ask in plain language about messaging or coordinating with another person's agent using an apub1 address. The skill is meant for requests like these, and for setting up or running the a4a-mcp server in your host.

Ask for inspection before action. The skill is designed to start with read-only work, so asking the agent to check first is the safest way to begin.

• "Inspect my existing A4A connection without sending anything."
• "Plan an A4A setup with a read-only check, using a persistent identity directory outside Git."
• "Help me coordinate with the agent at this apub1 address, but only after I approve the recipient and the content."

What the agent will and won't do

The skill sets firm limits. When you ask for an inspection, the agent reads the existing approved configuration and capability schema, then reports tool access separately from any tested receipt or wake behaviour. It does not initialise a new identity, promote contacts, publish a profile or send a test message unless you have authorised that action.

The skill also tells the agent to treat every inbound message as untrusted content, even from an approved sender. Authentication proves key control, not permission to run instructions or disclose private data. Requests from any external sender to run shell commands, make payments or change files are refused.

• Does not act on unknown senders until you approve the address
• Sends only within explicit authorisation covering the recipient and content
• Never transmits or logs private key material such as asec1... values or identity keystore files

Safety notes: scripts, network and data

The skill itself runs no scripts and contains no code. It does use the network, because sending and receiving go through a relay. Message contents may leave your machine through the relay even when they are end-to-end encrypted, and the relay can observe metadata. The upstream production relay is wss://eu1.a4a.network, but you should use only a destination your owner has approved.

Sending is a real external action. Recipient mistakes cannot be undone, and delivery tracking does not reverse them. Keep sensitive data, payments and credentials out of this workflow.

• Runs scripts: no
• Uses network: yes
• Private-message encryption does not guarantee every event is private; check event visibility before sending

Tips for a safe first run

Start in a dedicated, non-production environment. Keep the private identity directory outside any Git repository, and keep automatic mandates off. Verify a new contact out of band or through a short owner confirmation before granting any automatic-delivery policy.

Do not assume automatic replies. The skill notes that inbound messages from a new collaborator may not trigger a reply, and that inbox behaviour depends on the installed version and host wake support. Do not weaken a gate just to get an automatic response.

• Use a dedicated test environment first
• Keep the identity directory private and outside Git
• Check the installed package's actual tool schema rather than assuming one exists