Instructions

This guide teaches you how to write instructions for AI coding assistants using the canonical AGLOOM.md format.

What Are Instructions

Instructions are AGLOOM.md files placed in your project root or any subdirectory. They contain project-level guidance for AI coding assistants -- your stack, conventions, boundaries, and workflow preferences.

When you run agloom transpile, Agloom discovers all AGLOOM.md files and transforms each one into adapter-specific instruction files (CLAUDE.md, AGENTS.md, GEMINI.md, etc.) at the same relative path, based on your configured adapters.

Basic Instructions

Start by creating a simple AGLOOM.md with content that applies to all agents:

# My Project

## Stack

TypeScript, React, PostgreSQL.

## Conventions

- Use functional components with hooks.
- All API calls go through the `api/` directory.
- Write unit tests for business logic.

## Boundaries

- Never modify database migrations directly -- use the migration generator.
- Never commit `.env` files.

Everything in this file (outside of agent-specific blocks) is included in the output for every adapter.

Agent-Specific Blocks

Sometimes you need instructions that apply only to a particular tool. Use HTML comment tags to define agent-specific sections:

# My Project

All agents see this content.

<!-- agent:claude -->
Claude-specific: Use the Bash tool for file operations.
<!-- /agent:claude -->

<!-- agent:agentsmd -->
For AGENTS.md-compatible tools: Prefer the file search tool.
<!-- /agent:agentsmd -->

This content is also visible to all agents.

When transpiling for Claude, the agentsmd block is removed and the claude block content is included (without the comment tags). When transpiling for AGENTS.md, the reverse happens.

Valid Agent IDs

Only agents that have their own instruction file format can be used in agent-specific blocks:

Agent ID	Instruction file	Can use in blocks
claude	CLAUDE.md	Yes
agentsmd	AGENTS.md	Yes
gemini	GEMINI.md	Yes
opencode	(none)	No
kilocode	(none)	No
codex	(none)	No

opencode, kilocode, and codex do not have their own instruction file format -- they use AGENTS.md (generated by the agentsmd adapter). To write content specific to these tools, use <!-- agent:agentsmd --> blocks.

Using an invalid agent ID in a block (e.g., <!-- agent:opencode -->) will cause a transpilation error.

Multiple Instruction Files

Agloom supports instruction files in subdirectories. If you place an AGLOOM.md in a subdirectory (e.g., src/AGLOOM.md), it will be transpiled to the corresponding location (e.g., src/CLAUDE.md for the Claude adapter).

This lets you provide directory-level instructions that agents pick up when working in specific parts of your codebase.

Example

Here is a complete AGLOOM.md with shared and agent-specific sections:

---
description: Main project instructions
---

# My Web App

## Stack

TypeScript, Next.js 14, Prisma, PostgreSQL.

## Commands

- Build: `pnpm run build`
- Test: `pnpm run test`
- Lint: `pnpm run lint`

## Conventions

- Use server components by default.
- Client components must have the `"use client"` directive.
- All database queries go through Prisma.

<!-- agent:claude -->
## Claude-Specific

- Use the Bash tool to run commands; do not use the terminal directly.
- Prefer the Grep tool over shell grep.
- Read files with the Read tool, not cat.
<!-- /agent:claude -->

<!-- agent:agentsmd -->
## Agents.md Tools

- Use available search tools for code navigation.
- Always verify file existence before editing.
<!-- /agent:agentsmd -->

## Boundaries

- Never modify files in `generated/` -- they are auto-generated.
- Never skip TypeScript strict mode.

The YAML frontmatter is optional. If present, it can contain an override block for adapter-specific frontmatter fields. See reference/transpilers for details on frontmatter overrides.