Skip to main content
Version: 0.17.2

Overview

Agent Layer is a small CLI that keeps AI-assisted development consistent across tools. You define agent instructions, approvals, and MCP servers once in a repo-local .agent-layer/ folder, and al generates each client's native config on demand.

The same repo uses one source configuration whether you launch Antigravity, Claude, Codex, Copilot CLI, Grok, or VS Code. Agent Layer maps it to the closest behavior each client supports; approval enforcement is client-dependent and best effort. You do not copy configuration between clients. You review and refine agent setup in one folder.

Follow the recommended path below to set up Agent Layer, customize it, and find detailed guidance when you need it.

What you get​

  • A .agent-layer/ folder you can treat like code (reviewable, shareable, easy to audit).
  • Generated client files that are safe to delete and recreate (apart from a couple of documented shared-state files that al sync patches in place).
  • Guardrails for autonomy: choose what can run automatically and what must be approved.
  • Built-in workflow skills that give agents structured, repeatable processes for planning, debugging, shipping PRs, and more.
  • Optional version pinning so a team stays on the same behavior across machines and CI.

Who this is for​

  • You use more than one agent client and want them to behave consistently.
  • You want repo-specific safety rules instead of one global configuration for every project.
  • You want to add tools (MCP servers) once and have them available everywhere.
  • You want agent setup to be explicit and reviewable, not a collection of local tweaks.
  1. Getting started - run your first agent
  2. Concepts - learn how Agent Layer works and where the safety boundaries are
  3. Reference - config, environment variables, and CLI behavior
  4. Agent Dispatch - asynchronous, headless provider delegation
  5. Skills - built-in workflows for planning, debugging, shipping, and more
  6. Skills approach - Agent Layer's skill ethos and target root-skill model
  7. Best Practices - universal skill, CLI skill, and instruction design guides
  8. Troubleshooting - common errors and fixes
  9. Upgrades - upgrade event model, compatibility guarantees, and migration rules

Documentation map​

Getting started​

Install Agent Layer, initialize your first repo, and understand what gets generated. Includes: Quick start, Repo layout, and CLI command map.

Concepts​

How Agent Layer keeps agents consistent, and the safety boundaries involved. Includes: Single source of truth, Approvals and safety, MCP servers, Agent Dispatch, Project memory, and Version pinning.

Reference​

Authoritative configuration, environment variables, and CLI behavior. Includes: Configuration, Environment variables, and the CLI guide.

Agent Dispatch​

Asynchronous, headless provider conversations for agents, people, and scripts. Includes: MCP tools, CLI commands, the conversation lifecycle, and timeouts and cancellation.

Skills​

Built-in workflow skills that give agents structured processes for common tasks. Includes: The built-in skill library, Skill categories, Anatomy of a skill, and Writing your own skills.

Skills approach​

Agent Layer's skill ethos, target root modules, workflow boundaries, and mapping from conceptual names to current bundled skill names.

Best Practices​

Research-backed, product-neutral guides for designing agent skills, CLI-focused skills, and always-loaded instructions.

Troubleshooting​

Fast fixes for install, config, and MCP issues. Includes: Install issues, Configuration errors, MCP server issues, and Offline/pinning.

Upgrades​

Upgrade policy and release migration expectations. Includes: Upgrade event model, Compatibility guarantees, Migration rules by release, docs version retention and access, and OS and shell capability matrix.

Other resources​

note

If Agent Layer is useful, consider starring the repository so new users can find it.