---
name: tschuehly/embabel-agent-builder
source: https://app.decimal.ai/s/tschuehly-embabel-agent-builder@1/SKILL.md
source_sha256: c4b92e3aa708
---

# Embabel Agent Builder

Use this skill only when the user explicitly invokes `embabel-agent-builder` by name or path. Do not use it automatically for general Embabel work.

This skill routes a prompt, product spec, feature spec, docs question, existing high-level agent spec, or implementation request to the right Embabel workflow. The default route is spec-first: produce or update a high-level Embabel agent spec, then use that spec to ground implementation and progress.

## Route Selection

Choose one route from the user's input:

| Input | Route | Load |
|---|---|---|
| Prompt, product spec, feature spec, ticket, rough idea, or existing domain model | Planning | `references/planning.md` |
| Specific Embabel API, annotation, tool, state, RAG, chatbot, planner, invocation, or testing question | Docs research | `references/docs-research.md` |
| Approved high-level Embabel agent spec, or request to implement an existing spec | Implementation | `references/implementation.md` |
| Request to build the whole agent from idea/spec through code | End-to-end | Planning, then Docs research as needed, then Implementation |
| Ambiguous request | Clarify route | Ask whether the user wants planning only, docs research only, implementation from a spec, or end-to-end build |

Do not start implementation without a high-level Embabel agent spec unless the user explicitly says to bypass planning. If the user bypasses planning, state that this is risky because Embabel's typed GOAP flow depends on domain and blackboard design.

## Shared Rules

Inspect the codebase before asking questions that local files can answer. Look for existing domain types, services, agents, tests, docs, `CONTEXT.md`, `CONTEXT-MAP.md`, and ADRs.

Challenge vague or overloaded terms. Propose canonical domain language when needed.

Ask one unresolved blocking question at a time, give a recommended answer, and continue only after the user accepts, rejects, or refines it.

When implementation touches Embabel-specific APIs, fetch version-matched docs using `references/docs-map.md` and `scripts/fetch-docs-section.py`. Run the fetcher from the target project or pass `--project-dir` so it resolves the repository's Embabel version. Fetch only the narrowest docs needed.

Do not inspect Maven JARs, source JARs, decompiled classes, or local dependency caches as a substitute for Embabel docs research. Use them only after the version-matched docs are insufficient and there is a concrete compile/runtime mismatch to investigate.

Do not copy migration, roadmap, or old-vs-new framing into project documentation. Describe only the supported current workflow and intended state.

For every LLM action that creates a typed object, require a structured-output contract. Cover the target output type, nullable fields, required Kotlin constructor parameters, `SomeOf` fields, absent-value representation, validation/defaulting strategy, typed examples for strict or optional nested output, and downstream formatter inputs. Do not mark implementation complete while structured-output binding or live/fixture acceptance remains unverified unless the spec records a concrete blocker.

## High-Level Spec Contract

Planning and implementation routes revolve around a high-level Embabel agent spec. Keep it as the grounding artifact and progress tracker.

The spec must cover:

- source input and user outcome
- domain model and important terms
- blackboard facts
- GOAP flow
- structured-output contracts for typed LLM outputs
- advanced pattern decisions for stateful loops, chatbots, tool exposure, RAG, and subagents
- implementation plan and progress
- tests and verification
- open questions and assumptions

If the project has a spec location, use it. Otherwise, keep the spec in the conversation during planning; when implementing, create or update a repo-local spec file such as `docs/agents/<agent-name>-spec.md` unless the project has a better established location.

## Phase References

Load exactly the reference needed for the selected route:

- Planning: `references/planning.md`
- Docs research: `references/docs-research.md`
- Implementation: `references/implementation.md`
- Version-matched Embabel docs map: `references/docs-map.md`