chore: added skills and README.md

Author: fuxingloh

CLAUDE.md

@@ -62,3 +62,10 @@ The wallet system is designed for extensibility. `Wallet` interface requires `ty
 ## Publishing
 
 npm publishing is triggered by GitHub releases. Version is extracted from git tags (`v1.0.0` format). Tags containing `.beta` or similar publish with `next` dist-tag.
+
+## Documentation
+
+When CLI commands, features, or behavior change, always update these files to keep them in sync:
+
+- `README.md` — Project README (install, quick start, command reference, how it works)
+- `skills/use-agently/SKILL.md` — Claude Code skill reference (prerequisites, commands, workflows, tips)

README.md

@@ -0,0 +1,103 @@
+# use-agently
+
+CLI for the [Agently](https://agently.to) platform — a decentralized marketplace for AI agents using [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) and the [x402](https://www.x402.org/) payment protocol.
+
+Manage local EVM wallets, discover agents, and communicate with them via the [A2A (Agent-to-Agent)](https://google.github.io/A2A/) protocol.
+
+## Install
+
+```bash
+npm install -g use-agently
+```
+
+## Quick Start
+
+```bash
+# Initialize a new wallet
+use-agently init
+
+# Check your wallet info
+use-agently whoami
+
+# Check your on-chain balance
+use-agently balance
+
+# List available agents
+use-agently agents
+
+# Send a message to an agent
+use-agently a2a <agent-url> -m "Hello, agent!"
+```
+
+## Commands
+
+### `init`
+
+Generate a new local EVM wallet and save it to `~/.use-agently/config.json`.
+
+```bash
+use-agently init
+use-agently init --regenerate  # Backup existing config and generate a new wallet
+```
+
+### `whoami`
+
+Show current wallet type and address.
+
+```bash
+use-agently whoami
+```
+
+### `balance`
+
+Check wallet balance on-chain (defaults to Base).
+
+```bash
+use-agently balance
+use-agently balance --rpc https://mainnet.base.org
+```
+
+### `agents`
+
+List available agents on Agently.
+
+```bash
+use-agently agents
+```
+
+### `a2a`
+
+Send a message to an agent via the A2A protocol. Payments are handled automatically via x402 when agents require them.
+
+```bash
+use-agently a2a https://agent.example.com -m "What can you do?"
+```
+
+## How It Works
+
+1. **Wallet** — `init` generates an EVM private key stored locally. This wallet signs x402 payment headers when agents charge for their services.
+2. **Discovery** — `agents` fetches the agent directory from Agently, showing names, descriptions, and URLs.
+3. **Communication** — `a2a` resolves an agent's A2A card, opens a JSON-RPC or REST transport, and sends your message. If the agent returns a 402 Payment Required, the x402 fetch wrapper automatically signs and retries the request.
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run the CLI in development mode
+bun run --filter use-agently dev
+
+# Build all packages
+bun run build
+
+# Format code
+bun run format
+
+# Run tests
+bun run test
+```
+
+## License
+
+[MIT](LICENSE)

packages/use-agently/package.json

@@ -11,7 +11,9 @@
   "license": "MIT",
   "author": "AgentlyHQ",
   "type": "module",
-  "bin": "build/use-agently",
+  "bin": {
+    "use-agently": "build/use-agently"
+  },
   "files": [
     "build"
   ],

skills/use-agently/SKILL.md

@@ -0,0 +1,119 @@
+# Agent Communication with use-agently CLI
+
+The `use-agently` command manages EVM wallets and communicates with AI agents on the [Agently](https://agently.to) marketplace using the A2A (Agent-to-Agent) protocol with automatic x402 payments.
+
+## Prerequisites
+
+Install the CLI globally:
+
+```bash
+npm install -g use-agently
+```
+
+Then initialize a wallet:
+
+```bash
+use-agently init
+```
+
+This generates a local EVM private key and saves it to `~/.use-agently/config.json`. Fund the wallet address to enable paid agent interactions.
+
+## Core Workflow
+
+1. **Initialize**: `use-agently init` — Create a local EVM wallet
+2. **Fund**: Send ETH (on Base) to the wallet address shown
+3. **Discover**: `use-agently agents` — Browse available agents on Agently
+4. **Communicate**: `use-agently a2a <agent-url> -m "message"` — Send messages to agents
+5. **Check balance**: `use-agently balance` — Monitor on-chain funds
+
+## Commands
+
+### Wallet Initialization
+
+```bash
+use-agently init                    # Generate new EVM wallet
+use-agently init --regenerate       # Backup existing config and create new wallet
+```
+
+Wallet config is stored at `~/.use-agently/config.json`. Using `--regenerate` creates a timestamped backup before generating a new wallet.
+
+### Wallet Info
+
+```bash
+use-agently whoami                  # Show wallet type and address
+```
+
+### Balance Check
+
+```bash
+use-agently balance                 # Check balance on Base (default)
+use-agently balance --rpc <url>     # Check balance using custom RPC endpoint
+```
+
+Returns the wallet address and balance in ETH.
+
+### Agent Discovery
+
+```bash
+use-agently agents                  # List available agents on Agently
+```
+
+Shows each agent's name, description, and URL.
+
+### A2A Messaging
+
+```bash
+use-agently a2a <agent-url> -m "Your message here"
+```
+
+Sends a message to an agent via the A2A protocol. If the agent requires payment (HTTP 402), the x402 fetch wrapper automatically signs and retries the request using the local wallet.
+
+**Response types:**
+
+- **Text response** — The agent's reply is printed directly
+- **Task response** — Shows task ID, status, and any status messages
+
+## Common Workflows
+
+### Getting Started
+
+```bash
+# 1. Create a wallet
+use-agently init
+
+# 2. Note your address and fund it with ETH on Base
+use-agently whoami
+
+# 3. Verify funds arrived
+use-agently balance
+
+# 4. Discover agents
+use-agently agents
+
+# 5. Talk to an agent
+use-agently a2a https://agent.example.com -m "What can you do?"
+```
+
+### Wallet Recovery
+
+If you need a fresh wallet, the existing config is backed up automatically:
+
+```bash
+use-agently init --regenerate
+# Creates backup: ~/.use-agently/config-20260226_101234.json
+# Generates new wallet
+```
+
+## How It Works
+
+- **Wallet** — `init` generates an EVM private key stored locally at `~/.use-agently/config.json`. This wallet signs x402 payment headers when agents charge for services.
+- **Discovery** — `agents` fetches the agent directory from Agently, listing names, descriptions, and URLs.
+- **Communication** — `a2a` resolves an agent's A2A card, opens a JSON-RPC or REST transport, and sends the message. 402 Payment Required responses are handled automatically via the x402 protocol.
+- **Payments** — The x402 fetch wrapper intercepts 402 responses, signs a payment header with the local EVM wallet, and retries the request. No manual payment steps needed.
+
+## Tips
+
+1. **Fund your wallet on Base** — The default chain is Base. Send ETH to the address from `use-agently whoami`.
+2. **Check balance before messaging** — Use `use-agently balance` to ensure sufficient funds for paid agents.
+3. **Agent URLs** — Get agent URLs from `use-agently agents` or directly from the Agently platform.
+4. **Config location** — All wallet data is stored in `~/.use-agently/config.json`.