Document the AGENTS.md generated by `stellar contract init` and an agent workflow using the CLI

[briwylde08]

stellar contract init now generates an AGENTS.md in every new project (merged August 2026), and the CLI's --output json flags are in the manual. Neither is explained anywhere: developers using AI coding agents find both by accident, and the CLI guides describe only the human-facing flow.

Please add:

• a page on the generated AGENTS.md: what it contains, how to customise it, how agents pick it up;
• one end-to-end agent workflow (init → build → deploy → invoke) using the existing --output json flags, linked from the CLI manual.

Surfaced by Frontier Lab's ecosystem crawl.

[kaankacar]

/triage

[stellar-triage-bot]

Working this because @ElliotFriend assigned it to @kaankacar and @kaankacar asked with /triage.

I am checking the claims against the stellar-cli source. I will report back here.

[stellar-triage-bot]

Working this because @ElliotFriend assigned it to @kaankacar and @kaankacar asked with /triage.

@kaankacar @ElliotFriend, a decision is needed: #2869 already covers most of this, so what should the bot build for the rest?

What I checked (stellar-cli v28.1.0):

• stellar contract init does write AGENTS.md (Generate AGENTS.md when running stellar contract init stellar-cli#2687, first shipped in v28.0.0).
• Create Stellar CLI for Agents docs section ahead of developer preview #2869 (merged 2026-09-30) added the "Stellar CLI for Agents" section. It mentions AGENTS.md in two lines only. It does not say what the file contains or how to edit it.
• The issue's premise is wrong: init, build, deploy and invoke have no --output json flag. A global flag is only planned (Structured output & CLI API hardening (output + errors + --describe) stellar-cli#2622, open, no assignee).
• Today deploy prints the contract ID on stdout. invoke prints the return value on stdout as JSON.
• The CLI manual page is generated from stellar-cli. A link from it needs an upstream change. The sidebar already lists the agent section under the manual.

Options:

1. Add an AGENTS.md section to the agent Skills page, plus one init → build → deploy → invoke guide that reads today's stdout. No --output json claim.
2. Add the AGENTS.md section only. Wait for Structured output & CLI API hardening (output + errors + --describe) stellar-cli#2622 before writing the workflow guide.
3. Close this issue as covered by Create Stellar CLI for Agents docs section ahead of developer preview #2869.

I will build the option you pick.

[kaankacar]

Let's go with Option no. 1 and see what happens. Although I'm wondering: is there a more relevant page/place than Skills? Just something to think about.

[stellar-triage-bot]

🤖 Automated triage bot, acting for @kaankacar.

Back on this because @kaankacar replied.

Option 1 is in #2892.

On placement: I did not use the Skills page. AGENTS.md describes a project. stellar skill describes the CLI. So both parts are in one new guide, "Build and deploy a contract", in the Agent Cookbook. Its step 1 is init, the step that writes AGENTS.md.

• The Skills page and the agent landing page link to the guide's AGENTS.md section.
• The guide reads plain stdout. It makes no --output json claim.

If you want AGENTS.md on its own reference page, tell me and I will move it.