AI Assistant Integration

The @zaflun/lumio-agent-skill package installs a set of 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_schema fields 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.