configuration

All configuration is TOML. ACE merges multiple layers into one effective config, with later layers overriding earlier ones.

layer merge order

# 1. School defaults (read-only, from school.toml)
# 2. User-global config
~/.config/ace/ace.toml

# 3. Project config (checked into git, shared)
ace.toml

# 4. Project-local config (gitignored, per-machine)
ace.local.toml

ace.toml / ace.local.toml

Project and local config share the same schema. Local config is gitignored and holds machine-specific values like trust level.

# ace.toml example
school = "ace-rs/school"
backend = "claude"
trust = "auto"
session_prompt = "Always run tests before committing."

[env]
RUSTFLAGS = "-D warnings"

Three fields control which of the school's skills are loaded by the backend at session start. Each has one consistent rule across all scopes; the field name signals intent, the scope is mechanical.

Resolution: effective = (skills_base − exclude_skills) ∪ include_skills. Exclude is applied before include, so include_skills is authoritative when an item appears in both.

# user ace.toml — global "always-add" preferences
include_skills = ["issue-*"]

# project ace.toml — this repo only needs rust-coding
skills = ["rust-coding"]

# ace.local.toml — opt out of a global include just for this repo
exclude_skills = ["issue-*"]

Glob patterns use * as a wildcard (no ** or character classes). Foreign entries in <backend>/skills/ (real files or symlinks pointing outside the school clone) are left alone unless their name collides with a desired skill, in which case the link is skipped with a warning.

CLI

ace skills [--all] [--names]              # list resolved skills
ace skills include <pattern>...           # append to include_skills
ace skills exclude <pattern>...           # append to exclude_skills
ace skills reset [--include] [--exclude]  # set list(s) back to empty
ace explain <name>                        # provenance + trace for one skill

Mutating verbs default to project scope; pass --user or --local to target another layer. There is no ace skills set verb — the skills whitelist is config-only; edit ace.toml directly. The CLI exposes the union-merge fields because those are what users typically tweak per session.

user-global ace.toml

Same schema as project ace.toml. Holds your personal defaults across every ACE-managed repo — typically trust, resume, or a fallback school and backend. Project config overrides it; local config overrides project.

# ~/.config/ace/ace.toml
school = "ace-rs/school"
trust = "auto"
resume = true

school.toml

Lives at the root of a school repository. Defines the school name, backend preference, MCP servers, projects, and skill imports.

# school.toml example
name = "acme-school"
backend = "claude"
session_prompt = "Follow ACME conventions."

[env]
EDITOR = "nvim"

[[mcp]]
name = "github"
url = "https://mcp.example.com/github"
instructions = "Use for all GitHub operations."

[mcp.headers]
Authorization = "Bearer {{ github_token }}"

[[projects]]
name = "ace"
repo = "ace-rs/ace"
description = "ACE CLI and backend integration code."

[[imports]]
skill = "docker"
source = "ace-rs/school"

[[imports]]
skill = "*"
source = "company/school"
include_experimental = true

top-level keys

[[mcp]]

MCP (Model Context Protocol) server declarations. Each entry registers an MCP server for the backend to use.

[[projects]]

Optional project catalog entries that give the AI context about available repositories.

[[imports]]

Import skills from other school repositories. Skill discovery scans four tiers under skills/: the default skills/<name> and skills/.curated/<name> (both Curated), plus skills/.experimental/ and skills/.system/. Explicit names resolve from any tier. Glob patterns match only Curated by default.

placeholder syntax

String values in config (currently MCP headers) support placeholder substitution. Placeholders are resolved at runtime by prompting the user.

# Prompts user for "github_token" on first run
Authorization = "Bearer {{ github_token }}"

# Whitespace is flexible
"{{name}}"  "{{ name }}"  "{{  name  }}"  # all equivalent

# Names must be alphanumeric + underscore
"{{ my_api_key_2 }}"  # valid