configuration

Project and local config use the same file format. Local config is gitignored and holds personal settings such as trust and resume; those settings belong in local or user config, and project ace.toml ignores them. Unknown or misplaced fields are reported and ignored.

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

[env]
RUSTFLAGS = "-D warnings"

backend tables

Each [backends.<name>] table declares one backend instance; the table key is the name that backend = "..." and --backend select. Any layer can declare one, including school.toml. The old [[backends]] array with a name field is rejected since 0.9.3: move each name into its table key.

# Override the model of the built-in claude backend
[backends.claude]
model = "opus"

# Custom backend, selected with backend = "work-claude"
[backends.work-claude]
kind = "claude"
effort = "high"

[backends.work-claude.env]
ANTHROPIC_BASE_URL = "https://proxy.example.com"

Custom backends inherit their kind's mapping of model and effort to native flags. Arguments passed after -- come last, so they can override either value for one run. See custom backends.

inspecting and editing

ace config                    # effective config as one TOML document
ace config get <key>          # resolved value of one key
ace config set <key> <value>  # write a key to a layer
ace config explain [key]      # provenance per layer

Keys: school, backend, trust, resume, skip_update, session_prompt, env.<NAME>, backends.<name>.model, and backends.<name>.effort. skills, include_skills, exclude_skills, and exclude_mcp are read-only here: get and explain show them, set rejects them. Pass --user, --project, or --local to pick the layer.

Bare ace config includes backend model/effort and the selection lists; school metadata is not included, so read it from the school's school.toml. ace config set validates before writing and keeps comments, unrelated fields, inline tables, and dotted keys, including fields ACE doesn't recognize. It says when a higher-precedence layer overrides the value you wrote.

skills selection

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 — remove issue-* from the base selection
skills = ["rust-coding", "issue-*"]
exclude_skills = ["issue-*"]

# Result: include_skills wins, so issue-* is still loaded.

Glob patterns use * as a wildcard (no ** or character classes). An invalid pattern is warned and skipped rather than failing the run. 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.

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.

A user-level ace.toml resolves a project on its own: name a school here and a repo needs no ace.toml of its own. When the school comes from the user or local layer rather than the repo, bare ace announces which school it resolved, so a school that isn't the repo's own is never silent.

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

Lives at the root of a school repository. Defines the school name, backend preference, backend tables, 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, and skip skills marked internal: true unless include_internal is set. ace import writes these entries; ace school pull refreshes them.

Several string fields support {{ placeholder }} substitution. Two placeholder families share the same syntax but resolve at different times.

# MCP header — prompts user for "github_token" on first run
Authorization = "Bearer {{ github_token }}"

# Backend cmd — resolves school_dir when ACE resolves the backend
[backends.codex-ace]
kind = "codex"
cmd  = ["{{ school_dir }}/skills/ace-connect/scripts/codex.sh"]

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

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