Add stellar skill command for AI agents

[fnando]

What

Adds a new stellar skill command that prints a Markdown guide teaching AI coding agents how to use the CLI idiomatically. The content lives in an embedded SKILL.md and covers: setting default network/identity with stellar network use / stellar keys use (instead of repeating --network / --source), using contract aliases with --alias and --id <alias> (instead of stashing contract ids in env vars), building/deploying from source, discovering a contract's interface, read-only calls and output parsing, the TTL/archival lifecycle, and running a local network.

Why

AI agents increasingly drive the CLI but don't know its ergonomic conventions, so they fall into anti-patterns — saving raw contract ids into env vars, passing RPC URLs on every call, pasting secret keys. Inspired by groundhog --skill, this gives agents (and users) a single command whose output can be read or pasted into agent instructions. Ideas were adapted from stellar/stellar-dev-skill.

[Copilot]

🟡 Changes recommended

The guide contains invalid or inaccurate instructions about alias removal, identifier flags, archival behavior, and alias listing.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds stellar skill, which prints an embedded Markdown guide for AI agents.

Changes:

• Registers and documents the new command.
• Adds guidance covering networks, identities, contracts, TTL, and local environments.
• Adds an integration test for key guide content.

File summaries

File	Description
FULL_HELP_DOCS.md	Documents stellar skill.
cmd/soroban-cli/src/commands/skill/SKILL.md	Provides the embedded agent guide.
cmd/soroban-cli/src/commands/skill/mod.rs	Prints the guide.
cmd/soroban-cli/src/commands/mod.rs	Registers and dispatches the command.
cmd/crates/soroban-test/tests/it/skill.rs	Tests command output.
cmd/crates/soroban-test/tests/it/main.rs	Registers the integration test module.

Review details

Suppressed comments (1)

cmd/soroban-cli/src/commands/skill/SKILL.md:118

• stellar contract alias ls does not show only the current network. Its implementation collects stored aliases across every network passphrase and prints them grouped by network, consistent with the generated help's “List all aliases”; this description could lead an agent to miss aliases for other networks in the output.

- `stellar contract alias ls` — contract aliases for the current network

• Files reviewed: 6/6 changed files
• Comments generated: 3
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

The guide contains an invalid alias command and incomplete or misleading project and local-network workflows.

Review details

Suppressed comments (5)

Previously missed (2) — in code that hasn't changed since the last review.

cmd/soroban-cli/src/commands/skill/SKILL.md:67

• After stellar contract init my-project, the shell remains in the parent directory. Running contract build exactly as shown therefore does not build the generated project unless that parent is coincidentally another Cargo workspace; the sequence should enter my-project first.

This issue also appears on line 71 of the same file.
cmd/soroban-cli/src/commands/skill/SKILL.md:106

• Starting the container does not change the CLI's configured network; start.rs:63-71 only launches the runner. Because this guide previously selects testnet, subsequent contract commands will still target testnet unless the agent also runs stellar network use local. Include that step in the local-network workflow.

cmd/soroban-cli/src/commands/skill/SKILL.md:59

• rm is not a valid contract alias subcommand: the enum exposes remove (also shown in FULL_HELP_DOCS.md:189). Agents following this guide will get an invalid-subcommand error when trying to delete an alias.

- Manage aliases: `stellar contract alias ls`, `stellar contract alias add`, `stellar contract alias rm`

cmd/soroban-cli/src/commands/skill/SKILL.md:84

• --id is not universally a short form of --contract-id: for example, contract invoke declares only --id (invoke.rs:51-53), while contract info declares --contract-id with id as an alias. Describing them as interchangeable across commands can make agents generate unsupported flags.

`--id` accepts a contract id or an alias and works across contract commands (it's the short form of `--contract-id`) — prefer it everywhere.

cmd/soroban-cli/src/commands/skill/SKILL.md:71

• This command follows the freshly scaffolded project, whose template contract has no __constructor (src/utils/contract-template/src/lib.rs:16-20). The deploy path ignores trailing arguments when no constructor exists, so --admin alice is not applied even though the guide presents this as a runnable sequence; remove the argument here or explicitly state that the contract must first define such a constructor.

    stellar contract deploy --alias counter -- --admin alice

• Files reviewed: 6/6 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[leighmcculloch]

This line clobbers the longer doc comment on the Cmd I believe.