feat: add usage skill

CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+## Project Overview
+
+Monorepo for the Worldcoin AgentKit — a toolkit for building AI agents that integrate with World ID and World Chain.
+
+- `agentkit/` — Core TypeScript library (`@worldcoin/agentkit`). Handles signature verification, x402 payments, AgentBook lookups, and agent registration validation.
+- `cli/` — CLI tool (`@worldcoin/agentkit-cli`) for agent registration via World ID.
+- `contracts/` — Solidity smart contracts (AgentBook registry). Built with Foundry.
+- `skills/` — Claude AI integration skills for agentkit.
+
+## Dev Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Build the library
+bun run build:agentkit
+
+# Run TypeScript tests (from agentkit/)
+cd agentkit && bun test
+
+# Run Solidity checks (from contracts/)
+cd contracts && forge build && forge test -vvv
+
+# Format code
+npx prettier --write .
+```
+
+## Pre-PR Checklist
+
+CI only runs Solidity checks — TypeScript issues must be caught locally.
+
+1. `bun run build:agentkit` — must compile cleanly
+2. `cd agentkit && bun test` — all tests must pass
+3. `npx prettier --write .` — format all files
+4. If touching contracts: `cd contracts && forge fmt && forge build && forge test -vvv`
+
+## Code Style
+
+Prettier handles formatting (config in root `package.json`), but know the conventions:
+
+- **Tabs** for indentation, **no semicolons**, **single quotes**
+- 120 character line width
+- Trailing commas in ES5 positions
+- Imports sorted descending via `prettier-plugin-sort-imports-desc`
+
+### Naming
+
+- `camelCase` for functions and variables
+- `PascalCase` for types and interfaces
+- `kebab-case` for file names
+- `SCREAMING_SNAKE_CASE` for constants
+
+### Exports
+
+- Named exports only — no default exports
+- Barrel file at `agentkit/src/index.ts` grouped by category (constants, types, server, chain utilities, etc.)
+- New public exports must be added to the barrel file
+
+### TypeScript
+
+- Strict mode is enabled — do not weaken it
+- Use the `type` keyword for type-only imports: `import type { Foo } from './bar'`
+- Zod schemas co-located with their types, derive types via `z.infer<typeof Schema>`
+- Bun native test runner (`bun:test`) — not Jest, not Vitest
+
+## Architecture Constraints
+
+- **Viem** for all Ethereum interactions — never ethers.js
+- **World Chain** is the only supported chain — do not add other chains
+- **Zod** for runtime validation at system boundaries
+- **Dual ESM/CJS** output from tsup — do not break either format
+- **Bun** is the package manager and test runner
+
+## Commit Conventions
+
+Follow conventional commits with short imperative descriptions:
+
+```
+fix: correct signature validation for empty payloads
+feat(agent-book): add batch lookup support
+chore: bump @worldcoin/agentkit to 0.1.7
+```
+
+Use scopes when the change is isolated to a specific module (e.g., `agent-book`, `cli`, `evm`, `solana`).

README.md

@@ -2,34 +2,42 @@
 
 Verify that an agent is backed by a real, World ID-verified human.
 
-Agent Kit is an x402 extension for websites and APIs that want to recognize human-backed agents. It combines:
+## What It Does
 
-- `@worldcoin/agentkit-cli` for registering an agent wallet in AgentBook with a World ID proof
-- `@worldcoin/agentkit` for integrating AgentBook-backed verification into x402 server flows
+1. An agent wallet is registered in AgentBook using a World ID proof.
+2. A website or API using x402 challenges the agent to sign a CAIP-122 message.
+3. The server verifies the signature, resolves the registering human from AgentBook, and applies the configured access policy.
 
-Registration does not have to require the agent to hold gas. `agentkit register <address>` now defaults to Base mainnet plus the shared hosted relay at `https://x402-worldchain.vercel.app`, and `API_URL` can override it.
+This lets applications distinguish between arbitrary automation and automation acting on behalf of a real human, without exposing the human's underlying identity.
 
-For the common production setup, keep payments on World Chain and keep AgentBook lookup on Base mainnet.
+## For Agents
 
-## Default Registration Flow
+### Register
 
-Start with this prompt:
+Register your wallet in AgentBook so servers can verify you are human-backed. Registration is gasless by default (uses a hosted relay on Base mainnet).
 
-```text
-Run `npx @worldcoin/agentkit-cli --llms`, then help me register your wallet address in the AgentBook.
+```bash
+npx @worldcoin/agentkit-cli register <your-wallet-address>
 ```
 
-Use the CLI's machine-readable guidance instead of reconstructing the flow from repo docs.
+This will prompt a World ID verification via World App. You only need to register once per wallet.
 
-## What It Does
+For the full registration guide (manual mode, custom relays, Base Sepolia): [`./cli/REGISTRATION.md`](./cli/REGISTRATION.md)
 
-1. An agent wallet is registered in AgentBook using a World ID proof.
-2. A website or API using x402 challenges the agent to sign a CAIP-122 message.
-3. The server verifies the signature, resolves the registering human from AgentBook, and applies the configured access policy.
+### Use
 
-This lets applications distinguish between arbitrary automation and automation acting on behalf of a real human, without exposing the human's underlying identity.
+Once registered, you can authenticate with any x402 endpoint that has the AgentKit extension to get free or discounted access instead of paying.
+
+The full flow — parsing 402 responses, signing the CAIP-122 challenge, and sending the `agentkit` header — is documented in the agent skill: [`./skills/agentkit-x402/SKILL.md`](./skills/agentkit-x402/SKILL.md)
+
+## For x402 Developers
 
-## Docs
+### Integrate
+
+Add AgentKit to your x402 server to offer human-backed agents free access, free trials, or discounts.
+
+```bash
+npm install @worldcoin/agentkit
+```
 
-- Registration: [`./cli/REGISTRATION.md`](./cli/REGISTRATION.md)
-- Server integration: [`./agentkit/DOCS.md`](./agentkit/DOCS.md) for the end-to-end x402 flow, including World Chain payments plus Base AgentBook lookup
+For the full integration guide (hooks setup, access modes, World Chain payments, AgentBook configuration): [`./agentkit/DOCS.md`](./agentkit/DOCS.md)

agentkit/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@worldcoin/agentkit",
-	"version": "0.1.5",
+	"version": "0.1.6",
 	"main": "./dist/cjs/index.js",
 	"module": "./dist/esm/index.mjs",
 	"types": "./dist/cjs/index.d.ts",