Table of Contents

Neos Copilot

Note

This page is about Neos Copilot, the AI coding assistant that helps developers build Neos clusters from Claude Code or GitHub Copilot. It is unrelated to the in-app chatbot agent you configure for the end users of a cluster in Neos Studio — see Agent for that feature.

What it is

Neos Copilot is an agent definition plus a bundle of 8 skills that Neos generates for the current Neos version and installs into a developer's AI coding assistant profile. It teaches Claude Code or GitHub Copilot how to build Neos clusters correctly: which files to author, which files are generated, how to validate and generate metadata, and which local documentation to consult before improvising.

It is installed and updated with the neos agent install command, and removed with neos agent uninstall. See Commands for the exact command reference. Both the agent and its skills are installed under a name that includes the target Neos version, for example neos-copilot-3-2 and neos-cluster-bootstrap-3-2 for Neos 3.2 — so a cluster upgrade adds a fresh, distinctly named installation rather than overwriting the previous version's.

Quick start on an existing cluster

neos setup already installs Neos Copilot by default, so you may already have it. Otherwise, from the cluster's folder (so the cluster's own pinned Neos version is picked up):

neos agent install

This installs the Claude-format agent, which covers both Claude Code and VS Code's GitHub Copilot extension:

  • Claude Code CLI — open the cluster folder with claude; Claude auto-discovers the agent from ~/.claude/agents and routes to it for Neos-shaped tasks, or you can ask for it by name (for example "use the neos-copilot agent to...").
  • VS Code (Claude Code or GitHub Copilot extension) — VS Code reads the same Claude-format file directly; open the cluster, pick "Neos Copilot" as the active agent, and start prompting.
  • GitHub Copilot's standalone CLI (outside VS Code) needs its own Copilot-format install instead: neos agent install --target copilot (see Claude Code vs GitHub Copilot).

Also install the safety hooks, from the cluster or repository root:

neos agent install-hooks
Important

Start from a cluster with no check-metadata/neos generate warnings. Neos Copilot's hooks re-validate the file you just touched, not the whole cluster — on a cluster that already carries warnings, you can't tell a pre-existing issue from one the agent just introduced, and the agent itself has no way to know which warnings were already there. Run through the cluster and pipeline hardening checklist first if your cluster isn't warning-free yet.

Upgrading to a new Neos version

Because the agent and its skills are named with the Neos version, upgrading a cluster does not remove an older installation — the previous version's agent and skills stay on disk next to the new one. Uninstall every older version explicitly after upgrading:

neos agent uninstall --version 3.1

Repeat for every older version still present (--version accepts a dotted value, and targets every host by default, so each command removes both the Claude- and Copilot-format installs for that version). To check what's currently installed first:

ls ~/.claude/agents/neos-copilot-*
ls ~/.copilot/agents/neos-copilot-*

This matters most on Claude. VS Code's agent picker lets you explicitly choose which agent to activate, but Claude Code CLI routes a request to a subagent automatically based on its description — with several "Neos Copilot" versions installed side by side, there's no reliable way to force the current one. Leaving an older version installed risks Claude silently routing to outdated skills instead of the current ones.

What it does during a session

Neos Copilot acts as an orchestrator: for a task that depends on Neos framework behavior, it figures out which surface owns it — metadata authoring, generation, theming, and so on — consulting the framework documentation skill first when that isn't already obvious, then hands off to the matching skill instead of improvising from code alone.

Across every skill, it applies the same guardrails:

  • Generated vs authored — server/** and client/** are generated output, lost on the next neos generate; Neos Copilot only edits authored sources (modules/** metadata, business assembly code, root cluster YAML).
  • Evidence over assumption — it only states a Neos convention as fact when it actually read it this session, favoring installed skills and local files.
  • Structured questions — closed choices (which cluster, module, or metadata file to target) go through a structured question tool (vscode_askQuestions on GitHub Copilot, AskUserQuestion on Claude Code) instead of free-form chat.

neos agent install-hooks extends the generated/authored guardrail outside the chat itself, via two hooks written to the current directory: one blocks writes into generated code at the tool level, the other re-validates a metadata file right after it's edited. See Commands for the exact hook configuration.

The skills

Each skill below routes a specific surface of Neos development. The agent decides which skill to hand off to; you do not need to invoke them by name.

neos-cluster-bootstrap

Cluster bootstrap tasks: inspecting or completing installation, cluster creation, persistence setup, language setup, repository tooling reuse, and creating the first authored module before broader metadata work.

neos-metadata-authoring

YAML metadata authoring, discovery, naming, and localization: creating, editing, renaming, or understanding Module, Entity, EntityView, UIView, UIComponent, Theme, Menu, ServerMethod, DataObject, functions, permissions, and relations.

neos-generation-workflow

Validation and generation sequencing after metadata changes: whether to run check-metadata or neos generate, which target to generate, and how to interpret generation failures.

neos-application-shell

Application shell and custom home page setup: replacing the default home page, creating a dedicated shell UIView, wiring MainUIViewName with MainFramesContainerId (tabs) or MainViewContainerId (single view, no tabs), and designing an operational landing page such as a dashboard.

neos-themes

Application-wide visual changes: branding, palette, typography, component skinning, and coordinated light/dark theme behavior, on both the server and the client.

neos-business-assembly-resx

Business assembly .resx resource usage for localized, hand-written server-side messages through Properties.Resources.

neos-documentation-access

Consolidated Neos framework documentation across metadata authoring, UI template authoring, transpilation-safe UI code, handwritten server code, inter-cluster communication, reporting, permissions, persistence, and module packaging. This is the entry point when the owning surface for a task is not yet proven.

neos-improvement-reporting

Structured improvement-report creation when a repeated failure, an ambiguous instruction, a missing piece of context, a tooling limitation, or a documentation gap materially slows the agent down. This is an internal feedback loop for the Neos team, not a user-facing feature.

Claude Code vs GitHub Copilot

Host Agent file Skills directory
Claude Code ~/.claude/agents/neos-copilot-<version>.md ~/.claude/skills/neos-*-<version>
GitHub Copilot ~/.copilot/agents/neos-copilot-<version>.agent.md ~/.copilot/skills/neos-*-<version>

By default, neos agent install (no --target) only installs the Claude-format agent. VS Code reads that file directly for both Claude Code and GitHub Copilot sessions, so installing a separate Copilot-format file used to make the same agent appear twice in VS Code's agent picker. A default install also removes any leftover Copilot-format installation from an older Neos version automatically.

Pass an explicit --target all or --target copilot if you specifically want a standalone Copilot-format installation; an explicit target never removes another host's installation.

Note

neos agent install-hooks/uninstall-hooks is a separate command that still defaults to all — it writes repository-local hook configuration files, not the picker-visible agent file, so the duplicate-picker issue does not apply to it.

Content-wise, the skills and agent behavior are identical across both hosts; only the structured clarification tool differs (vscode_askQuestions vs AskUserQuestion), and the install step rewrites that reference automatically for each host.

Where to go next

  • Commands for the exact neos agent install/uninstall/install-hooks/uninstall-hooks commands, flags, and examples.
  • Using GitHub Copilot with Neos for the separate MCP server integration that lets GitHub Copilot query a running Neos cluster's data from Neos Studio — a different integration from Neos Copilot.