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:
| App |
Owns |
Calls |
hubspot-pipeline |
CRM deals, contacts, companies, associations |
provider-api-request with provider hubspot |
gong-evidence |
Calls, transcripts, snippets, speaker evidence |
provider-api-request with provider gong |
knowledge-base |
Internal docs, pricing rules, playbooks |
local search/read actions |
deal-brief |
Orchestration and final brief |
message-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.
1---2name: composable-mini-apps3description: >-4 Build focused workspace apps and cross-app workflows, using A2A only when a5 task needs a peer-owned capability. Use when designing mini-app boundaries.6scope: dev7metadata:8 source: https://skillmd.com/skills/builderio/composable-mini-apps9---1011# Composable Mini-Apps1213## Rule1415Prefer many one-job apps in a workspace over one oversized app. A headless app16can own a provider, dataset, workflow, or specialist action surface without a17full UI. This architecture does not make every task a cross-app task: use the18current app's actions by default. Call a peer only when the user asks or the19outcome requires data, credentials, or a capability only that peer can provide.20A peer's availability or ability to enrich the result is not enough. The app21that owns an artifact remains responsible for authoring and editing it.2223## Shape2425- Give each mini-app one clear job, a concise `package.json` description, and26 action names that describe the job it owns.27- Keep provider credentials and upstream API details in the app that owns that28 provider or workflow. When a task needs its peer-exclusive data, credentials,29 or capability, delegate that bounded work instead of copying integration30 code.31- Use a tiny status/config screen only when users need to inspect state. A32 pure headless app is fine when its job is invoked by agents, automations, or33 sibling apps.34- If two workflows only share a helper, put the helper in `packages/shared`;35 keep the workflow actions in separate apps.3637## Discovery And Invocation3839The main agent should discover available siblings before assuming capability:4041- Runtime agents receive an `<available-apps>` block built from42 `discoverAgents()`. Workspace siblings are layered in by43 `discoverWorkspaceAgents()`. It carries one line per app — enough to know a44 sibling exists, not enough to know what it can do.45- Use the built-in `describe-workspace-apps` tool for actual capability.46 It reads each peer's live `/.well-known/agent-card.json` and returns its47 purpose plus any optional stable machine contracts; pass `app: "<id>"` for48 one peer's full description. Use it only when the requested outcome depends49 on peer-exclusive data or capability and you cannot tell which peer owns it50 or whether a known peer can provide it, or when the user asks which app can51 do the job.52- Never hand-maintain a markdown or code list of what each workspace app does.53 A stale catalog is worse than none: it reads as authoritative while pointing54 at capabilities that moved or vanished. An app's purpose belongs in its own55 `package.json` `description` (which flows into the workspace manifest and the56 `<available-apps>` block), and its capabilities belong in its exposed57 actions — both of which `describe-workspace-apps` reads live.58- UI shells, headless surfaces, and scripts can read the same registry through59 `GET /_agent-native/agents?selfAppId=<app-id>`.60- Code or CLI callers should use the first-class message-based A2A invocation61 path (`invokeAgent()` / `agent-native invoke`) when they need to ask an app62 by id, name, or URL.63- In the agent loop, use `call-agent` with the sibling app id only when the64 requested outcome depends on peer-exclusive data or capability, or the user65 explicitly asks you to involve that app. A sibling's availability or ability66 to enrich the result is not enough. Never call the current app through67 `call-agent`; use local actions instead.68- Send a natural-language objective by default so the sibling can apply its own69 instructions, skills, schemas, data dictionary, credentials, and tools.70 `invokeAgentAction()` or `call-agent` with `action` + `input` is only for an71 explicit stable semantic read contract whose complete input is already known.72 Never expose or call an implementation action as a workaround for slow or73 failed message delegation.7475Send narrow prompts to siblings: name the exact question, relevant ids, date76ranges, and expected output shape. Preserve returned ids and URLs verbatim.7778## Artifact Handoff7980Mini-apps should hand off compact artifacts, not giant pasted transcripts or81provider dumps. When a mini-app creates something another app may use, return82or store an artifact with:8384- `artifactType` - what kind of output this is, such as `deal-set`,85 `call-evidence`, `brief`, `dashboard`, or `report`.86- `artifactId` - the stable app-owned id, file path, or resource id.87- `createdAt` - an ISO timestamp.88- `source` - provider/app/source ids used to create it.89- `summary` - a short human-readable explanation.90- `items` or `records` - the bounded structured data downstream apps need.91- `links` - fully qualified URLs for user-visible artifacts.9293Downstream apps should receive artifact ids, URLs, and narrow follow-up94questions. If a downstream app needs more detail, it should call back to the95artifact-owning app instead of asking the orchestrator to paste the whole96corpus into a prompt.9798Example: `hubspot-pipeline` returns `{ artifactType: "deal-set",99artifactId: "hubspot-pipeline:deal-set:2026-06-18" }`. `deal-brief` passes100that id to `gong-evidence`, which returns a `call-evidence` artifact id and101URLs. `deal-brief` then synthesizes the final brief from the artifact ids and102bounded summaries.103104## Provider APIs105106Provider-specific actions are shortcuts, not limits. When the upstream API can107answer the question better than a first-class shortcut, call108`provider-api-catalog` and `provider-api-docs` as needed, then109`provider-api-request` against the real provider endpoint. For broad joins,110searches, or absence claims, stage the bounded corpus with `stageAs` and reduce111it with `query-staged-dataset` or code.112113When composing apps, make the provider-owning mini-app do those114`provider-api-request` calls. The orchestrator should delegate a bounded job;115it should not reimplement every provider endpoint locally.116117## Example118119For a sales-intelligence workspace, split the job into small apps:120121| App | Owns | Calls |122| --- | --- | --- |123| `hubspot-pipeline` | CRM deals, contacts, companies, associations | `provider-api-request` with provider `hubspot` |124| `gong-evidence` | Calls, transcripts, snippets, speaker evidence | `provider-api-request` with provider `gong` |125| `knowledge-base` | Internal docs, pricing rules, playbooks | local search/read actions |126| `deal-brief` | Orchestration and final brief | message-based `invokeAgent()` or `call-agent` to the three apps |127128Flow: `deal-brief` asks `hubspot-pipeline` for the target account and open129deals, asks `gong-evidence` for recent transcript evidence about those deals,130asks `knowledge-base` for relevant playbook guidance, then synthesizes the131answer. That is a HubSpot→Gong→knowledge-base chain made of focused apps,132not a single app that clones every provider integration.133134## Don't135136- Do not clone Mail, Calendar, Analytics, Brain, Assets, or another first-party137 app just to reuse its data. Delegate or link to the existing app.138- Do not hide a multi-provider workflow inside a giant "misc tools" app.139- Do not add one-off provider endpoints when `provider-api-request` can express140 the upstream API safely.141- Do not create wrapper routes that only re-export another app's action or A2A142 result.143144## Related Skills145146- **a2a-protocol** - How apps expose and call A2A endpoints.147- **actions** - How each mini-app exposes its own operation surface.148- **external-agents** - How external MCP hosts route through workspace apps.149- **storing-data** - How app-owned data stays SQL-backed and portable.