<div align="center">

<img src="social-preview.jpg" width="100%" alt="Material Icons Agent Skill Banner" />

# Material Icons Agent Skill

### One icon workflow for every AI coding agent.

Search, import, migrate, validate, and maintain official Google Material Symbols<br>across **Codex · Claude · Gemini · Antigravity · Cursor · Grok**

<br>

[![Version](https://img.shields.io/badge/version-0.1.0-7C3AED?style=for-the-badge)](docs/versioning.md)
[![Agent Skills](https://img.shields.io/badge/Agent_Skills-compatible-0F766E?style=for-the-badge)](https://agentskills.io/home)
[![MCP](https://img.shields.io/badge/MCP-stdio-2563EB?style=for-the-badge)](docs/mcp.md)
[![License](https://img.shields.io/badge/license-MIT-15803D?style=for-the-badge)](LICENSE)

<br>

[**Quick start**](#-quick-start) · [**Documentation**](docs/README.md) · [**Русский**](docs/ru/README.md) · [**MCP tools**](docs/mcp.md)

<br>

<img src="https://img.shields.io/badge/Codex-412991?style=for-the-badge&logo=openai&logoColor=white" alt="Codex" />
<img src="https://img.shields.io/badge/Claude-CC785C?style=for-the-badge&logo=anthropic&logoColor=white" alt="Claude" />
<img src="https://img.shields.io/badge/Gemini-4285F4?style=for-the-badge&logo=googlegemini&logoColor=white" alt="Gemini" />
<img src="https://img.shields.io/badge/Cursor-1E1E1E?style=for-the-badge" alt="Cursor" />
<img src="https://img.shields.io/badge/Antigravity-34A853?style=for-the-badge&logo=google&logoColor=white" alt="Antigravity" />
<img src="https://img.shields.io/badge/Grok-000000?style=for-the-badge&logo=x&logoColor=white" alt="Grok" />

</div>

<br>

> [!NOTE]
> **Version 0.1.0** — The kit is local-first: it uses official Google sources, does not overwrite assets by default, and requires explicit confirmation for destructive changes.

---

## 🔭 How it works

```text
  💬  User request
       ↓
  🧠  Agent Skill ──── understands intent, platform, style, states, accessibility
       ↓
  🔧  MCP + CLI ────── searches, imports, previews, migrates, audits, validates
       ↓
  📦  Project ───────── Android Compose · Android Views · Flutter · Web · React · Vue
```

<table>
  <tr>
    <th>🎯 Need</th>
    <th>✅ Included capability</th>
  </tr>
  <tr>
    <td><strong>Find the right symbol</strong></td>
    <td>Semantic search, aliases, style filters, HTML preview</td>
  </tr>
  <tr>
    <td><strong>Add it correctly</strong></td>
    <td>Official Android VectorDrawable or SVG import</td>
  </tr>
  <tr>
    <td><strong>Modernize a project</strong></td>
    <td>Dry-run-first Compose migration to local resources</td>
  </tr>
  <tr>
    <td><strong>Keep it consistent</strong></td>
    <td>Asset audit, accessibility checks, selected/unselected states</td>
  </tr>
  <tr>
    <td><strong>Use any agent</strong></td>
    <td>Portable <code>SKILL.md</code>, host adapters, stdio MCP, and CLI</td>
  </tr>
</table>

---

## ⚡ Quick start

```powershell
git clone <repository-url> material-icons-agent-skill
cd material-icons-agent-skill
npm install
npm run setup
```

Start a new agent chat after setup. For **Claude App / Desktop / Cowork**, upload the generated `material-icons-claude-skill.zip` in **Customize → Skills → Create skill → Upload a skill**.

---

## 🚀 Choose your entry point

<details>
<summary><strong>💬 Ask an agent</strong></summary>
<br>

```text
Use $material-icons: choose a rounded save icon for an article and add it to my Android Views screen.
```

The agent reads the portable skill, detects your project environment, searches for the best icon, and imports it — all in one request.

</details>

<details>
<summary><strong>⌨️ Use the CLI</strong></summary>
<br>

```powershell
npm run cli -- search "save article" --style rounded
npm run cli -- migrate-compose --root C:\path\to\project
npm run cli -- skill:update
```

</details>

<details>
<summary><strong>🔌 Connect an MCP client</strong></summary>
<br>

```powershell
npm start
```

The server exposes search, import, preview, audit, environment detection, Compose migration, accessibility validation, optional wrappers, and an optional offline catalog.

See the full [MCP reference →](docs/mcp.md)

</details>

---

## 🧩 Command palette

| Goal | Command |
|:---|:---|
| 📥 Install into detected clients | `npm run setup` |
| 🔄 Refresh integrations after an update | `npm run skill:update` |
| 🗑️ Remove integrations | `npm run skill:remove` |
| ⌨️ Run the CLI | `npm run cli -- <command>` |
| ✅ Run syntax checks | `npm test` |

> [!TIP]
> Run a command for one host: `npm run setup -- --hosts Cursor`<br>
> Remove only one: `npm run skill:remove -- --hosts Cursor`<br>
> For global access in Cursor, ChatGPT, and Claude Desktop → set up a global [MCP server](docs/mcp.md).

---

## 📚 Documentation

<table>
  <tr>
    <th>📘 Start here</th>
    <th>📖 Go deeper</th>
  </tr>
  <tr>
    <td><a href="docs/installation.md">Installation and hosts</a></td>
    <td><a href="docs/skill-usage.md">Skill workflow</a> · <a href="docs/mcp.md">MCP reference</a></td>
  </tr>
  <tr>
    <td><a href="docs/android-and-policy.md">Android migration and policy</a></td>
    <td><a href="docs/automation.md">Automation and CI</a> · <a href="docs/versioning.md">Versioning</a></td>
  </tr>
  <tr>
    <td><a href="docs/ru/README.md">🇷🇺 Русская документация</a></td>
    <td><a href="SECURITY.md">Security policy</a> · <a href="CHANGELOG.md">Changelog</a></td>
  </tr>
</table>

---

## 🗂️ Repository map

```text
skills/material-icons/     🧠  Portable skill and deterministic helpers
src/                        🔧  MCP server and CLI
integrations/               🔌  MCP and host templates
templates/                  🏗️  Opt-in CI template
docs/                       📚  English + Russian documentation
```

---

## 👤 Developer

Built and maintained by **ByteFlipper** ([GitHub](https://github.com/ByteFlipper-58) · [Website](https://byteflipper.com) · [Telegram](https://t.me/byteflipper)).

This project is intentionally **local-first**: the skill is portable, the MCP server runs over stdio, and destructive operations require explicit confirmation. See [SECURITY.md](SECURITY.md) for the operational boundaries.

---

## 📄 License

The kit is licensed under [MIT](LICENSE). Google Material Symbols are provided separately under Apache-2.0; see [google/material-design-icons](https://github.com/google/material-design-icons).