Skip to content

Commit ae6afb8

Browse files
JamesLawtonJamesLawton
authored
Merge pull request #70 from 0xPolygon/feat/skill-refactor
feat: refactor skills into sub-skill files by use-case
2 parents 73b9283 + 82fbf3f commit ae6afb8

15 files changed

Lines changed: 1592 additions & 663 deletions

File tree

‎.husky/pre-commit‎

Lines changed: 32 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,48 @@
11
# =============================================================================
22
# SKILL.md sync
33
#
4-
# skills/SKILL.md is the single source of truth for the agent skill definition.
5-
# It must be kept in sync with two other locations:
4+
# skills/ is the single source of truth for all agent skill definitions.
5+
# The entire directory is synced to two locations on every commit:
66
#
7-
# packages/connector-ui/public/SKILL.md
8-
# Served at https://agentconnect.polygon.technology/SKILL.md — this is the
9-
# URL that agents fetch at runtime (referenced in the dashboard's use-case
10-
# commands as SKILL_URL). Must match the root exactly.
7+
# packages/connector-ui/public/skills/
8+
# Served at https://agentconnect.polygon.technology/skills/ — agents fetch
9+
# skill files at runtime from this URL.
1110
#
12-
# packages/polygon-agent-cli/skills/SKILL.md
13-
# Bundled inside the published npm package so the skill is available
14-
# locally after install. The `name` field is rewritten from
11+
# packages/polygon-agent-cli/skills/
12+
# Bundled inside the published npm package so skills are available
13+
# locally after install. The `name` field in SKILL.md is rewritten from
1514
# `polygon-agent-kit` (monorepo name) to `polygon-agent-cli` (the
1615
# installed skill identifier) to match what Claude Code registers.
1716
#
1817
# DO NOT edit the package copies directly — they will be overwritten.
19-
# Always edit skills/SKILL.md at the repo root.
18+
# Always edit files under skills/ at the repo root.
2019
# =============================================================================
2120
node -e "
2221
const fs = require('fs');
23-
const src = fs.readFileSync('skills/SKILL.md', 'utf8');
24-
fs.writeFileSync('packages/connector-ui/public/SKILL.md', src);
25-
fs.writeFileSync('packages/polygon-agent-cli/skills/SKILL.md', src.replace('name: polygon-agent-kit', 'name: polygon-agent-cli'));
22+
const path = require('path');
23+
24+
function copyDir(src, dest) {
25+
fs.mkdirSync(dest, { recursive: true });
26+
for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
27+
const srcPath = path.join(src, entry.name);
28+
const destPath = path.join(dest, entry.name);
29+
if (entry.isDirectory()) {
30+
copyDir(srcPath, destPath);
31+
} else {
32+
fs.copyFileSync(srcPath, destPath);
33+
}
34+
}
35+
}
36+
37+
// Sync to connector-ui (verbatim)
38+
copyDir('skills', 'packages/connector-ui/public/skills');
39+
40+
// Sync to CLI package (rewrite name field in root SKILL.md only)
41+
copyDir('skills', 'packages/polygon-agent-cli/skills');
42+
const cliSkill = path.join('packages/polygon-agent-cli/skills/SKILL.md');
43+
fs.writeFileSync(cliSkill, fs.readFileSync(cliSkill, 'utf8').replace('name: polygon-agent-kit', 'name: polygon-agent-cli'));
2644
"
27-
git add packages/connector-ui/public/SKILL.md packages/polygon-agent-cli/skills/SKILL.md
45+
git add packages/connector-ui/public/skills packages/polygon-agent-cli/skills
2846

2947
pnpm exec lint-staged
3048
pnpm run typecheck

‎packages/connector-ui/public/skills/SKILL.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
---
2+
name: polygon-agent-kit
3+
description: Complete Polygon agent toolkit for on-chain operations on Polygon. Use this skill whenever helping an agent set up a wallet, check balances, send or swap tokens, bridge assets, deposit to earn yield, register on-chain identity, submit or query reputation/feedback, or make x402 micropayments. Covers the full lifecycle: Sequence smart contract wallets, Trails DeFi actions, ERC-8004 identity + reputation, x402 payments. Single CLI entry point (`polygon-agent`), AES-256-GCM encrypted storage.
4+
---
5+
6+
# Polygon Agentic CLI
7+
8+
## Prerequisites
9+
- Node.js 20+
10+
- Install globally: `npm install -g github:0xPolygon/polygon-agent-kit` (reinstall to update)
11+
- Entry point: `polygon-agent <command>`
12+
- Storage: `~/.polygon-agent/` (AES-256-GCM encrypted)
13+
14+
## Architecture
15+
16+
| Wallet | Created by | Purpose | Fund? |
17+
|--------|-----------|---------|-------|
18+
| EOA | `setup` | Auth with Sequence Builder | NO |
19+
| Ecosystem Wallet | `wallet create` | Primary spending wallet | YES |
20+
21+
## Environment Variables
22+
23+
### Access key — auto-loaded, no export needed
24+
25+
After `setup` runs, the access key is stored in `~/.polygon-agent/builder.json`. The CLI bootstraps it into `SEQUENCE_PROJECT_ACCESS_KEY` and `SEQUENCE_INDEXER_ACCESS_KEY` automatically on every invocation. Trails commands additionally fall back through `session.projectAccessKey` → `SEQUENCE_PROJECT_ACCESS_KEY`, so `TRAILS_API_KEY` also does not need to be exported manually.
26+
27+
**In a fresh agent session with no environment variables set**, simply run commands — the CLI reads credentials from disk. No `export` step is required between phases.
28+
29+
Only set these manually to override the stored value (e.g. to point at a different project):
30+
```bash
31+
export SEQUENCE_PROJECT_ACCESS_KEY=<override-key>
32+
```
33+
34+
### Optional overrides
35+
| Variable | Default |
36+
|----------|---------|
37+
| `SEQUENCE_ECOSYSTEM_CONNECTOR_URL` | `https://agentconnect.polygon.technology` |
38+
| `SEQUENCE_DAPP_ORIGIN` | Same as connector URL origin |
39+
| `TRAILS_TOKEN_MAP_JSON` | Token-directory lookup |
40+
| `POLYGON_AGENT_DEBUG_FETCH` | Off — logs HTTP to `~/.polygon-agent/fetch-debug.log` |
41+
| `POLYGON_AGENT_DEBUG_FEE` | Off — dumps fee options to stderr |
42+
43+
## Complete Setup Flow
44+
45+
```bash
46+
# Step 1: Setup (creates EOA + Sequence project, stores access key to disk)
47+
polygon-agent setup --name "MyAgent"
48+
# → saves privateKey (not shown again), eoaAddress, accessKey to ~/.polygon-agent/builder.json
49+
# → all subsequent commands auto-load the access key from disk — no export needed
50+
51+
# Step 2: Create ecosystem wallet (opens browser, waits for 6-digit code)
52+
polygon-agent wallet create --usdc-limit 100 --native-limit 5
53+
# → opens https://agentconnect.polygon.technology/link?rid=<rid>&...
54+
# → user approves in browser, browser shows a 6-digit code
55+
# → enter the 6-digit code in the terminal when prompted
56+
# → session saved to ~/.polygon-agent/wallets/main.json
57+
58+
# Step 3: Fund wallet
59+
polygon-agent fund
60+
# → reads walletAddress from session, builds Trails widget URL with toAddress=<walletAddress>
61+
# → ALWAYS run this command to get the URL — never construct it manually or hardcode any address
62+
# → send the returned `fundingUrl` to the user; `walletAddress` in the output confirms the recipient
63+
64+
# Step 4: Verify balances
65+
polygon-agent balances
66+
67+
# Step 5: Register agent on-chain (ERC-8004, Polygon mainnet only)
68+
polygon-agent agent register --name "MyAgent" --broadcast
69+
# → mints ERC-721 NFT, emits Registered event containing agentId
70+
# → retrieve agentId: open the tx on https://polygonscan.com, go to Logs tab,
71+
# find the Registered event — agentId is the first indexed parameter
72+
# → use agentId for reputation queries, reviews, and feedback
73+
```
74+
75+
## Commands Reference
76+
77+
### Setup
78+
```bash
79+
polygon-agent setup --name <name> [--force]
80+
```
81+
82+
### Wallet
83+
Valid `--chain` values: `polygon` (default/mainnet), `amoy` (Polygon testnet), `mainnet` (Ethereum), `arbitrum`, `optimism`, `base`. ERC-8004 agent operations only support `polygon`.
84+
85+
```bash
86+
polygon-agent wallet create [--name <n>] [--chain polygon] [--timeout <sec>] [--print-url]
87+
[--native-limit <amt>] [--usdc-limit <amt>] [--usdt-limit <amt>]
88+
[--token-limit <SYM:amt>] # repeatable
89+
[--usdc-to <addr> --usdc-amount <amt>] # one-off scoped transfer
90+
[--contract <addr>] # whitelist contract (repeatable)
91+
polygon-agent wallet import --code <6-digit-code> --rid <rid> [--name <n>]
92+
polygon-agent wallet import --ciphertext '<blob>|@<file>' [--name <n>] # legacy
93+
polygon-agent wallet list
94+
polygon-agent wallet address [--name <n>]
95+
polygon-agent wallet remove [--name <n>]
96+
```
97+
98+
### Operations
99+
```bash
100+
polygon-agent balances [--wallet <n>] [--chain <chain>]
101+
polygon-agent send --to <addr> --amount <num> [--symbol <SYM>] [--token <addr>] [--decimals <n>] [--broadcast]
102+
polygon-agent send-native --to <addr> --amount <num> [--broadcast] [--direct]
103+
polygon-agent send-token --symbol <SYM> --to <addr> --amount <num> [--token <addr>] [--decimals <n>] [--broadcast]
104+
polygon-agent swap --from <SYM> --to <SYM> --amount <num> [--to-chain <chain>] [--slippage <num>] [--broadcast]
105+
polygon-agent deposit --asset <SYM> --amount <num> [--protocol aave|morpho] [--broadcast]
106+
polygon-agent fund [--wallet <n>] [--token <addr>]
107+
polygon-agent x402-pay --url <url> --wallet <n> [--method GET] [--body <str>] [--header Key:Value]
108+
```
109+
110+
### Agent (ERC-8004)
111+
```bash
112+
polygon-agent agent register --name <n> [--agent-uri <uri>] [--metadata <k=v,k=v>] [--broadcast]
113+
polygon-agent agent wallet --agent-id <id>
114+
polygon-agent agent metadata --agent-id <id> --key <key>
115+
polygon-agent agent reputation --agent-id <id> [--tag1 <tag>] [--tag2 <tag>]
116+
polygon-agent agent reviews --agent-id <id> [--tag1 <t>] [--tag2 <t>] [--revoked]
117+
polygon-agent agent feedback --agent-id <id> --value <score> [--tag1 <t>] [--tag2 <t>] [--endpoint <e>] [--feedback-uri <uri>] [--broadcast]
118+
```
119+
120+
**ERC-8004 contracts (Polygon mainnet):**
121+
- IdentityRegistry: `0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`
122+
- ReputationRegistry: `0x8004BAa17C55a88189AE136b182e5fdA19dE9b63`
123+
124+
## Key Behaviors
125+
126+
- **Dry-run by default** — all write commands require `--broadcast` to execute
127+
- **Smart defaults** — `--wallet main`, `--chain polygon`, auto-wait on `wallet create`
128+
- **Fee preference** — auto-selects USDC over native POL when both available
129+
- **`fund`** — reads `walletAddress` from the wallet session and sets it as `toAddress` in the Trails widget URL. Always run `polygon-agent fund` to get the correct URL — never construct it manually or hardcode any address.
130+
- **`deposit`** — picks highest-TVL pool via Trails `getEarnPools`. If session rejects (contract not whitelisted), re-create wallet with `--contract <depositAddress>`
131+
- **`x402-pay`** — probes endpoint for 402, smart wallet funds builder EOA with exact token amount, EOA signs EIP-3009 payment. Chain auto-detected from 402 response
132+
- **`send-native --direct`** — bypasses ValueForwarder contract for direct EOA transfer
133+
- **Session permissions** — without `--usdc-limit` etc., session gets bare-bones defaults and may not transact
134+
- **Session expiry** — 6 months from creation
135+
136+
## Wallet Creation Flow (v2 Relay)
137+
138+
`wallet create` uses a Cloudflare Durable Object relay and a 6-digit out-of-band code — no cloudflared tunnel required. The browser encrypts the approved session with an X25519 key negotiated via the relay; the 6-digit code is the decryption key entered in the terminal.
139+
140+
**`--print-url` flag:** Use this in headless or non-interactive environments (CI, remote shells) where `wallet create` can't block waiting for the code. The CLI prints the approval URL and exits immediately. Complete the flow separately:
141+
```bash
142+
polygon-agent wallet import --code <6-digit-code> --rid <rid>
143+
```
144+
145+
## CRITICAL: Wallet Approval URL
146+
147+
When `wallet create` outputs a URL in the `url` or `approvalUrl` field, send the **complete, untruncated URL** to the user. The URL contains the relay request ID required for session approval.
148+
149+
- Do NOT shorten, summarize, or add `...` to the URL
150+
- Do NOT split the URL across multiple messages
151+
- Output the raw URL exactly as returned by the CLI
152+
153+
## Presenting Results to the User
154+
155+
CLI commands output JSON (non-TTY). After running a command, always render the result as formatted markdown — never paste raw JSON into the conversation.
156+
157+
| Command | How to present |
158+
|---------|---------------|
159+
| `balances` | Markdown table: Token / Balance columns. Show wallet address and chain above the table. |
160+
| `send` / `send-token` / `send-native` | One-liner summary: amount, symbol, recipient. If broadcast, show tx hash as a code span and explorer URL as a link. |
161+
| `swap` | Summary: `X FROM → Y TO` with chain. If broadcast, show deposit tx hash + explorer link. |
162+
| `deposit` | Summary: amount, asset, protocol, pool address. If broadcast, show tx hash + explorer link. |
163+
| `fund` | Show the `fundingUrl` as a clickable link with a brief instruction to open it. |
164+
| `wallet create` / `wallet list` | Wallet name, truncated address, chain in a small table or bullet list. |
165+
| `agent register` | Show agent name and tx hash as a code span with Polygonscan link. Remind user to retrieve `agentId` from the Registered event on the Logs tab. |
166+
| `agent wallet` | Show `agentId`, wallet address, and whether a wallet is set. |
167+
| `agent metadata` | Show `agentId`, key, and decoded value. |
168+
| `agent reputation` | Format score and tag breakdown as a small table. |
169+
170+
**Dry-run results** — always make it visually clear this was a simulation. Prefix with `⚡ Dry run` and show what *would* happen. Remind the user to re-run with `--broadcast` to execute.
171+
172+
**Errors** — extract the `error` field and present it as a clear sentence, not a JSON blob. Include the relevant fix from the Troubleshooting table if applicable.
173+
174+
---
175+
176+
## Use-Case Skills
177+
178+
For specific workflows, load the relevant sub-skill:
179+
180+
| Use Case | Skill |
181+
|----------|-------|
182+
| Polymarket prediction market trading | [polygon-polymarket/SKILL.md](polygon-polymarket/SKILL.md) |
183+
| DeFi — swap, deposit, yield | [polygon-defi/SKILL.md](polygon-defi/SKILL.md) |
184+
| x402 discovery & pay-per-call APIs | [polygon-discovery/SKILL.md](polygon-discovery/SKILL.md) |
185+
186+
---
187+
188+
## Troubleshooting
189+
190+
| Issue | Fix |
191+
|-------|-----|
192+
| `Builder configured already` | Add `--force` |
193+
| `Missing SEQUENCE_PROJECT_ACCESS_KEY` | Run `setup` first |
194+
| `Missing wallet` | `wallet list`, re-run `wallet create` |
195+
| `Session expired` | Re-run `wallet create` (6-month expiry) |
196+
| `Fee option errors` | Set `POLYGON_AGENT_DEBUG_FEE=1`, ensure wallet has funds |
197+
| `Timed out waiting for wallet approval` | Add `--timeout 600` |
198+
| `Invalid code: hash mismatch` | Wrong 6-digit code entered — retry (3 attempts allowed) |
199+
| `Relay request not found` | Session expired or already used — re-run `wallet create` (or `wallet create --print-url`) |
200+
| Deposit session rejected | Re-create wallet with `--contract <depositAddress>` |
201+
| Wrong recipient in Trails widget | Run `polygon-agent fund` (do not construct the URL manually) |
202+
| `x402-pay`: no 402 response | Endpoint doesn't require x402 payment, or URL is wrong |
203+
| `x402-pay`: payment token mismatch | Chain/token in the 402 response differs from wallet — check `--wallet` points to the right chain |
204+
| `x402-pay`: EOA funding failed | Wallet lacks sufficient balance to cover the payment amount — run `balances` and fund if needed |
205+
206+
## File Structure
207+
```
208+
~/.polygon-agent/
209+
├── .encryption-key # AES-256-GCM key (auto-generated, 0600)
210+
├── builder.json # EOA privateKey (encrypted), eoaAddress, accessKey, projectId
211+
├── wallets/<name>.json # walletAddress, session, chainId, chain
212+
└── requests/<rid>.json # Pending wallet creation requests (deleted after successful import)
213+
```

0 commit comments

Comments
 (0)