---
title: FAQ
description: Common questions about Agent Layer.
---

## What problem does Agent Layer solve?
It keeps instructions, skills, MCP servers, and approvals consistent across multiple agents by generating every client config from one repo-local source of truth.

If you run more than one client, Agent Layer prevents drift and gives you a single place to review or audit changes.

## Does Agent Layer align with the skills standard?
Yes. Skill parsing and validation align with the [agentskills.io specification](https://agentskills.io/specification), including canonical directory `SKILL.md` naming with a compatibility fallback for lowercase `skill.md`.

## Does Agent Layer install Claude/Codex/Antigravity/Copilot CLI/VS Code?
No. Install client CLIs separately and ensure they are on your `PATH`.

## What do I edit vs what gets generated?
You edit `.agent-layer/`. Agent Layer generates client-specific outputs in each client's native format when you run `al sync` or `al <client>`.

Rule of thumb: generated files include:

- Instruction shims: `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`
- Agent config: `.mcp.json`, `.agy/antigravity-cli/settings.json`, `.agy/antigravity-cli/mcp_config.json`, `.claude/settings.json`, `.copilot/mcp-config.json`
- Shared skills: `.agents/skills/`
- Claude skills: `.claude/skills/`
- Codex config and rules: `.codex/`
- VS Code integration: `.vscode/mcp.json` and a managed block in `.vscode/settings.json`

If VS Code is enabled, Agent Layer also generates repo-local launchers under `.agent-layer/` (for example `open-vscode.command` and `open-vscode.app/`). These are kept untracked by `.agent-layer/.gitignore`.

For full detail, see [/docs/reference#sync](/docs/reference#sync).

## Why does Codex ask me to sign in again per repo?
The Codex VS Code extension reads `CODEX_HOME` at startup. Agent Layer sets a repo-specific value via its launchers, so Codex authentication state is stored per repository. When you open VS Code in a different repository, reauthentication is expected.

If you prefer to avoid the VS Code launcher for Codex, use the global MCP fallback so VS Code can continue to discover your MCP servers. See [/docs/troubleshooting#global-mcp-server-fallback-for-vs-code-codex](/docs/troubleshooting#global-mcp-server-fallback-for-vs-code-codex).

## Why doesn't Claude keep separate sign-ins per repo?
Claude per-repo settings and caches isolation is opt-in. If you set `local_config_dir = true` under `[agents.claude]` in `config.toml`, Agent Layer sets `CLAUDE_CONFIG_DIR` to a repo-local directory, isolating settings and caches per repository.

**Known upstream limitation:** Claude Code currently stores auth credentials in the OS credential store (macOS Keychain service `"Claude Code-credentials"`; Linux libsecret/gnome-keyring) regardless of `CLAUDE_CONFIG_DIR`, so authentication is always shared globally. Per-repo login isolation (e.g., separate work and personal accounts) does not work until this is fixed upstream. This has been reported to the Claude Code team.

For VS Code, keep `[agents.claude_vscode] enabled = true` so the extension receives the repo-local `CLAUDE_CONFIG_DIR`. Without the launcher path, VS Code falls back to global `~/.claude/` behavior.

By default (`local_config_dir` absent or `false`), Claude uses your global `~/.claude/` configuration and settings are shared across repositories.

For Claude-specific fallback details, see [/docs/troubleshooting#global-config-fallback-for-vs-code-claude](/docs/troubleshooting#global-config-fallback-for-vs-code-claude).

## Should we commit `.agent-layer/`?
By default it is gitignored, but teams can choose to commit it (except `.agent-layer/.env`).

- Commit when you want shared, stable behavior across the team.
- Keep it ignored for local-only experiments.

If you commit it, keep `.agent-layer/.gitignore` so launchers and backups stay untracked.

## Where do secrets go?
Secrets go in `.agent-layer/.env` and are always gitignored. Only variables with the `AL_` prefix are loaded from `.env`.

Your existing environment variables take precedence over `.env` entries.

## Does Agent Layer use the network?
Agent Layer itself uses the network for update checks and pinned-version downloads (unless `AL_NO_NETWORK=1` is set).

If you enable MCP servers, `al doctor` and your agents will also connect to those servers.

See [/security](/security) for a precise breakdown.

## Where should I ask for help?
Open a GitHub issue:

- [GitHub Issues](https://github.com/conn-castle/agent-layer/issues)

If you're not sure whether something is a bug or "just usage", it's still fine to file an issue. Include your `al --version` and the output of `al doctor` (redact secrets).

See [/docs/troubleshooting](/docs/troubleshooting) for common fixes first.

## How do MCP servers work?
You define servers in `.agent-layer/config.toml`. Agent Layer runs exactly the command or URL you configure; it does not install runtimes for you.

If a server uses `npx` or `uvx`, you must have those tools installed.

## Why do MCP servers fail to start in VS Code on macOS?
If MCP servers that use `npx` fail to start, VS Code may not see a user-directory Node install. Install Node via Homebrew (`brew install node`) so GUI apps can find `node` and `npx`, and avoid per-user installs that only exist in shell profiles.

## Why did some VS Code settings disappear after `al sync`?
Some VS Code extensions (for example Peacock) write settings through the VS Code configuration API in a way that can land inside the Agent Layer-managed block in `.vscode/settings.json`.

If that happens, Agent Layer replaces the managed block on the next `al sync`, and those extension-written settings are removed.

Use the full repair steps in [/docs/troubleshooting#vs-code-settings-disappear-after-sync](/docs/troubleshooting#vs-code-settings-disappear-after-sync).

## Can I pin a repo to a specific version?
Yes. `.agent-layer/al.version` is the repo pin (required). Set it to `X.Y.Z` or `vX.Y.Z`, or set an initial pin during `al init` with `--version`. You can temporarily override the pin with `AL_VERSION`.

See [/docs/concepts#version-pinning](/docs/concepts#version-pinning) for the full model and tradeoffs.

## How do I upgrade a repo?
Upgrade the global CLI first, then run `al upgrade plan` and `al upgrade` inside the repo. This updates the repo pin (`.agent-layer/al.version`) to match the currently installed `al` version.

For the full upgrade contract, compatibility guarantees, and release migration rules, see [/docs/upgrades](/docs/upgrades). For a one-page runbook, use [/docs/upgrade-checklist](/docs/upgrade-checklist).

## What happens if I edit a generated file?
It will be overwritten the next time you run `al sync` or `al <client>`. Always edit the source files in `.agent-layer/` instead.

See [/docs/reference#sync](/docs/reference#sync) for what is considered generated.

## Can I disable the wizard?
Yes. Use `al init --no-wizard` to skip the prompt or run `al wizard` later if you change your mind.

See [/docs/reference#wizard](/docs/reference#wizard) for what it edits.

## Is this safe for teams with strict security requirements?
Yes, if you configure it accordingly. Set `approvals.mode` to limit automatic approvals, keep command allowlists tight, and enable only trusted MCP servers.

Agent Layer does not install or sandbox MCP servers. It runs exactly what you configure, which makes review and auditing straightforward.

## Does Agent Layer ever delete files?
In the default interactive `al upgrade` flow, Agent Layer may prompt about unknown files under `.agent-layer/` and will only delete them if you explicitly approve. For non-interactive or explicit-category apply (e.g., `--yes --apply-managed-updates`), unknown-file deletions require the separate `--apply-deletions` flag.

Files under `.agent-layer/tmp/` (ephemeral agent run artifacts: plans, reports, scratch dumps) are protected by stricter rules. The interactive prompt requires a destructive **double-confirm** that defaults to "no". Non-interactive deletion requires the dedicated `--apply-tmp-deletions` flag — `--apply-deletions` alone never touches tmp content. The interactive "delete all unknowns?" choice is also scoped to skip tmp; the grouped tmp prompt always fires separately. See [/docs/reference#ephemeral-artifacts-under-agent-layertmp](/docs/reference#ephemeral-artifacts-under-agent-layertmp).

## Will rollback restore files I had under .agent-layer/tmp/?
No. Pre-upgrade snapshots intentionally exclude `.agent-layer/tmp/` so they stay small (tmp can accumulate hundreds of MB of agent run artifacts). `al upgrade rollback <snapshot-id>` will not recreate plans, reports, or scratch files that were under tmp. If you need to keep an in-progress agent artifact across an upgrade, copy it out of `.agent-layer/tmp/` first.

See [/docs/upgrades#ephemeral-artifacts-and-rollback-scope](/docs/upgrades#ephemeral-artifacts-and-rollback-scope) for the full contract.
