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, including canonical directory SKILL.md naming with a compatibility fallback for lowercase skill.md.
Does Agent Layer install Claude/Codex/Gemini/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,GEMINI.md,.github/copilot-instructions.md - Agent config:
.mcp.json,.gemini/settings.json,.claude/settings.json - Codex config and skills:
.codex/ - Antigravity skills:
.agent/skills/ - VS Code integration:
.vscode/mcp.json,.vscode/prompts/, 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.
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.
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.
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 for a precise breakdown.
Where should I ask for help?
Open a GitHub issue:
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 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.
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 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. For a one-page runbook, use /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 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 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.