shield-swap: agent onboarding & lifecycle — one-verb journeys, self-provisioning credentials, packaged agent guide

.claude/skills/shield-swap/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: shield-swap
+description: Use when the user wants to trade, LP, or build on the shield_swap AMM — setting up an account, redeeming an invite, getting the airdrop, swapping privately, managing liquidity positions, or collecting winnings via the aleo_shield_swap Python SDK.
+---
+
+Read `shield-swap-sdk/AGENTS.md` (generated from the SDK — always current)
+and follow its Tier 1 lifecycle and conversation pattern. Write Python
+against the SDK; don't re-implement flows the verbs already provide, and
+don't read SDK source unless AGENTS.md genuinely lacks the answer.
+Preconditions are enforced in code — on error, read the exception message;
+it names the verb that fixes it.

.github/workflows/sdk-wheels.yml

@@ -254,11 +254,14 @@ jobs:
           pip install --find-links sdk-dist aleo-sdk
           pip install --find-links shield-swap-sdk/dist "shield-swap-sdk[async,mcp]" pytest pytest-asyncio
           cd shield-swap-sdk && python -m pytest
+      - name: AGENTS.md up to date
+        run: python shield-swap-sdk/codegen/gen_context.py --check
       # Prove the installed wheel imports on its own, away from the source tree.
       - name: Smoke test wheel
         run: |
           cd "$RUNNER_TEMP"
           python -c "import aleo_shield_swap; print('shield-swap-sdk', aleo_shield_swap.__version__)"
+          python -m aleo_shield_swap | head -1   # packaged agent guide
       - name: Upload wheel
         uses: actions/upload-artifact@v4
         with:

README.md

@@ -9,6 +9,45 @@ The SDK ships two layers:
 
 Built with snarkvm 4.8.1 (MainnetV0). For build instructions, see [sdk/Readme.md](./sdk/Readme.md).
 
+## Agent skills (trade on Shield Swap by chatting)
+
+The [`shield-swap-sdk`](./shield-swap-sdk) package ships everything an AI
+agent needs to drive the shield_swap AMM — set up an account, redeem an
+invite code, get the airdrop, make private swaps, manage liquidity, and
+collect earnings — from a single generated guide.
+
+**Any agent (Claude Code, Codex, Cursor, custom):**
+
+```bash
+pip install shield-swap-sdk
+python -m aleo_shield_swap > AGENTS.md   # drop the agent guide into your project
+```
+
+Most coding agents (Codex, Cursor, Claude Code, …) automatically read a
+repo-root `AGENTS.md`, so after that one command just chat: *"set up a
+shield-swap account and get tokens"*, *"find pools and start swapping"*.
+(Equivalently, open with "run `python -m aleo_shield_swap` and follow that
+guide", or paste the output into the agent's instructions.) The one thing
+the agent will ask you for is an invite code; everything else — key
+material, API credentials, airdrop — is handled by the SDK. Bring an existing account by exporting
+`SHIELD_SWAP_PRIVATE_KEY` (or `SHIELD_SWAP_PRIVATE_KEY_FILE`) before the
+first run — never paste a private key into the chat.
+
+**Claude Code:** working in this repo, the skill is already installed
+(`.claude/skills/shield-swap/`) — just ask. In your own project, copy the
+packaged skill in:
+
+```bash
+cp -r "$(python -c 'import aleo_shield_swap, pathlib; print(pathlib.Path(aleo_shield_swap.__file__).parent / "skills")')" .claude/skills/shield-swap
+```
+
+**MCP clients (Claude Desktop, etc.):**
+
+```bash
+pip install "shield-swap-sdk[mcp]"
+python -m aleo_shield_swap.mcp      # stdio server with the lifecycle tools
+```
+
 ## Quick Start (facade)
 
 ```python

sdk-abi/Cargo.toml

@@ -5,7 +5,7 @@
 
 [package]
 name = "aleo-abi"
-version = "0.2.1"
+version = "0.2.2"
 edition = "2024"
 license = "GPL-3.0-or-later"
 description = "Python bindings for ABI generation from Aleo bytecode (via Leo's leo-abi crate)"

sdk-abi/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "aleo-contract-abi-generator"
-version = "0.2.1"
+version = "0.2.2"
 description = "Python bindings for ABI generation from Aleo bytecode"
 readme = "README.md"
 license = {text = "GPL-3.0-or-later"}

sdk/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "aleo"
 authors = ["Konstantin Pandl", "Mike Turner", "Roman Proskuryakov"]
-version = "0.2.1"
+version = "0.2.2"
 description = "A Python sdk for zero-knowledge cryptography based on Aleo"
 edition = "2021"
 license = "GPL-3.0-or-later"

sdk/docs/source/conf.py

@@ -11,7 +11,7 @@
 copyright = '2019-2026, Provable Inc.'
 author = 'kpp'
 
-version = '0.2.1'
+version = '0.2.2'
 
 # -- General configuration
 

sdk/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "aleo-sdk"
 description = "Python SDK for building zero-knowledge apps and DeFi on the Aleo network"
-version = "0.2.1"
+version = "0.2.2"
 readme = "Readme.md"
 license = {file = "LICENSE.md"}
 authors = [