> ## Documentation Index
> Fetch the complete documentation index at: https://docs.charlielabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENTS.md instructions

> Write durable repo instructions that Charlie loads by default.

Charlie reads shared repository instructions from `AGENTS.md` and Charlie-specific instructions from scoped `CHARLIE.md` files.

For most teams, the best setup is a single **root-level** `AGENTS.md` that defines your default operating rules for planning, coding, reviews, and communication.

Use a root-level `CHARLIE.md`, or `CHARLIE.md` files anywhere under the root `.agents/` directory, for routing or instruction guidance meant specifically for Charlie. Charlie does not load `CHARLIE.md` from other paths such as `apps/foo/CHARLIE.md` or `foo/.agents/CHARLIE.md`.

## Instructions template

Use this compact template and keep rules stable over time:

````md theme={null}
# <Section Title>

## Scope
- Paths, packages, or contexts this section applies to.

## Context
- Team- or domain-specific background Charlie should know.

## Rules
- [R1] <Clear imperative rule>
- [R2] <Clear imperative rule>
- [R3] <Clear imperative rule>

## Examples

### Good
- [R1]
```ts
// minimal example
```

### Bad
- [R2]
```ts
// anti-pattern
```
````

## Instructions vs. skills

* **Instructions (`AGENTS.md` and scoped `CHARLIE.md`)** define persistent policy and defaults. Use `CHARLIE.md` only when the guidance is specific to Charlie.
* **Skills (`.agents/skills/*/SKILL.md`)** define reusable task-shaped playbooks you invoke with `$<skill-name>`.

Use instructions for durable rules. Use skills for repeatable workflows.

## Common mistakes to avoid

* Putting task-by-task checklists in instruction files (that belongs in skills).
* Duplicating the same rule across multiple files.
* Writing vague guidance without a default action.

## Related docs

* [Skills](/skills)
* [How it works](/how-it-works)