AI Assistant Integration
Two ways to give your AI coding assistant full Lumio SDK context:
| Approach | Setup | Best for |
|---|---|---|
| llms.txt | Zero install — paste a URL | Quick start, one-off questions, any AI tool |
| Agent Skill | npx @zaflun/lumio-agent-skill add | Persistent per-project context, deep integration |
Both approaches are complementary — use llms.txt for immediate context and the agent skill for ongoing project work.
llms.txt — Zero-Install Documentation
The Lumio developer docs are available as machine-readable files that any AI assistant can consume directly:
- llms.txt — structured index of all documentation pages with descriptions
- llms-full.txt — complete documentation (~400 KB) in a single file
How to use
Paste the URL or file content into your assistant's context window. Most AI tools accept URLs directly:
Read https://developers.lumio.vision/llms-full.txt and help me build a loyalty points bot module.
Or fetch and pipe the content:
curl -s https://developers.lumio.vision/llms-full.txt | pbcopy
These files are auto-generated from the documentation source on every build — they always reflect the latest published docs.
When to use llms.txt vs the agent skill
Use llms.txt when you want to give an AI assistant context without modifying your project. Useful for:
- Asking questions about the Lumio SDK before starting a project
- One-off code generation in a chat interface
- Tools that support URL fetching but not local skill files
Use the agent skill when you want persistent, automatic context on every conversation in your project. The skill files are loaded automatically by supported tools without any manual URL pasting.
Agent Skill — Per-Project Context
The @zaflun/lumio-agent-skill package installs reference files into your extension project that teach AI coding assistants how to build Lumio extensions correctly without you having to explain the SDK every session.
Supported tools: Claude Code, GitHub Copilot, Cursor, Google Gemini CLI, OpenAI Codex, Windsurf, and any agent that reads SKILL.md, AGENTS.md, or GEMINI.md.
What it installs
Running the setup command creates a .lumio/skills/ directory in your project with the following files:
| File | Purpose |
|---|---|
SKILL.md | Entry point — overview of the Lumio Extension SDK, conventions, and link map to other files |
components.md | All SDK UI components (<Layout>, inputs, display elements) with prop signatures |
server-functions.md | Declarative and handler-based server function patterns, storage scoping, external API calls |
cli-workflows.md | lumio dev, lumio build, lumio deploy, lumio logs — full CLI reference |
auth.md | Auth context, identity hooks, OAuth scope requirements |
runtime-scopes.md | Surface targeting (layer, editor, interactive), sandbox constraints |
best-practices.md | Performance, state management, extension manifest dos and don'ts |
troubleshooting.md | Common errors and how to fix them |
AI assistants that read these files understand:
- How
config_schemafields map to rendered UI inputs in the extension editor panel - Which hooks (
useLumioConfig,useLumioEvent,useExtensionStorage) are available in which surfaces - How to call external APIs from server functions without hitting the sandbox boundary
- The correct way to declare permissions and egress rules in
lumio.config.ts
Installation
Install the CLI globally and run the setup command inside your extension project:
npm install -g @zaflun/lumio-agent-skill
npx lumio-skills add
This creates .lumio/skills/ with all reference files. The directory is safe to commit to your repository — it contains only read-only reference markdown, no secrets or generated code.
Single-run alternative
If you prefer not to install globally, use npx directly:
npx @zaflun/lumio-agent-skill add
Using with Claude Code
Claude Code reads .lumio/skills/SKILL.md automatically when it is present in the working tree. No additional configuration is required — open your extension project directory in Claude Code and the assistant is already primed with Lumio context.
To manually point the assistant to a skill file, reference it in your prompt:
Read .lumio/skills/server-functions.md and help me add an external API call to my scoreboard handler.
Using with GitHub Copilot
Copilot picks up the skill files as workspace context when they are open in an editor tab or referenced in a prompt. For consistent context across a session, add the skill directory to your Copilot workspace instructions (.github/copilot-instructions.md):
See .lumio/skills/SKILL.md for Lumio Extension SDK conventions.
Using with Cursor
Cursor's @Docs and @File context commands work with the skill files directly:
@File .lumio/skills/components.md What inputs are available for a config_schema field of type "select"?
You can also add .lumio/skills/ to your Cursor project rules so Cursor loads the SKILL.md on every new conversation.
Using with Google Gemini CLI
Gemini CLI reads GEMINI.md in the project root. Create one that references the skill files:
<!-- GEMINI.md -->
## Lumio Extension SDK
This project is a Lumio extension. Read `.lumio/skills/SKILL.md` for the full SDK reference including components, hooks, server functions, and CLI commands.
For detailed references see:
- `.lumio/skills/components.md` — UI components
- `.lumio/skills/server-functions.md` — Server function patterns
- `.lumio/skills/cli-workflows.md` — CLI commands
Gemini loads this file automatically at session start.
Using with OpenAI Codex / ChatGPT
Codex reads AGENTS.md in the project root. Create one:
<!-- AGENTS.md -->
## Lumio Extension SDK
This project is a Lumio extension built with `@zaflun/lumio-sdk`.
Read `.lumio/skills/SKILL.md` for the complete SDK reference.
This also works with any agent that follows the AGENTS.md convention.
Using with Windsurf
Windsurf reads .windsurfrules in the project root. Create one:
Read .lumio/skills/SKILL.md for Lumio Extension SDK conventions.
This project uses @zaflun/lumio-sdk for components and hooks, and @zaflun/lumio-cli for development.
Windsurf will load this on every new conversation in the project.
Keeping skills up to date
The skill files are versioned with @zaflun/lumio-agent-skill. When the Lumio SDK is updated, re-run the same command to overwrite the old files with the latest reference:
npx lumio-skills add
The command is idempotent — running it multiple times is safe and always writes the version that matches your currently installed @zaflun/lumio-agent-skill package.
To update to the latest published version and refresh the skill files in one step:
npm install -g @zaflun/lumio-agent-skill@latest && npx lumio-skills add
What the assistant will not do
The skill files are reference documentation, not executable code. They teach the assistant Lumio patterns but do not grant it access to your Lumio account, API keys, or extension runtime. The assistant generates code; you review, test with lumio dev, and deploy with lumio deploy.