Skip to main content
Each supported agent has its own opinion about where skills go and how MCP config is stored. gaal abstracts those differences behind a small agent registry and a per-agent renderer.

​
The registry

gaal ships with a built-in registry that records, for every supported agent:
  • Project skills directory, where skills live inside a project (e.g. .claude/skills, .cursor/skills).
  • Global skills directory, where skills live in the user’s home (e.g. ~/.claude/skills).
  • MCP config file, the JSON file gaal upserts into (e.g. ~/.config/claude/claude_desktop_config.json).
  • Skills search paths, additional directories gaal audit scans when discovering existing skills.
  • Package-manager search paths, vendor-specific directories (~/.cursor/extensions, ~/.claude/plugins/cache) where extension-installed skills may live.
You can list what’s in the registry at any time: 
$ gaal agents
NAME             INSTALLED  PROJECT_SKILLS    GLOBAL_SKILLS                MCP_CONFIG
claude-code      yes        .claude/skills    ~/.claude/skills             ~/.config/claude/claude_desktop_config.json
cursor           yes        .agents/skills    ~/.cursor/skills             ~/.cursor/mcp.json
codex            yes        .agents/skills    ~/.codex/skills              ~/.codex/mcp.json
github-copilot   no         .github/skills    ~/.copilot/skills            ~/.vscode/settings.json
…
Pass an agent name for a detailed view: gaal agents cursor.

​
What “installed” means

gaal calls an agent installed when at least one of these is true on the host:
  • The agent’s MCP config file exists.
  • The agent’s project skills directory exists.
  • The agent’s global skills directory exists.
  • A package-manager path for the agent exists (e.g. ~/.cursor/extensions).
Agents marked installed are the ones that win when you use the agents: ["*"] wildcard in your skills entries.

​
Renderers

Once gaal knows what to install (the plan from gaal sync) and where (the registry), the per-agent renderer does the actual write:
  • For skills, the renderer copies the source files into the agent’s skills directory and adapts file names if the agent expects a different layout.
  • For MCP servers, the renderer reads the target JSON, upserts the mcpServers entry, and writes the file back atomically.
Renderers are responsible for the guarantees, they never clobber, they always write atomically, and they fail loudly when the target is malformed.

​
The “generic” agent

Some agents (Cline, Cursor in default mode, Codex, OpenCode, Warp, …) follow vendor-neutral conventions. Rather than maintaining separate redundant entries, gaal has a built-in generic agent that owns:
  • ./.agents/skills (project-local)
  • ~/.agents/skills (global)
Agents flagged supports_generic_project: true or supports_generic_global: true install through the generic renderer. This means a single .agents/skills/ directory can serve multiple agents at once. See Agent integrations for which agents use the generic fallback.

​
Extending the registry

You can teach gaal about an agent it doesn’t know yet by writing your own registry file at:
OSPath
Linux / macOS$XDG_CONFIG_HOME/gaal/agents.yaml (defaults to ~/.config/gaal/agents.yaml)
Windows%AppData%\gaal\agents.yaml
Custom entries extend the built-in list, you can’t override a built-in entry. See Custom agents for the schema.

Agent integrations

Custom agents

gaal agents

gaal audit