Add wallet skill: use the Stellar CLI as a wallet

[aristidesstaffieri]

Summary

Adds a wallet skill that documents using the Stellar CLI (stellar) as a wallet by composing existing commands — key management, funding, balances, account readiness, trustlines, value transfer, the stellar token client, and transaction diagnosis — with structured JSON output and a branchable error contract.

Commands were verified against stellar-cli 25.1.0 on testnet. Some of the surface this skill documents is still gated on in-flight CLI work and is called out as forthcoming rather than presented as shipped — see In-progress dependencies below.

What's in this PR

• skills/wallet/SKILL.md — entry point: wallet-operation → command map, prerequisites (install, RPC/relayer config), and the {status, result, error} output/error contract.
• skills/wallet/keys.md — key lifecycle, private-key security, funding, and key selection.
• skills/wallet/accounts-and-tx.md — balances/readiness, trustlines, tx diagnosis, sign + submit, account draining, plus an inline Stellar account & transaction model (reserves, sequence numbers/idempotency, fees & fee-bumps, tx lifecycle).
• skills/wallet/tokens.md — the stellar token client (SEP-41 / SAC), trusted token lists, error remediation, and asset anatomy.
• site/src/data/skills.ts — new "Wallets" filter category and a SKILL_CARD_SOURCES entry so the skill renders on skills.stellar.org and in llms.txt.

In-progress dependencies

This skill documents CLI surface that is not yet fully shipped. These are flagged as forthcoming in the content so readers aren't misled:

• stellar token client (stellar-cli#2620) — the typed SEP-41/SAC client that tokens.md and several examples depend on (e.g. stellar token balance noted # (via #2620)).
• Structured JSON output + {status, result, error} receipt (stellar-cli#2622) — the output/error contract in SKILL.md.
• Relayer submission (stellar-cli#2623) — the optional relayer config / fee-bump-on-submit path.
• DeFi skills — the "Working with Soroban protocols" section links to ../defi/SKILL.md, which does not exist in this repo yet. The link is intentional forward-routing to that forthcoming skill package.

Test plan

• Commands verified against stellar-cli 25.1.0 on testnet
• Fixed a deprecated command surfaced during verification (stellar contract asset id → stellar contract id asset)
• Confirm the skill card renders under the new "Wallets" filter on the site preview
• CI green

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://stellar.github.io/stellar-dev-skill/pr/pr-49/
Built to branch gh-pages at 2026-07-09 15:38 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[Copilot]

Pull request overview

Adds a new “wallet” skill to the Stellar Skills collection, documenting how to use the stellar CLI for key management, account readiness, transfers, trustlines, token operations, and transaction diagnosis, and surfaces it on the skills landing page under a new “Wallets” filter.

Changes:

• Introduces the skills/wallet skill overview plus supporting docs for keys, accounts/transactions, and tokens.
• Adds a new “Wallets” category/filter and a “CLI Wallet” card entry to the site skills registry.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
skills/wallet/SKILL.md	Adds the wallet skill entrypoint, prerequisites, structured JSON guidance, and navigation to the wallet subtopics.
skills/wallet/keys.md	Documents CLI key lifecycle operations and private-key safety guidance.
skills/wallet/accounts-and-tx.md	Documents account readiness, reserves/fees/sequence mechanics, trustlines, building/signing/sending, and diagnosis flows.
skills/wallet/tokens.md	Documents stellar token usage: target resolution, common subcommands, examples, and error remediation.
site/src/data/skills.ts	Registers the new “Wallets” filter and adds the “CLI Wallet” card entry pointing at the new skill.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[oceans404]

I stress tested this skill by giving fresh agents (no Stellar context) only the SKILL.md URL, real wallet tasks, and --help, on testnet with CLI 26.0.0. Setting aside the sections gated on unshipped CLI work (#2620, #2622, #2623), here is what agents actually hit, ranked by impact. All flows completed, but every agent had to escape the doc into --help to do it.

accounts-and-tx.md

1. Amount units. tx new payment --amount is stroops, but the examples (--amount 100, --amount 10) read as human units, and tokens.md primes "pass human units." An agent transferred 100 stroops thinking 100 tokens. It succeeds silently, off by 10^7. State the unit next to every --amount and use a realistic value like --amount 100000000 # 10 XLM.
2. Add a tx new create-account example. Paying a non-existent account with tx new payment fails on-chain with NoDestination, and create-account (the actual fix, --starting-balance, also stroops) has no example anywhere. This is the most common onboarding flow.
3. Drop --output json from the tx new payment, tx new account-merge, and tx send examples. The flag doesn't exist on those commands (error: unexpected argument '--output' found). Also worth noting: tx new prints nothing to stdout on success (hash on stderr only), so show what success looks like.
4. Name the real errors. Failures agents saw are Rust debug dumps like TxFailed(VecM([OpInner(Payment(NoTrust))])), and the names NoTrust, NoDestination, Underfunded, HasSubEntries, InvalidLimit appear nowhere in the doc. Agents recovered only where prose sat next to the example (InvalidLimit gives zero hint that "balance must be 0"; Underfunded never connects to "reserve"). A small error-name table would fix this.
5. Readiness details. The checklist says "decimal balance" but ledger entry fetch account returns raw stroops. A missing account returns success with empty entries, not an error. Failed txs still charge the fee.

keys.md

6. Document the stdin pipe for keys add. echo "$SEED" | stellar keys add <name> --secure-store works with no TTY. The current "reads the secret from an interactive prompt" wording made an agent conclude import can't be automated.
7. keys rm needs --force non-interactively. Bare keys rm <name> with no TTY fails with removal cancelled by user. --force isn't mentioned.
8. Fix the secure-store claims. It's seed-phrase-only (no S-key import, per --help), and secure-store keys can never be exported (Secure Store does not reveal secret key). Worth a one-way-door callout since the doc recommends it.
9. Small fixes. The pubnet note implies tx new payment can fund a new address (it can't, see Add dedicated ZK skill for Protocol 25 X-Ray #2). keys ls --long prints file paths, not addresses.

SKILL.md

10. Scope habit Fix README installation commands: correct org name and plugin syntax #1. "Pass --output json on any command that supports it" holds only for reads (ledger entry fetch, tx fetch, network health) in 26.0.0. Say that, since agents attach it everywhere and their first command errors.
11. Network section. Testnet ships preconfigured, so network add testnet re-adds a built-in, and "the default is the public testnet RPC" overstates it (no network selected = error). Say "select the built-in testnet with -n testnet or network use testnet."

tokens.md

12. Make the invoke bridge actionable until token ships. "Thin wrapper over contract invoke" is true but unteachable as written. Two lines close it: discover functions with stellar contract invoke --id <SAC> --network testnet -- --help, and raw invoke amounts are base units (call decimals first). Without the second, the human-units framing causes the same silent 10^7 error as Fix README installation commands: correct org name and plugin syntax #1. (contract id asset and contract asset deploy worked perfectly as documented.)
13. Small fixes. The publishing-asset-information link 404s. Transferring a SAC token to its issuer emits Burn and the issuer balance stays at the i64::MAX sentinel, so destination-balance verification reads as failure. A pointer to ../assets/SKILL.md for "how do I get an issued asset in the first place" would help; agents needed outside knowledge for that.

What held up well: the file structure and relative links (every agent navigated them cold), the keys lifecycle, the tx fetch result|fee|events family, --build-only and the tx sign | tx send pipe, drain ordering, and the reserve/fee/idempotency facts, which we verified on-chain (resending the same signed envelope really does return the identical receipt). The "discover before you guess" habit is what carried every agent, so the doc's bones are right.

[aristidesstaffieri]

I stress tested this skill by giving fresh agents (no Stellar context) only the SKILL.md URL, real wallet tasks, and --help, on testnet with CLI 26.0.0. Setting aside the sections gated on unshipped CLI work (#2620, #2622, #2623), here is what agents actually hit, ranked by impact. All flows completed, but every agent had to escape the doc into --help to do it.

accounts-and-tx.md

1. Amount units. tx new payment --amount is stroops, but the examples (--amount 100, --amount 10) read as human units, and tokens.md primes "pass human units." An agent transferred 100 stroops thinking 100 tokens. It succeeds silently, off by 10^7. State the unit next to every --amount and use a realistic value like --amount 100000000 # 10 XLM.
2. Add a tx new create-account example. Paying a non-existent account with tx new payment fails on-chain with NoDestination, and create-account (the actual fix, --starting-balance, also stroops) has no example anywhere. This is the most common onboarding flow.
3. Drop --output json from the tx new payment, tx new account-merge, and tx send examples. The flag doesn't exist on those commands (error: unexpected argument '--output' found). Also worth noting: tx new prints nothing to stdout on success (hash on stderr only), so show what success looks like.
4. Name the real errors. Failures agents saw are Rust debug dumps like TxFailed(VecM([OpInner(Payment(NoTrust))])), and the names NoTrust, NoDestination, Underfunded, HasSubEntries, InvalidLimit appear nowhere in the doc. Agents recovered only where prose sat next to the example (InvalidLimit gives zero hint that "balance must be 0"; Underfunded never connects to "reserve"). A small error-name table would fix this.
5. Readiness details. The checklist says "decimal balance" but ledger entry fetch account returns raw stroops. A missing account returns success with empty entries, not an error. Failed txs still charge the fee.

keys.md

6. Document the stdin pipe for keys add. echo "$SEED" | stellar keys add <name> --secure-store works with no TTY. The current "reads the secret from an interactive prompt" wording made an agent conclude import can't be automated.
7. keys rm needs --force non-interactively. Bare keys rm <name> with no TTY fails with removal cancelled by user. --force isn't mentioned.
8. Fix the secure-store claims. It's seed-phrase-only (no S-key import, per --help), and secure-store keys can never be exported (Secure Store does not reveal secret key). Worth a one-way-door callout since the doc recommends it.
9. Small fixes. The pubnet note implies tx new payment can fund a new address (it can't, see Add dedicated ZK skill for Protocol 25 X-Ray #2). keys ls --long prints file paths, not addresses.

SKILL.md

10. Scope habit Fix README installation commands: correct org name and plugin syntax #1. "Pass --output json on any command that supports it" holds only for reads (ledger entry fetch, tx fetch, network health) in 26.0.0. Say that, since agents attach it everywhere and their first command errors.
11. Network section. Testnet ships preconfigured, so network add testnet re-adds a built-in, and "the default is the public testnet RPC" overstates it (no network selected = error). Say "select the built-in testnet with -n testnet or network use testnet."

tokens.md

12. Make the invoke bridge actionable until token ships. "Thin wrapper over contract invoke" is true but unteachable as written. Two lines close it: discover functions with stellar contract invoke --id <SAC> --network testnet -- --help, and raw invoke amounts are base units (call decimals first). Without the second, the human-units framing causes the same silent 10^7 error as Fix README installation commands: correct org name and plugin syntax #1. (contract id asset and contract asset deploy worked perfectly as documented.)
13. Small fixes. The publishing-asset-information link 404s. Transferring a SAC token to its issuer emits Burn and the issuer balance stays at the i64::MAX sentinel, so destination-balance verification reads as failure. A pointer to ../assets/SKILL.md for "how do I get an issued asset in the first place" would help; agents needed outside knowledge for that.

What held up well: the file structure and relative links (every agent navigated them cold), the keys lifecycle, the tx fetch result|fee|events family, --build-only and the tx sign | tx send pipe, drain ordering, and the reserve/fee/idempotency facts, which we verified on-chain (resending the same signed envelope really does return the identical receipt). The "discover before you guess" habit is what carried every agent, so the doc's bones are right.

@oceans404 thanks for going through this in detail. I've fixed most of these issues in 2f3dd63

for 3 and 10, the doc targets a future version of the CLI where the assumption is that both the token command and the structured outputs have landed upstream. Given that, it seems like we shouldn't make the changes listed in those lien items. Does that sound right to you?