Skip to content

docs: add a2a-cli agent skill - #27

Open
msampathkumar wants to merge 3 commits into
mainfrom
skill/a2a-cli
Open

docs: add a2a-cli agent skill#27
msampathkumar wants to merge 3 commits into
mainfrom
skill/a2a-cli

Conversation

@msampathkumar

@msampathkumar msampathkumar commented Sep 1, 2026

Copy link
Copy Markdown
Member

Adds a single-file Agent Skill for the a2a CLI (SPEC §14), plus a short install README.

  • skills/a2a-cli/SKILL.md — how to use and learn the CLI, and record tasks for follow-up
  • skills/a2a-cli/README.md — install and verify

closes: #4

@msampathkumar
msampathkumar marked this pull request as ready for review September 2, 2026 23:14
@msampathkumar msampathkumar mentioned this pull request Sep 2, 2026
1 task
@yarolegovich

Copy link
Copy Markdown
Member

Thanks for kicking this off, but I think we need to iterate on this before merging.

  1. "Use when" description I think should be selling the skill more, i.e. lis more concrete triggers: use when you need to delegate to a specialized agent, fetch an agent card, send a message to an agent at a URL, check or cancel an A2A task.

  2. The core concepts like tasks and context are not introduced. I'd add a short bulleted statements list like:

* An A2A interaction starts with a client Message.
* The server responds with either a Message or a Task.
* Task represents a long running work, that can be cancelled or interrupted (eg. auth or user input required).
Server keeps track of Tasks and messages which relate to Tasks, while messages not related to a task are not stored.
* Tasks have server generated task and context-id. 
* Task transition to an interrupted state when user input or auth credentials are required to proceed.
* A Message carrying a task-id can be used to resume a task in the interrupted state.
* A Message carrying a context-id allows the server to link it to previous interactions this client had. A Task created in response to such a Message will be created in the same context.
* Many Tasks can exist within a single Context, but a Task can't be referenced with a reference to the different context, i.e. ---task-id and --context-id must agree.
  1. Too much focus on less important things: "Try it with a throwaway echo agent", "Exit code and task state answer different questions", "Recording requests and responses". Models are smart enough to come up with workflows and connect to real agents they need to connect from the start, I don't think these sections add value.

  2. There are no command examples or example flows. Check the internal CLI readme, it's important for a skill to have something like this: https://github.com/a2aproject/a2a-cli/tree/main/internal#send---send-a-message Just not focused on a single command, but more like walking through a task lifecycle.

  3. You're basically instructing to always read the SPEC.

  • Global flags and the output schema are defined in the a2a-cli specification (SPEC.md) — consult it rather than guessing.

It has too much information and it's now frozen, so the real cli mechanics will inevitably drift. Let's focus on cli help for flag and command discovery.

Let's check the prior CLI skill art:

Note the focus on the core workflow, commands to run and flags to pass.

@msampathkumar

Copy link
Copy Markdown
Member Author

Great points! Updated the PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feat]: create agent skill

2 participants