Project Structure
This guide explains the layout of the .agloom/ directory and how it maps to generated output files.
Canonical Directory
The .agloom/ directory is the single source of truth for your project's AI agent configuration. Here is the full structure:
.agloom/
├── config.yml # Project configuration (adapters, plugins, variables)
├── instructions/
│ └── AGLOOM.md # Instructions for AI agents
├── skills/ # Reusable skill definitions
│ └── my-skill/
│ ├── SKILL.md
│ └── helpers.ts
├── agents/ # Sub-agent definitions
│ └── reviewer.md
├── commands/ # Slash-command definitions
│ ├── deploy.md
│ └── git/
│ └── commit.md
├── docs/ # Documentation files for agents
├── schemas/ # JSON/OpenAPI schemas for agents
├── mcp.yml # MCP server configuration
├── permissions.yml # Agent permissions
└── overlays/ # Per-adapter overrides
├── claude/
└── opencode/
What Each Part Does
config.yml -- project configuration. Lists which adapters to use, which plugins to load, and project-level variables. This is the only required file.
instructions/ -- contains AGLOOM.md, the canonical instructions file. This is where you write project conventions, stack descriptions, and coding guidelines that AI agents should follow.
skills/ -- reusable action definitions. Each skill is a directory containing a SKILL.md file and any supporting files. Skills are copied to each adapter's skill directory during transpilation.
agents/ -- sub-agent definitions. Each agent is a single .md file with YAML frontmatter describing the agent's role, model, and tools.
commands/ -- slash-command definitions. Each command is a single .md file with YAML frontmatter and a Markdown body. Commands may be organized into subdirectories (e.g., commands/git/commit.md). During transpilation, commands are transformed and written to each adapter's commands directory. See Skills and Agents for details on creating commands.
docs/ -- documentation files that agents can reference. Copied to each adapter's docs directory.
schemas/ -- JSON or OpenAPI schema files. Copied to each adapter's schemas directory.
mcp.yml -- MCP (Model Context Protocol) server configuration. Transpiled into adapter-specific formats (.mcp.json for Claude, opencode.json for OpenCode). See reference/transpilers for details.
permissions.yml -- agent permissions configuration. Transpiled into adapter-specific formats. See reference/transpilers for details.
overlays/ -- per-adapter override files. Files placed here are copied directly to the project root after transpilation. Use overlays for adapter-specific config that does not fit the canonical format. See Overlays for details.
Generated Files
Each adapter generates different output files. Here is what you get:
| Adapter | Generated files |
|---|---|
claude | CLAUDE.md, .claude/skills/, .claude/agents/, .claude/commands/, .claude/docs/, .claude/schemas/, .mcp.json |
opencode | opencode.json, .opencode/skills/, .opencode/agents/, .opencode/commands/, .opencode/docs/, .opencode/schemas/ |
agentsmd | AGENTS.md (generated automatically as a dependency) |
kilocode | .kilo/skills/, .kilo/agents/, .kilo/commands/, .kilo/docs/, .kilo/schemas/ |
codex | .agents/skills/, .codex/agents/ |
gemini | GEMINI.md, .gemini/skills/, .gemini/agents/, .gemini/commands/, .gemini/docs/, .gemini/schemas/ |
Note that agentsmd is a hidden adapter -- you do not configure it directly. It is included automatically when you use opencode, kilocode, or codex (which depend on it for AGENTS.md generation).
Important Rule
Never edit generated files directly. Always edit the canonical files in .agloom/ and run agloom transpile. Generated files are overwritten on every transpile run.
.gitignore
It is recommended to commit the .agloom/ directory to version control and add generated files to .gitignore:
# Generated by agloom
CLAUDE.md
AGENTS.md
GEMINI.md
.mcp.json
opencode.json
This way, your team shares the canonical source and each developer generates output locally.