Most people set up Elyra like this: install it, drop an AGENTS.md in the repo, start typing. And honestly? That works. But it's like buying a house and living in the hallway — comfortable enough that you never discover the other rooms.

The users who get the most out of Elyra have all independently discovered the same handful of setup moves. None of them are documented loudly. All of them are small. Together they turn "a repo the agent visits" into "a repo the agent knows." Here's the full tour.

The secret is a directory: .elyra/

The single least-known fact about Elyra project setup: your repo can have a .elyra/ directory, and Elyra discovers everything inside it automatically. Settings, skills, prompt templates — all project-scoped, all versioned in git, all shared with every teammate the moment they pull.

A fully set-up project looks like this:

your-project/
├── AGENTS.md                  # the rules (you probably have this)
├── .elyra/
│   ├── settings.json          # project-scoped settings
│   ├── skills/
│   │   └── make-migration/
│   │       └── SKILL.md       # team-shared abilities
│   └── prompts/
│       └── review.md          # team-shared prompt templates
└── src/

Commit the whole thing. That's the move. Now let's walk through what each piece earns you.

0. Start with /init (the one-command head start)

Before you build any of this by hand, know that Elyra can scaffold most of it for you. From inside a session in your project:

/init

Elyra inspects the repo, detects your stack — Laravel with Livewire? Vue and Inertia? Filament? Docker? — and sets up the foundation: a .elyra/AGENTS.md pre-populated with what it learned about your project, the .elyra/blueprints/ directory, and a list of extensions worth installing for exactly your stack. It's polite about it, too: if .elyra/ already exists, it refuses to touch anything.

So why does the rest of this article exist? Because /init builds the house frame — the rooms are still yours to furnish. It won't write your team's skills, pin your models per repo, turn on codebase memory, or know which files deserve /pin. Run /init first; then spend the fifteen minutes below making it yours.

1. Install extensions into the project, not your machine

Everyone knows elyra install npm:@elyracode/laravel. Almost nobody knows the -l flag:

elyra install npm:@elyracode/laravel -l
elyra install npm:@elyracode/lsp-typescript -l

The difference is everything: -l writes the extension into .elyra/settings.json — the project's settings, not yours. Commit it, and every teammate (and every CI agent) gets the exact same extension setup on their next pull. No onboarding doc that says "remember to install these five extensions." The repo carries its own toolbelt.

2. Project skills: abilities that live in the repo

You may know skills — folders with a SKILL.md that teach the agent procedures. What most users miss: Elyra loads skills from two places. Your personal ~/.elyra/agent/skills/ … and the project's .elyra/skills/.

Personal skills follow you. Project skills follow the codebase — which is where most skills actually belong:

---
name: make-migration
description: Create a database migration following this project's conventions.
---
¶Make a migration

Run php artisan make:migration <name> — never write the file by hand.
Use anonymous class syntax; this project targets Laravel 11.
Always add the corresponding down() method.
Run php artisan migrate --pretend to verify before applying.

Pro move: when /learn extracts a skill from a session, it lands in your personal directory. If it's really a project procedure, move the folder into .elyra/skills/ and commit it. One person teaches the agent; the whole team inherits the knowledge.

3. Project settings: pin the models per repo

.elyra/settings.json doesn't just hold extensions. Anything you'd put in your global settings can be scoped to the project — and the one most worth scoping is model strategy:

{
"smartRouting": true,
"smartRoutingModels": {
"fast": "anthropic/claude-haiku-4-5",
"balanced": "anthropic/claude-sonnet-4-6",
"powerful": "anthropic/claude-fable-5"
}
}

Your hobby project can run on cheap models; the production codebase gets the premium tier — automatically, per directory, no flags to remember. Check what routing will do anytime with /route.

4. Turn on the memory (it's off by default)

This is the one that surprises people most. Elyra can remember your project between sessions — architecture, decisions, gotchas, conventions, distilled automatically when a session ends and loaded next time. No more re-explaining that the billing module is legacy and the events system is the new way.

It's off by default. Turn it on in /settings ("Codebase memory") and forget about it — from then on, every session starts a little smarter than the last.

One honest caveat: memory is stored per-machine (in your agent directory, keyed by project path), so it doesn't travel through git. Durable team knowledge belongs in AGENTS.md and project skills; memory is your personal accumulating context.

5. Keep AGENTS.md lean — and /pin the north star

Two related habits the power users share:

AGENTS.md is loaded every turn, so every line costs tokens forever. Keep the rules there; move the bulky reference material into files the agent reads on demand ("Conventions live in docs/conventions.md — read it before large refactors").

And for the one file the agent must never forget — your schema, your core types, the API contract — pin it:

/pin src/core/types.ts

Pinned files survive context compaction. In long sessions, this is the difference between an agent that drifts from your types and one that stays anchored to them.

6. The advanced move: separate agent profiles

One more, for those who want the whole house: the environment variable ELYRA_CODING_AGENT_DIR relocates Elyra's entire agent home — settings, sessions, skills, memory. Which means you can run completely separate agent profiles:

# Work profile: pinned premium models, work skills
ELYRA_CODING_AGENT_DIR=~/agents/work elyra

¶Experiments profile: cheap models, anything goes
ELYRA_CODING_AGENT_DIR=~/agents/lab elyra

Different brains for different lives, switching with one variable.

The checklist

Setting up a project properly takes about fifteen minutes — and the first one is free:

1. /init — detect the stack, scaffold .elyra/ and a pre-populated AGENTS.md

2. Trim the generated AGENTS.md — lean rules, pointers to deeper docs

3. elyra install <ext> -l — accept /init's extension suggestions, into the project, committed

4. .elyra/skills/ — team procedures, versioned

5. .elyra/settings.json — model strategy per repo

6. /settings → enable codebase memory

7. /pin your north-star files

8. Commit .elyra/ and AGENTS.md

Do it once, and every future session — yours, your teammates', the CI agent's — starts in a repo that explains itself. The hallway is fine. But the house is better.

Happy building.