Azu Toolkit AI Skills (azutoolkit/ai-skills)

Official multi-agent AI skills, architectural blueprints, live GitBook documentation tools, and production guardrails for the Crystal & Azu Toolkit Ecosystem.

Compatible out of the box with:

• Claude Code (.claude-plugin/plugin.json, .claude-plugin/marketplace.json, ~/.claude/skills/)
• OpenAI Codex CLI & ChatGPT Desktop/App (.codex-plugin/plugin.json, agents/openai.yaml, ~/.codex/skills/)
• ChatGPT Web Projects & Custom GPTs (dist/chatgpt-web-bundle/ & dist/azutoolkit-chatgpt-skills.zip)
• Google Antigravity (plugin.json, ~/.gemini/config/skills/)
• Cursor, Windsurf & GitHub Copilot (rules/AGENTS.md)

---

📦 Included Skills (14 Skills)

Tier 1: Ecosystem Router & Live Documentation

Skill	Description
azutoolkit	Master router across all 6 Azu libraries, Crystal concurrency/type/macro idioms, Schema validation & definition rules, and live GitBook documentation helper (scripts/ask_gitbook.sh).

Tier 2: Core Library Skills (1:1 with Official Documentation)

Skill	Documentation Site	Description
azu	azutopia.gitbook.io/azu	Type-safe HTTP Endpoint(Request, Response) structs, middleware pipeline, Azu::Auth RBAC/scopes/MFA/challenge-response, Azu::Spark LiveView, Azu::Channel WebSockets, and OpenAPI 3.1.
azu-cli	azutopia.gitbook.io/azu-cli	Non-interactive project scaffolding (azu new), code generators (azu generate), database migrations (azu db:*), OpenAPI export, and live process inspection (--yes --ui json).
cql	azutopia.gitbook.io/cql	Crystal Query Language ORM: Active Record, Data Mapper, Repository, select_rows -> Model::Row, migrations (auto_sync: false), transactions, and PostgreSQL AsyncEngine.
session	azutopia.gitbook.io/session	Strongly-typed Session::Base contracts, AES-256-GCM CookieStore, RedisStore, ClusteredRedisStore (L1 + Redis PubSub), circuit breaker, rotation, and SecurityReset.
joobq	azutopia.gitbook.io/joobq	High-throughput Redis background jobs (JoobQ::Job) and JoobQPro (@[JoobQ::Encrypted], @[JoobQ::Secret], batches, outbox, and deterministic JoobQPro::Workflows::DSL).
authly	azutopia.gitbook.io/authly	OAuth 2.0, OpenID Connect, PKCE S256, Refresh Token family rotation, Device Code (RFC 8628), Challenge-Response, PAR, JARM, mTLS, JWKS rotation, and social sign-in.

Tier 3: Developer & AI Agent Workflow Skills (Task-Oriented Builders)

Skill	Description
azu-webapp-builder	Build full-stack server-rendered Crinja (Jinja2) + daisyUI web apps and real-time Azu::Spark::Component LiveViews with CSRF and session flash support.
azu-api-and-spa-builder	Build contract-first JSON REST APIs, OpenAPI 3.1 specs, WebSocket streams, StaticUi SPA hosting, and Nuxt/Vue/React dual-driver frontends (contract.ts + liveDriver + mockDriver).
azu-native-and-cli-builder	Build native mobile/desktop backends (PKCE, Device Code, Ed25519 Challenge-Response), embedded single-binary Tauri/WebView + local Azu + SQLite desktop apps, and Crystal CLIs.
azu-workflow-and-jobs-architect	Architect idempotent background jobs, CQL-to-Redis transactional outboxes, distributed sagas (compensate:), human-in-the-loop signals (wait_for), and replay tests.
azu-auth-and-multitenancy	Implement 3-layer authorization (scope ▷ endpoint ▷ call-site), hierarchical RBAC, Authly OIDC/FAPI 2.0, MFA/hardware key step-up, pg_advisory_xact_lock tenancy, and audit!.
azu-testing-and-verification	Write fast socket-free Azu::Testing::Client specs, Azu::Clock::Fake time-travel tests, Golden OpenAPI contract snapshots, and zero-allocation Benchmark.memory tests.
azu-production-ops	Harden, containerize, deploy, and monitor production Azu services: check_boot secret files (*_FILE), graceful shutdown ordering, Redis leader leases, Dockerfiles, and Prometheus /metrics.

---

🚀 Quick Installation

Option 1: Install for All Local Agents (Claude Code, OpenAI Codex/ChatGPT & Antigravity)

git clone https://github.com/azutoolkit/ai-skills.git
cd ai-skills
bash scripts/install.sh --target all

You can also target a single agent or copy files instead of symlinking:

bash scripts/install.sh --target claude       # -> ~/.claude/skills/
bash scripts/install.sh --target codex        # -> ~/.codex/skills/
bash scripts/install.sh --target antigravity  # -> ~/.gemini/config/skills/
bash scripts/install.sh --target all --copy   # Copy directories instead of symlinks

Option 2: Claude Code Plugin Marketplace

Inside Claude Code:

/plugin marketplace add azutoolkit/ai-skills
/plugin install azutoolkit@azutoolkit-ai-skills

Option 3: ChatGPT Web Projects & Custom GPTs

ChatGPT Web Projects and Custom GPTs support up to 20 uploaded Knowledge files. We pre-compile all 14 skills and their reference manuals into 6 consolidated Knowledge files in dist/chatgpt-web-bundle/:

1. Copy the instructions from dist/chatgpt-web-bundle/CHATGPT_INSTRUCTIONS.md into your ChatGPT Project Instructions or Custom GPT Instructions.
2. Upload the 6 numbered Markdown files (01-AZUTOOLKIT-CORE-AND-CLI.md through 06-TESTING-AND-PRODUCTION-OPS.md) from dist/chatgpt-web-bundle/ into your Project Files / Knowledge.
3. Alternatively, upload dist/azutoolkit-chatgpt-skills.zip in Code Interpreter sessions.

Option 4: Project-Level AGENTS.md / CLAUDE.md Guardrails

Copy rules/AGENTS.md into the root of any Crystal/Azu repository as AGENTS.md (and symlink CLAUDE.md -> AGENTS.md) so every coding agent enforces the 29 production Azu Toolkit guardrails automatically.

---

🔍 Live GitBook Documentation Helper

Every skill includes offline sitemaps (references/llms-sitemap.md), and skills/azutoolkit/scripts/ask_gitbook.sh lets agents fetch live Markdown pages or query the GitBook AI engine directly:

# Query any of the 6 GitBook sites (azu, azu-cli, cql, session, joobq, authly)
bash skills/azutoolkit/scripts/ask_gitbook.sh azu --ask "How do I use require_challenge_response! on an endpoint?"

# Fetch the live llms.txt index
bash skills/azutoolkit/scripts/ask_gitbook.sh cql --sitemap

# Fetch a raw Markdown documentation page
bash skills/azutoolkit/scripts/ask_gitbook.sh authly --page reference/fapi-compliance

---

🛠️ Validation & Building Bundles

# Validate all 14 skills (SKILL.md frontmatter, links, agents/openai.yaml) and plugin manifests
python3 scripts/validate.py

# Rebuild dist/chatgpt-web-bundle/ and dist/azutoolkit-chatgpt-skills.zip
python3 scripts/build_chatgpt_bundle.py

---

📄 License

Distributed under the MIT License. See LICENSE.txt for more information.