English | 繁體中文 | 简体中文 | 日本語

AI Agent Dev Guide — A Claude Code Skill Suite

A set of Claude Code skills for building AI agent applications — covering the full stack from the agentic backend (pluggable per framework; currently Embabel + Spring AI: GOAP / @Agent / JVM) to a backend-agnostic frontend that renders UI generated by an LLM (backend produces a spec → SSE streaming → progressively rendered dashboard).

Grounded in real projects: the learn-embabel course (backend) and the embabel-json-render POC (frontend). Baseline versions: Spring Boot 4.1.x + Embabel 1.5.1 + Spring AI 2.0.x (Spring Boot 4 is supported since Embabel 1.5.0; Boot 3.5.x projects stay on Embabel 1.0.x).

Skills at a glance

Skill	Layer	Responsibility
ai-agent-dev-guide	Entry / Router	Start here when unsure which skill to use: routing table, "should I use an agent framework" decision, backend-framework list, full-stack build order
embabel-agent-backend	Backend (Embabel)	@Agent/@Action/@AchievesGoal, GOAP planning, Blackboard, domain @Tool, MCP/RAG, @Condition gates, @State loops, cost guardrails, multi-agent orchestration, testing & observability
json-render-ui	Frontend (backend-agnostic)	json-render flat element-tree spec contract, component catalog ↔ registry reconciliation, SSE streaming (fetch+ReadableStream), lenient progressive rendering, backend progress/cost panels, click-to-drill-down, catalog maintenance page
webmcp-development-guide	Agent-facing (optional)	Publish page capabilities as WebMCP tools an external Agent (ChatGPT Site tools / Chrome 149+) can discover and call: document.modelContext, Imperative vs Declarative, tool schemas and lifecycle, security, Inspector/Evals verification; includes integration with an LLM-generated UI

All four cross-reference each other; when the requirement is ambiguous or spans tiers, dispatch from ai-agent-dev-guide. The frontend (json-render-ui) is also usable on its own with any conformant backend. webmcp-development-guide is an optional layer pointing the other way: the first three build your agent, this one makes your site a tool provider for someone else's — and it stacks on any frontend.

Installation

Option 1: Claude Code Plugin (recommended)

Add this repo as a plugin marketplace, then install the whole suite:

/plugin marketplace add kevintsai1202/ai-agent-dev-guide
/plugin install ai-agent-dev-guide@ai-agent-dev-guide

After install, all four skills load automatically and Claude triggers them based on each skill's description.

Option 2: skills CLI

Install the suite straight from the repo with the skills CLI — it auto-discovers the four skills under skills/ and wires them into your agent(s):

# Interactive: pick which agents and scope to install into
npx skills add kevintsai1202/ai-agent-dev-guide

# Non-interactive: all skills, all detected agents
npx skills add kevintsai1202/ai-agent-dev-guide --all

# Install globally (user-level, available across all projects)
npx skills add kevintsai1202/ai-agent-dev-guide --global

Works cross-platform (macOS / Linux / Windows) — no manual file copying required.

Directory structure

ai-agent-dev-guide/
├─ .claude-plugin/
│  ├─ plugin.json          # plugin definition
│  └─ marketplace.json     # marketplace definition (for /plugin marketplace add)
├─ skills/
│  ├─ ai-agent-dev-guide/       # entry / router skill
│  ├─ embabel-agent-backend/   # backend: agent / GOAP / JVM
│  ├─ json-render-ui/   # frontend: generative UI / streaming rendering
│  └─ webmcp-development-guide/  # agent-facing: WebMCP tool publishing (optional)
└─ README.md

Version compatibility

• The latest released Embabel is 1.5.2 (Maven Central, 2026-09-16), built on Spring Boot 4.1.0 + Spring AI 2.0.x + Jackson 3.
• Spring Boot 4 is supported since Embabel 1.5.0. For projects still on Spring Boot 3.5.x, stay on the Embabel 1.0.0 line (Spring AI 1.1.7). Mixing lines still fails at context startup (HttpHeaders.addAll signature change).
• Migrating to Boot 4 also means spring-boot-starter-web → spring-boot-starter-webmvc, Jackson 3 (tools.jackson.*, immutable ObjectMapper), and Spring AI 2.0 model-builder renames.
• System One (TypeSafe Jev) Acceleration: The suite supports TypeSafe Jev System One models as fast (~50ms) judgment nodes across all domains:
  • Backend (embabel-agent-backend): Semantic @Condition gates, type-driven routing, guardrails, and parallel fan-out.
  • Generative UI (json-render-ui): Zero-hallucination component catalog selection via Choice and metric severity styling via Score.
  • WebMCP (webmcp-development-guide): Dynamic tool pruning to eliminate tool overload and pre-execution safety gatekeepers via backend BFF proxy.
• Before you start, confirm the actual versions from your target project's build file — never assume version numbers. See the Version Compatibility section in embabel-agent-backend.