ai

<p align="center">
  <img src="https://raw.githubusercontent.com/fluttersdk/ai/main/.github/ai-logo.png" width="120" alt="FlutterSDK AI Logo" />
</p>

<h1 align="center">FlutterSDK AI</h1>

<p align="center">
  <strong>AI coding skills for the FlutterSDK ecosystem.</strong><br/>
  Teach your AI assistant Wind UI, Magic Framework, and more, across every major coding tool.
</p>

<p align="center">
  <a href="https://github.com/fluttersdk/ai/actions"><img src="https://img.shields.io/github/actions/workflow/status/fluttersdk/ai/deploy-registry.yml?branch=main&label=Registry" alt="Registry"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
  <a href="https://github.com/fluttersdk/ai/stargazers"><img src="https://img.shields.io/github/stars/fluttersdk/ai?style=flat" alt="GitHub stars"></a>
</p>

<p align="center">
  <a href="https://fluttersdk.github.io/ai/">Registry</a> ·
  <a href="https://github.com/fluttersdk/ai/issues">Issues</a> ·
  <a href="#quick-start">Quick Start</a>
</p>

---

## Why?

AI coding assistants are powerful, but they don't know your frameworks. They hallucinate widget names, guess at API patterns, and miss conventions.

**FlutterSDK AI fixes this.** It gives your AI structured knowledge about Wind UI's className system, Magic Framework's Laravel-inspired architecture, and more, so it generates correct code on the first try.

One install, every tool:

| Tool | Integration |
|:-----|:------------|
| [OpenCode](https://github.com/opencodetool/opencode) | URL-based skill registry |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Plugin + Marketplace |
| [Cursor](https://cursor.sh) | Rules (`.mdc`) |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Command templates (`.toml`) |
| [VS Code Copilot](https://code.visualstudio.com/) | Instructions (`.md`) |
| [Codex CLI](https://github.com/openai/openai-codex) | MCP config (`~/.codex/config.toml`) |
| [Antigravity CLI](https://github.com/antigravity-cli/antigravity) | MCP config (`~/.gemini/config/mcp_config.json`) |
| [Cline](https://github.com/cline/cline) | MCP config (`.mcp.json`) |
| [Roo Code](https://github.com/RooVetGit/Roo-Code) | MCP config (`.mcp.json`) |

## Skills

Five skills are available. See [docs/SKILLS.md](docs/SKILLS.md) for full descriptions.

| Skill | Package | Upstream | What it covers |
|:------|:--------|:---------|:---------------|
| `wind-ui` | `fluttersdk_wind` | [fluttersdk/wind](https://github.com/fluttersdk/wind) | W-prefix widgets, the `className` parser pipeline, `WindRecipe` variants, dark mode, responsive breakpoints, design culture |
| `magic-framework` | `magic` | [fluttersdk/magic](https://github.com/fluttersdk/magic) | IoC container, 18 facades, Eloquent ORM, GoRouter routing, forms, auth, testing, 5 ecosystem plugins |
| `fluttersdk-dusk` | `fluttersdk_dusk` | [fluttersdk/dusk](https://github.com/fluttersdk/dusk) | E2E driver: `dusk_*` MCP tools and matching CLI commands to snap, tap, type, and screenshot a running Flutter app |
| `fluttersdk-telescope` | `fluttersdk_telescope` | [fluttersdk/telescope](https://github.com/fluttersdk/telescope) | Runtime inspector: 9 ring buffers for HTTP, logs, exceptions, events, gates, DB queries |
| `fluttersdk-artisan` | `fluttersdk_artisan` | [fluttersdk/artisan](https://github.com/fluttersdk/artisan) | CLI framework + stdio MCP server: substrate `artisan_*` tools, builtin commands, `artisan_tinker` |

Each skill mirrors its upstream package's own `skills/` directory and arrives here when that package publishes a release. The exact synced version is the `version:` field in `skills/<name>/SKILL.md`, and [`skills/index.json`](skills/index.json) is the machine-readable index; neither is duplicated in this table, so neither can drift from it.

## MCP Server

`mcp.fluttersdk.com` exposes a single `search-docs` tool via Streamable HTTP.
Public, no auth required. Full client config snippets (Claude Code, Cursor,
OpenCode, Codex CLI, Gemini CLI, VS Code Copilot, and more) are in
[docs/MCP.md](docs/MCP.md).

For clients that only support stdio (Claude Desktop, older Codex CLI):

```bash
npx @fluttersdk/mcp
```

The npx bridge proxies stdio to the upstream HTTP server transparently.

## Quick Start

### Option 1: `npx skills` (Recommended)

The fastest way. Works with [40+ AI coding agents](https://github.com/vercel-labs/skills).

```bash
# Install all FlutterSDK skills to all detected agents
npx skills add fluttersdk/ai

# Install a specific skill
npx skills add fluttersdk/ai --skill wind-ui

# Install globally (available across all projects)
npx skills add fluttersdk/ai -g
```

### Option 2: Universal Installer

```bash
git clone https://github.com/fluttersdk/ai.git && cd ai

# Preview what would be installed
bash scripts/install.sh --dry-run --global

# Install globally for all detected tools
bash scripts/install.sh --global

# Install globally and register the MCP server for all detected tools
bash scripts/install.sh --global --with-mcp

# Or install into your current Flutter project
bash scripts/install.sh --project
```

### Option 3: Tool-Specific

<details>
<summary><strong>OpenCode</strong></summary>

Add the registry URL to your `opencode.json`:

```json
{
    "skills": {
        "urls": ["https://fluttersdk.github.io/ai/"]
    }
}
```

Skills are fetched automatically and cached locally.

</details>

<details>
<summary><strong>Claude Code</strong></summary>

```bash
/plugin marketplace add https://raw.githubusercontent.com/fluttersdk/ai/main/.claude-plugin/marketplace.json
/plugin install fluttersdk@fluttersdk-marketplace
```

The plugin auto-registers:
- 5 skills (`/fluttersdk:wind-ui`, `/fluttersdk:magic-framework`, `/fluttersdk:fluttersdk-dusk`, `/fluttersdk:fluttersdk-telescope`, `/fluttersdk:fluttersdk-artisan`)
- `/fluttersdk:flutter-review`, a review that runs in a subagent as an independent second pair of eyes and then fixes what it finds, plus `/fluttersdk:flutter-test`
- `fluttersdk:flutter-reviewer` and `fluttersdk:flutter-reviewer-deep` subagents, invokable directly with `@`
- `fluttersdk` MCP server (HTTP transport to `mcp.fluttersdk.com`; no manual `.mcp.json` edit required)

</details>

<details>
<summary><strong>Cursor</strong></summary>

```bash
mkdir -p .cursor/rules
cp tool-templates/cursor/fluttersdk.mdc .cursor/rules/
```

Activates automatically for all `.dart` files.

</details>

<details>
<summary><strong>Gemini CLI</strong></summary>

```bash
mkdir -p ~/.gemini/commands
cp tool-templates/gemini/*.toml ~/.gemini/commands/
```

Use with `/flutter-review` and `/flutter-test` commands.

</details>

<details>
<summary><strong>VS Code Copilot</strong></summary>

```bash
mkdir -p .github
cp .github/copilot-instructions.md .github/
```

</details>

## How It Works

```
skills/index.json              ← OpenCode fetches this from GitHub Pages
  → wind-ui/SKILL.md           ← Skill definition + className rules
  → wind-ui/references/*.md    ← On-demand widget docs, layout patterns, tokens
  → magic-framework/SKILL.md   ← Skill definition + framework laws
  → magic-framework/refs/*.md  ← Controllers, ORM, facades, routing, auth, ...
```

**OpenCode**: Fetches `fluttersdk.github.io/ai/index.json`, downloads listed skill files, caches locally.

**Claude Code**: Plugin manifest (`.claude-plugin/plugin.json`) makes the repo installable. Skills in `skills/` are auto-discovered and namespaced under `/fluttersdk:`.

**Deployment**: Push to `main` → GitHub Actions deploys `skills/` to GitHub Pages automatically.

## Contributing

### Adding a New Skill

1. Create `skills/<skill-name>/SKILL.md` with YAML frontmatter (`name`, `description`)
2. Add reference files in `skills/<skill-name>/references/`
3. Update `skills/index.json`: list **every** file in the `files` array
4. Bump version in `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`
5. Push to `main`

See [CLAUDE.md](CLAUDE.md) for the full specification.

> **Important**: Every file must be listed in `index.json`: OpenCode only downloads listed files. Forgetting a file means users get incomplete skills.

## License

MIT. See [LICENSE](LICENSE) for details.

---

<p align="center">
  <sub>Built with care by <a href="https://github.com/fluttersdk">FlutterSDK</a></sub><br/>
  <sub>If this saves you time, <a href="https://github.com/fluttersdk/ai">give it a star</a>; it helps others discover it.</sub>
</p>