liveavatar-agent-skills: Instructions file for Codex

AGENTS.md

This repository contains AI agent skills for integrating with LiveAvatar. The skills follow the Agent Skills format.

Repository Structure

liveavatar-agent-skills/
├── README.md                        # User-facing documentation
├── AGENTS.md                        # This file (for AI agents)
├── CLAUDE.md                        # Points to AGENTS.md
├── CONTRIBUTING.md                  # Contribution guidelines
├── package.json                     # For npx skills add
└── skills/
    ├── liveavatar-demo/               # Curated demo catalog → clone, configure, run
    │   ├── SKILL.md                  # Catalog, routing, preflight, handoff
    │   └── references/
    │       ├── sales-agent.md        # Demo 1: Next.js AI sales agent
    │       ├── livekit-agent.md      # Demos 2+3: LiveKit agent (hosted + BYO room)
    │       └── gpt-live-demos.md     # Demo 4: GPT-Live × Hyperframes (one repo, several branches)
    ├── liveavatar-integrate/         # End-to-end integration builder
    │   ├── SKILL.md                  # Discovery, routing, golden pathways
    │   └── references/
    │       ├── embed-guide.md        # Embed implementation
    │       ├── full-mode-guide.md    # FULL Mode + Custom LLM/TTS/PTT
    │       └── lite-mode-guide.md    # LITE Mode + audio format + plugins
    ├── liveavatar-debug/             # Troubleshooting
    │   └── SKILL.md
    └── liveavatar-feedback/          # Post-integration feedback collection
        └── SKILL.md

Skill Architecture

Design Principles

1. Clear responsibilities per skill. liveavatar-demo = run someone else's working code. liveavatar-integrate = discovery → recommendation → implementation in the user's own code. liveavatar-debug = troubleshooting. liveavatar-feedback = feedback collection.
2. liveavatar-integrate is the main skill. It scans the user's codebase, asks clarifying questions if needed, picks the best pathway, and walks through implementation. All three integration paths (Embed, FULL, LITE) live here as reference guides.
3. Pit of success. Always default to the simplest integration. Embed > FULL > LITE.
4. Gotcha-driven. Lead with what breaks, not what works. Silent failures are the biggest enemy.
5. Backend/frontend split is sacred. Every code block must label where it runs and which auth header to use.
6. Smaller skills inline everything. liveavatar-debug has no references/ directory. Only split into references when SKILL.md would exceed ~500 lines.
7. Demo repos document themselves. liveavatar-demo clones a repo, then reads that repo's own agent docs (AGENTS.md → CLAUDE.md → docs/ + README) as the setup source of truth — repo docs are always newer than this skill. A demo's references/ file holds only what the repo can't know: account-level gotchas, billing semantics, routing, agent-safe paths through interactive scripts. When a demo repo gains a real AGENTS.md, shrink its reference here accordingly (the gpt-live-demos reference is the model; sales-agent carries full setup detail only because its repo has no agent docs).