Configuration is taken from the highest step of one ladder, built-ins, a pod's bundle, .agents/, AGENTS.md, the person's <config>/, the repository's .troupe/, and .agents/ is read as .agents/skills and .agents/AGENTS.md only¶
Decision 822 · accepted · 2026-10-09 · issue #516
- What
.agents/is. The maintainer's choice (#516's second decision):.agents/means.agents/skills/and.agents/AGENTS.md, and nothing else. - The ladder, lowest first: Troupe's built-ins; a profile's bundle, on a pod;
.agents/;AGENTS.md, the root's then each directory's on the way to the work; the person's<config>/; the repository's.troupe/. What has a name (an agent, a skill, a command, an MCP server) comes from the highest step that has it; instruction files all apply, the higher later in the prompt and kept whole first. .agents/skillsis a layer, read in place. Below Troupe's own two (<config>/skills,.troupe/skills, Decision 700):~/.agents/skillslowest (user_agents), then each.agents/skillsfrom the repository root down to the workspace (agents), the nearest highest, the root being the one the instruction files are read up to (Troupe.Instructions.repository_root/1: the nearest directory with a.git, or the workspace). Not chosen: copying.agents/skillsinto.troupe/skills(a second copy that goes stale, and a write nobody asked for); reading.agents/skillsbelow the workspace as the conversation works there (skills are offered when the session starts, and the convention scans up, not down);~/.agentsabove the repository's (the person's own layer is below the repository's everywhere else,<config>/under.troupe/).- A name lost is listed, with why.
resolve/2answers what is offered and every skill the layers hold and do not offer, in ladder order:skipped, withskipped: <dir> is usednaming the directory of the one offered, when a higher step has the name (between Troupe's two layers, and a layer's link against its own directory, too, as they always shadowed);skippedwithnot a skill namefor an.agents/skillsfolder no skill may be called;outsidefor one not read. - Confined by real path, as instruction files are (Decision 798): a repository's
.agents/skillsis held to the repository root and~/.agents/skillsto~/.agents. An.agents/skillsthat is a link out is listed once, with no name, and not looked into, so not even the names of what is there are said; a skill folder or aSKILL.mdlinked out isoutsideand its front matter is never read, nor its directory made a read root. .agents/AGENTS.mdis an instruction file of its directory. In the repository root and in each directory on the way to where the session works (798's directories), read right before that directory's own file (the alias chosen there) and in its scope, so it is the farther of the two and the directory's own wins where they disagree; in the budget it is a scope of its own, cut before the directory's own file.- The person's own
<config>/AGENTS.mdstays first. Instruction files have no name to lose, and Decisions 706 and 798 read the person's own file first, below the repository's, as every other tool reads its user-level file: it is about every repository, and the repository's is about this one, so where they disagree the repository's wins and the budget keeps it whole first.
Governs: apps/troupe_core/lib/troupe/skills/local.ex, apps/troupe_core/lib/troupe/instructions.ex, apps/troupe_gateway/lib/troupe/gateway/local_sources.ex