diff --git a/ai-toolkit/contributions.mdx b/ai-toolkit/contributions.mdx deleted file mode 100644 index 77db3c3..0000000 --- a/ai-toolkit/contributions.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Contributions -description: Contribute skills, evals, and improvements to the Uniswap AI toolkit. ---- - -Thank you for your interest in contributing to Uniswap AI! This guide will help you get started. \ No newline at end of file diff --git a/ai-toolkit/evals.mdx b/ai-toolkit/evals.mdx deleted file mode 100644 index c2a9d5d..0000000 --- a/ai-toolkit/evals.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Evals -description: Evaluate AI agent performance on Uniswap integration tasks with standardized benchmarks. ---- - diff --git a/ai-toolkit/meta.json b/ai-toolkit/meta.json deleted file mode 100644 index bf0731f..0000000 --- a/ai-toolkit/meta.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "title": "AI Toolkit", - "root": true, - "pages": ["overview", "skills", "evals", "contributions"] -} diff --git a/ai-toolkit/overview.mdx b/ai-toolkit/overview.mdx deleted file mode 100644 index 3ea41bf..0000000 --- a/ai-toolkit/overview.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Overview -description: Explore AI-powered tools, plugins, and LLM context files to build on Uniswap faster. ---- - -Uniswap provides AI-powered development tools that help you integrate swaps, build v4 hooks, provide liquidity, and interact with the EVM — all from within your code editor. These tools work with AI coding agents like [Claude Code](https://claude.ai/code), [Cursor](https://cursor.com), [Windsurf](https://windsurf.com), and others. - - - - - - - -## Uniswap AI - -The [Uniswap AI](https://github.com/uniswap/uniswap-ai) is an open-source collection of plugins and skills that give AI coding agents deep knowledge of Uniswap protocols, APIs, and smart contracts. Instead of relying on general training data, these tools provide agents with up-to-date, protocol-specific guidance — including code patterns, security best practices, and deployment workflows. - -### Available plugins - -| Plugin | Description | -| --- | --- | -| **uniswap-trading** | Integrate Uniswap swaps via the Uniswap API, Universal Router SDK, or direct smart contract calls. Covers Permit2 patterns, ERC-4337 smart accounts, and multi-chain support. | -| **uniswap-hooks** | Security-first guidance for building Uniswap v4 hooks. Includes vulnerability patterns (NoOp attacks, delta accounting), permission flag risk matrices, and aggregator hook templates for routing through external DEX liquidity. | -| **uniswap-viem** | EVM blockchain integration using [viem](https://viem.sh) and [wagmi](https://wagmi.sh). Covers client setup, contract interactions, account management, and React hooks. | -| **uniswap-driver** | Discover tokens and plan Uniswap swaps or liquidity positions. Generates deep links that open directly in the Uniswap interface with parameters pre-filled. | -| **uniswap-cca** | Configure and deploy Continuous Clearing Auction (CCA) smart contracts for token distribution. Interactive configuration, validation, and Foundry deployment scripts. | - -### Install with the Skills CLI - -Uniswap AI is available through [skills.sh](https://skills.sh), a cross-platform CLI for installing AI agent skills: - -```bash -npx skills add uniswap/uniswap-ai -``` - -This works with any AI coding agent that supports skill files — not just Claude Code. - -### Install as a Claude Code plugin - -If you use [Claude Code](https://claude.ai/code), first add the Uniswap marketplace, then install individual plugins: - -```bash -# Add the Uniswap marketplace -/plugin marketplace add uniswap/uniswap-ai - -# Install individual plugins -claude plugin add uniswap-hooks # v4 hook development -claude plugin add uniswap-trading # Swap integration -claude plugin add uniswap-viem # EVM / viem / wagmi -claude plugin add uniswap-driver # Token discovery & deep links -claude plugin add uniswap-cca # CCA auction configuration -``` - -Once installed, the plugins activate automatically when relevant to your task. You can also invoke specific skills directly — for example, `/uniswap-hooks:v4-security-foundations` for a security-first walkthrough of hook development. - -## LLM Context Files - -If you prefer to give your AI agent raw documentation context rather than structured skills, Uniswap publishes LLM-optimized text files that summarize the protocol documentation. - -### llms.txt and llms-full.txt - -AI models have a context window — the amount of text they can process at once. Providing relevant documentation upfront helps the model give better answers without hallucinating. - -Uniswap offers two context files: - -- **[llms.txt](https://docs.uniswap.org/v4-llms.txt)** — A compact summary with links to documentation sections. Works well with most models (100K+ token context windows). -- **[llms-full.txt](https://docs.uniswap.org/v4-llms-full.txt)** — A verbose version with more inline content. Use this if your model has a larger context window or you want more detail without following links. - -## Code Editor Setup - -### Cursor - -1. Navigate to **Cursor Settings > Features > Docs** -2. Select **Add new doc** and paste one of the following URLs: - -``` -https://docs.uniswap.org/v4-llms.txt -``` - -``` -https://docs.uniswap.org/v4-llms-full.txt -``` - -3. Use `@docs` → **Uniswap** to reference the documentation in your chat. - -### Windsurf - -Windsurf requires referencing documentation in each conversation. Add it to the Cascade window (`CMD+L`): - -``` -@docs:https://docs.uniswap.org/v4-llms.txt -``` - -``` -@docs:https://docs.uniswap.org/v4-llms-full.txt -``` - -### Claude Code - -Install the Uniswap AI plugins (see [above](#install-as-a-claude-code-plugin)) for the richest integration. The plugins provide structured skills, expert agents, and protocol-specific tools that go beyond static documentation context. diff --git a/ai-toolkit/skills.mdx b/ai-toolkit/skills.mdx deleted file mode 100644 index 707c87d..0000000 --- a/ai-toolkit/skills.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Skills -description: Browse available Uniswap AI skills for swap integration, hook development, liquidity management, and more. ---- diff --git a/meta.json b/meta.json index aef319d..2afc689 100644 --- a/meta.json +++ b/meta.json @@ -1,4 +1,4 @@ { "title": "Documentation", - "pages": ["get-started", "trading", "liquidity", "ai-tooling", "api", "protocols", "sdks", "unichain", "ecosystem"] + "pages": ["get-started", "trading", "liquidity", "uniswap-ai", "api", "protocols", "sdks", "unichain", "ecosystem"] } diff --git a/uniswap-ai/contributions.mdx b/uniswap-ai/contributions.mdx new file mode 100644 index 0000000..eb90799 --- /dev/null +++ b/uniswap-ai/contributions.mdx @@ -0,0 +1,210 @@ +--- +title: Contributions +description: Contribute skills, plugins, and improvements to Uniswap AI. +--- + +Thank you for your interest in contributing to Uniswap AI! This guide will help you get started. + +## Prerequisites + +- Node.js 22.x or later +- npm 11.7.0 or later +- Git +- Familiarity with TypeScript and Nx + +## Getting Started + +### 1. Fork and clone + +```bash +# Fork the repository on GitHub, then clone +git clone https://github.com/YOUR_USERNAME/uniswap-ai.git +cd uniswap-ai +``` + +### 2. Install dependencies + +```bash +# Ensure you have the correct npm version +npm install -g npm@11.7.0 + +# Install dependencies +npm install +``` + +### 3. Verify setup + +```bash +# Run tests +npx nx run-many --target=test + +# Build all packages +npx nx run-many --target=build + +# Start docs dev server +npm run docs:dev +``` + +## Development Workflow + +### Creating changes + +1. **Create a branch** from `main`: + + ```bash + git checkout -b feature/your-feature-name + ``` + +2. **Make your changes** following the code guidelines + +3. **Test your changes**: + + ```bash + # Run affected tests + npx nx affected --target=test + + # Run affected linting + npx nx affected --target=lint + + # Check formatting + npx nx format:check + ``` + +4. **Commit using conventional commits**: + + ```bash + git commit -m "feat(hooks): add new feature" + ``` + +### Pull request process + +1. Push your branch and create a PR +2. Ensure all CI checks pass +3. Request review from maintainers +4. Address any feedback +5. Once approved, the PR will be merged + +## Code Guidelines + +### TypeScript + +- Use strict TypeScript (`strict: true`) +- Never use `any` - prefer `unknown` with type guards +- Use explicit types at function boundaries +- Prefer union types over enums + +### Nx usage + +- All packages must be Nx projects +- Use Nx commands for build, test, lint +- Leverage Nx caching and affected detection + +### Documentation + +After making changes: + +1. Update relevant CLAUDE.md files +2. Update README.md if needed +3. Add/update documentation in `docs/` +4. Run `npm exec markdownlint-cli2 -- --fix "**/*.md"` + +## Creating New Packages + +### New plugin + +```bash +# Plugins go in packages/plugins/ +mkdir -p packages/plugins/my-plugin +``` + +Each plugin needs: + +- `package.json` with plugin metadata +- `project.json` for Nx configuration +- `.claude-plugin/plugin.json` manifest +- `README.md` documentation + +### New skill + +Skills are defined in `packages/plugins/*/skills/`: + +```bash +mkdir -p packages/plugins/uniswap-hooks/skills/my-skill +``` + +Each skill needs: + +- `SKILL.md` - The skill definition +- Validation through lint, tests, and documentation updates + +## PR workflow highlights + +### Branch naming + +Use descriptive branch names: + +```text +feature/add-v4-security-skill +fix/plugin-timeout-issue +docs/update-installation-guide +``` + +### PR title and commit format + +Use Conventional Commits for both commit messages and PR titles: + +```text +feat(hooks): add dynamic fee hook skill +fix(trading): improve swap integration guidance +docs: update installation guide +``` + +### CI checks to expect + +Typical checks include: + +- Build +- Lint +- Format +- Tests +- Plugin validation + +## Commit Message Format + +You can use [Conventional Commits](https://www.conventionalcommits.org/): + +```text +(): + +[optional body] + +[optional footer] +``` + +### Types + +| Type | Description | +| ---------- | --------------------- | +| `feat` | New feature | +| `fix` | Bug fix | +| `docs` | Documentation only | +| `style` | Formatting changes | +| `refactor` | Code restructuring | +| `test` | Adding/updating tests | +| `chore` | Maintenance tasks | + +### Scopes + +- `hooks` - uniswap-hooks plugin +- `cca` - uniswap-cca plugin +- `trading` - uniswap-trading plugin +- `viem` - uniswap-viem plugin +- `driver` - uniswap-driver plugin +- `docs` - Documentation +- `ci` - CI/CD workflows + +## Getting Help + +- Open an issue for bugs or feature requests +- Join the [Uniswap Discord](https://discord.gg/uniswap) for discussions +- Check existing issues before creating new ones \ No newline at end of file diff --git a/uniswap-ai/meta.json b/uniswap-ai/meta.json new file mode 100644 index 0000000..4390581 --- /dev/null +++ b/uniswap-ai/meta.json @@ -0,0 +1,5 @@ +{ + "title": "Uniswap AI", + "root": true, + "pages": ["overview", "skills", "contributions"] +} diff --git a/uniswap-ai/overview.mdx b/uniswap-ai/overview.mdx new file mode 100644 index 0000000..8644403 --- /dev/null +++ b/uniswap-ai/overview.mdx @@ -0,0 +1,111 @@ +--- +title: Overview +description: Get started with Uniswap AI plugins, skills, and LLM context. +--- + +Use Uniswap AI to speed up swap integration, hook development, and EVM workflows with tools designed for builders on Uniswap. + +## Uniswap AI + +The [Uniswap AI](https://github.com/uniswap/uniswap-ai) repository is an open-source collection of plugins and skills for coding agents. It provides protocol-specific guidance for Uniswap APIs and smart contracts. + +### Available plugins + +| Plugin | Description | +| --- | --- | +| **uniswap-trading** | Integrate swaps via the [Uniswap API](https://developers.uniswap.org/dashboard), Universal Router SDK, or direct contract calls. | +| **uniswap-hooks** | Security-first guidance for building Uniswap v4 hooks. | +| **uniswap-viem** | EVM integration with viem and wagmi. | +| **uniswap-driver** | Token discovery and swap/liquidity planning with deep links. | +| **uniswap-cca** | Configure and deploy CCA contracts for token distribution. | + +### Official skills + +These are the official skills currently published in Uniswap AI: + +- `configurator` +- `deployer` +- `liquidity-planner` +- `pay-with-any-token` +- `swap-integration` +- `swap-planner` +- `v4-security-foundations` +- `viem-integration` + +## Install Uniswap AI + +### Skills CLI (any agent) + +```bash +npx skills add Uniswap/uniswap-ai +``` + +### Claude Code marketplace + +If you use [Claude Code](https://claude.ai/code), add the marketplace and install plugins: + +```bash +# Add the Uniswap marketplace +/plugin marketplace add uniswap/uniswap-ai + +# Install individual plugins +/plugin install uniswap-hooks # v4 hook development +/plugin install uniswap-trading # Swap integration (+ pay-with-any-token skill) +/plugin install uniswap-viem # EVM / viem / wagmi +/plugin install uniswap-driver # Token discovery & deep links +/plugin install uniswap-cca # CCA auction configuration +``` + +Once installed, the plugins activate automatically when relevant to your task. You can also invoke specific skills directly, for example, `/uniswap-hooks:v4-security-foundations` for a security-first walkthrough of hook development. + +## LLM Context Files + +If you prefer to give your AI agent raw documentation context rather than structured skills, Uniswap publishes LLM-optimized text files that summarize the protocol documentation. + +### llms.txt and llms-full.txt + +AI models have a context window, which is the amount of text they can process at once. Providing relevant documentation upfront helps the model give better answers without hallucinating. + +Uniswap offers two context files: + +- **[llms.txt](https://docs.uniswap.org/v4-llms.txt)**: A compact summary with links to documentation sections. Works well with most models (100K+ token context windows). +- **[llms-full.txt](https://docs.uniswap.org/v4-llms-full.txt)**: A verbose version with more inline content. Use this if your model has a larger context window or you want more detail without following links. + +## Code Editor Setup + +### Cursor + +1. Navigate to **Cursor Settings > Features > Docs** +2. Select **Add new doc** and paste one of the following URLs: + +``` +https://docs.uniswap.org/v4-llms.txt +``` + +``` +https://docs.uniswap.org/v4-llms-full.txt +``` + +3. Use `@docs` → **Uniswap** to reference the documentation in your chat. + +### Windsurf + +Windsurf requires referencing documentation in each conversation. Add it to the Cascade window (`CMD+L`): + +``` +@docs:https://docs.uniswap.org/v4-llms.txt +``` + +``` +@docs:https://docs.uniswap.org/v4-llms-full.txt +``` + +### Claude Code + +Install the Uniswap AI plugins (see [above](#install-as-a-claude-code-plugin)) for the richest integration. The plugins provide structured skills, expert agents, and protocol-specific tools that go beyond static documentation context. + +## Where to Go Next + +- [Browse official skills](/docs/uniswap-ai/skills) +- [Contribute to Uniswap AI](/docs/uniswap-ai/contributions) +- [View the Uniswap AI repository](https://github.com/Uniswap/uniswap-ai) diff --git a/uniswap-ai/skills.mdx b/uniswap-ai/skills.mdx new file mode 100644 index 0000000..3f22e2d --- /dev/null +++ b/uniswap-ai/skills.mdx @@ -0,0 +1,77 @@ +--- +title: Skills +description: Browse available Uniswap AI skills for swap integration, hook development, liquidity management, and more. +--- + +Use Uniswap AI skills to run specialized workflows for swap integration, hook development, EVM interactions, and liquidity planning. + +## Uniswap Skills + +These are the official skills currently available in the installer: + +- `configurator` +- `deployer` +- `liquidity-planner` +- `pay-with-any-token` +- `swap-integration` +- `swap-planner` +- `v4-security-foundations` +- `viem-integration` + +## Available plugins + +| Plugin | Skill | What it helps with | Invocation | +|---|---|---|---| +| `uniswap-hooks` | `v4-security-foundations` | Review v4 hook architecture and security risks before implementation | `/v4-security-foundations` | +| `uniswap-cca` | `configurator` | Configure CCA auction parameters for a new deployment | `/configurator` | +| `uniswap-cca` | `deployer` | Deploy CCA contracts using the factory deployment pattern | `/deployer` | +| `uniswap-trading` | `swap-integration` | Integrate swaps using the Uniswap API, Universal Router, or direct smart contract calls | `/swap-integration` | +| `uniswap-trading` | `pay-with-any-token` | Pay HTTP 402 challenges (x402 and MPP) using tokens via Uniswap swaps | `/pay-with-any-token` | +| `uniswap-viem` | `viem-integration` | Set up EVM clients and contract interactions with viem and wagmi | `/viem-integration` | +| `uniswap-driver` | `swap-planner` | Plan token swaps and generate interface deep links | `/swap-planner` | +| `uniswap-driver` | `liquidity-planner` | Plan LP positions and generate interface deep links | `/liquidity-planner` | + +## Install skills + +Install Uniswap AI skills with the Skills CLI: + +```bash +npx skills add Uniswap/uniswap-ai +``` + +If your environment supports interactive selection, you can choose specific skills from the install prompt. + +## Use skills + +### Direct invocation + +Invoke a skill explicitly with a slash command: + +```text +/v4-security-foundations +``` + +### Contextual activation + +Skills also activate contextually when your prompt matches the skill domain: + +```text +What are the security risks of beforeSwapReturnDelta? +``` + +In this example, the assistant can activate the v4 security foundations skill automatically. + +## Skill structure + +Each skill is defined in a `SKILL.md` file and typically includes: + +- Frontmatter metadata (`name`, `description`, and plugin metadata) +- Step-by-step instructions for the agent +- Optional references in a `references/` directory + +## Add a new skill + +1. Create the skill folder under `packages/plugins//skills//` +2. Add a `SKILL.md` file with frontmatter and clear instructions +3. Register the skill in the plugin manifest (`plugin.json`) +4. Validate the skill with lint and test checks before opening a PR