integrate-atlas-chat

cognitedata/builder-skills

Embed Atlas chat in standalone apps when the sidebar integration cannot work.

What is integrate-atlas-chat?

This skill integrates Atlas Agent Chat directly into your application UI as an exception path. Use it only when the user explicitly requires in-app embedded chat and the standard Fusion/EOS sidebar integration is unavailable (e.g., standalone apps that cannot connect to the host). For most cases, use integrate-fusion-agent instead.

Wire useAtlasChat hook for embedded chat in standalone applications
Preserve existing product UI while adding chat capability
Enforce rate limits: max 5 completions per user action, ceiling 50 total
Cache completions by space:externalId:lastUpdatedTime to avoid redundant calls
Probe app architecture to confirm sidebar integration is truly unavailable before proceeding

How to install integrate-atlas-chat

npx skills add https://github.com/cognitedata/builder-skills --skill integrate-atlas-chat

Prerequisites

@cognite/app-sdk installed
Confirmation that connectToHostApp/useHostApp cannot resolve in your environment
Review of Cognite's AI agent integration guide

Claude Code

Cursor

Windsurf

Cline

How to use integrate-atlas-chat

1.Verify the app is standalone and cannot use the Fusion/EOS sidebar (test connectToHostApp rejection)
2.Follow https://docs.cognite.com/cdf/flows/guides/ai_agent_integration
3.Wire the useAtlasChat hook with your agent-external-id argument
4.Implement caching by space:externalId:lastUpdatedTime for completion results
5.Set rate limits: max 5 completions per user action, max 50 total
6.Test that the chat UI integrates without replacing your existing product interface

Use cases

Good for

Adding chat to a standalone app that cannot load within Fusion/EOS
Embedding Atlas chat directly in custom application interfaces when host connection fails
Integrating chat for applications that reject host app connections
Adding per-item chat completions with proper caching and rate limiting

Who it's for

Developers building standalone applications requiring Atlas chat
Teams with apps that cannot integrate via the standard Fusion sidebar
Developers needing embedded chat in non-Fusion environments

integrate-atlas-chat FAQ

When should I use this skill instead of integrate-fusion-agent?

Only when the user explicitly requests in-app/embedded chat AND your app is standalone or cannot connect to the Fusion host. If the sidebar integration is possible, use integrate-fusion-agent instead.

What does 'probe the app' mean?

Test whether @cognite/app-sdk's connectToHostApp or useHostApp can resolve in your environment. If it resolves, the sidebar works and you should use integrate-fusion-agent. If it always rejects, in-app chat is appropriate.

What are the rate limits for chat completions?

Maximum 5 completions per single user action, with a ceiling of 50 total. Cache results by space:externalId:lastUpdatedTime to avoid redundant API calls.

Can I use this to add generic chat to my app?

No. This skill is specifically for Atlas Agent Chat in standalone apps. For generic chat features, use a different integration approach.

Should I replace my app UI with a chat view?

No. Keep your existing product UI and embed the chat alongside it. The chat is an addition, not a replacement.

Full instructions (SKILL.md)

Source of truth, from cognitedata/builder-skills.

name: integrate-atlas-chat description: >- Exception path. Use integrate-fusion-agent for Atlas/chat/agent. Only when the user explicitly requires in-app useAtlasChat and connectToHostApp cannot provide the EOS sidebar (standalone app, always rejects). Triggers: useAtlasChat, in-app atlas chat, embedded chat, vendored atlas-agent. Not for generic "add a chat". allowed-tools: Read, Glob, Grep, Edit, Write, Bash metadata: argument-hint: "[agent-external-id]"

Integrate Atlas Agent Chat (exception path)

Stop. Use integrate-fusion-agent (Atlas / EOS sidebar) unless all of:

The user asked for an in-app / embedded chat — not "add Atlas" / "add a chat"
The host Atlas sidebar cannot work. There is no manifest field for this. Probe the app:
- @cognite/app-sdk + connectToHostApp / useHostApp resolving inside Fusion/EOS → sidebar works; do not continue
- Standalone-only (host connect always rejects; app is never loaded in Fusion) → in-app chat is allowed
- If unsure, ask. Default to the sidebar.
The user accepted this as the non-standard path

Then follow https://docs.cognite.com/cdf/flows/guides/ai_agent_integration and wire useAtlasChat for $ARGUMENTS. Keep the product UI; do not replace the app with a chat view.

Do not map send() / chat completions over DMS rows. If per-item completions are required: 5 per user action, ceiling 50, cache by space:externalId:lastUpdatedTime. See integrate-fusion-agent.