Skip to content

BuilderIO/agent-native / packages/core/src/templates/workspace-core/.agents/skills/composable-mini-apps

composable-mini-apps

Unverified

Build focused workspace apps and cross-app workflows, using A2A only when a task needs a peer-owned capability. Use when designing mini-app boundaries.

Composable Mini-Apps

Rule

Prefer many one-job apps in a workspace over one oversized app. A headless app can own a provider, dataset, workflow, or specialist action surface without a full UI. This architecture does not make every task a cross-app task: use the current app's actions by default. Call a peer only when the user asks or the outcome requires data, credentials, or a capability only that peer can provide. A peer's availability or ability to enrich the result is not enough. The app that owns an artifact remains responsible for authoring and editing it.

Shape

  • Give each mini-app one clear job, a concise package.json description, and action names that describe the job it owns.
  • Keep provider credentials and upstream API details in the app that owns that provider or workflow. When a task needs its peer-exclusive data, credentials, or capability, delegate that bounded work instead of copying integration code.
  • Use a tiny status/config screen only when users need to inspect state. A pure headless app is fine when its job is invoked by agents, automations, or sibling apps.
  • If two workflows only share a helper, put the helper in packages/shared; keep the workflow actions in separate apps.

Discovery And Invocation

The main agent should discover available siblings before assuming capability:

  • Runtime agents receive an <available-apps> block built from discoverAgents(). Workspace siblings are layered in by discoverWorkspaceAgents(). It carries one line per app — enough to know a sibling exists, not enough to know what it can do.
  • Use the built-in describe-workspace-apps tool for actual capability. It reads each peer's live /.well-known/agent-card.json and returns its purpose plus any optional stable machine contracts; pass app: "<id>" for one peer's full description. Use it only when the requested outcome depends on peer-exclusive data or capability and you cannot tell which peer owns it or whether a known peer can provide it, or when the user asks which app can do the job.
  • Never hand-maintain a markdown or code list of what each workspace app does. A stale catalog is worse than none: it reads as authoritative while pointing at capabilities that moved or vanished. An app's purpose belongs in its own package.json description (which flows into the workspace manifest and the <available-apps> block), and its capabilities belong in its exposed actions — both of which describe-workspace-apps reads live.
  • UI shells, headless surfaces, and scripts can read the same registry through GET /_agent-native/agents?selfAppId=<app-id>.
  • Code or CLI callers should use the first-class message-based A2A invocation path (invokeAgent() / agent-native invoke) when they need to ask an app by id, name, or URL.
  • In the agent loop, use call-agent with the sibling app id only when the requested outcome depends on peer-exclusive data or capability, or the user explicitly asks you to involve that app. A sibling's availability or ability to enrich the result is not enough. Never call the current app through call-agent; use local actions instead.
  • Send a natural-language objective by default so the sibling can apply its own instructions, skills, schemas, data dictionary, credentials, and tools. invokeAgentAction() or call-agent with action + input is only for an explicit stable semantic read contract whose complete input is already known. Never expose or call an implementation action as a workaround for slow or failed message delegation.

Send narrow prompts to siblings: name the exact question, relevant ids, date ranges, and expected output shape. Preserve returned ids and URLs verbatim.

Artifact Handoff

Mini-apps should hand off compact artifacts, not giant pasted transcripts or provider dumps. When a mini-app creates something another app may use, return or store an artifact with:

  • artifactType - what kind of output this is, such as deal-set, call-evidence, brief, dashboard, or report.
  • artifactId - the stable app-owned id, file path, or resource id.
  • createdAt - an ISO timestamp.
  • source - provider/app/source ids used to create it.
  • summary - a short human-readable explanation.
  • items or records - the bounded structured data downstream apps need.
  • links - fully qualified URLs for user-visible artifacts.

Downstream apps should receive artifact ids, URLs, and narrow follow-up questions. If a downstream app needs more detail, it should call back to the artifact-owning app instead of asking the orchestrator to paste the whole corpus into a prompt.

Example: hubspot-pipeline returns { artifactType: "deal-set", artifactId: "hubspot-pipeline:deal-set:2026-06-18" }. deal-brief passes that id to gong-evidence, which returns a call-evidence artifact id and URLs. deal-brief then synthesizes the final brief from the artifact ids and bounded summaries.

Provider APIs

Provider-specific actions are shortcuts, not limits. When the upstream API can answer the question better than a first-class shortcut, call provider-api-catalog and provider-api-docs as needed, then provider-api-request against the real provider endpoint. For broad joins, searches, or absence claims, stage the bounded corpus with stageAs and reduce it with query-staged-dataset or code.

When composing apps, make the provider-owning mini-app do those provider-api-request calls. The orchestrator should delegate a bounded job; it should not reimplement every provider endpoint locally.

Example

For a sales-intelligence workspace, split the job into small apps:

AppOwnsCalls
hubspot-pipelineCRM deals, contacts, companies, associationsprovider-api-request with provider hubspot
gong-evidenceCalls, transcripts, snippets, speaker evidenceprovider-api-request with provider gong
knowledge-baseInternal docs, pricing rules, playbookslocal search/read actions
deal-briefOrchestration and final briefmessage-based invokeAgent() or call-agent to the three apps

Flow: deal-brief asks hubspot-pipeline for the target account and open deals, asks gong-evidence for recent transcript evidence about those deals, asks knowledge-base for relevant playbook guidance, then synthesizes the answer. That is a HubSpot→Gong→knowledge-base chain made of focused apps, not a single app that clones every provider integration.

Don't

  • Do not clone Mail, Calendar, Analytics, Brain, Assets, or another first-party app just to reuse its data. Delegate or link to the existing app.
  • Do not hide a multi-provider workflow inside a giant "misc tools" app.
  • Do not add one-off provider endpoints when provider-api-request can express the upstream API safely.
  • Do not create wrapper routes that only re-export another app's action or A2A result.

Related Skills

  • a2a-protocol - How apps expose and call A2A endpoints.
  • actions - How each mini-app exposes its own operation surface.
  • external-agents - How external MCP hosts route through workspace apps.
  • storing-data - How app-owned data stays SQL-backed and portable.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall