Instructions

Agent instructions are markdown files committed to your repo that tell Capy how to work in your codebase: how to build and test, which conventions to follow, and what to avoid. Capy reads the same AGENTS.md files used by other coding agents, so if you already maintain them, Capy works with zero setup.

How instructions are loaded

Capy loads instructions from three sources with different timing:

Source	Files	When it’s loaded
Root instructions	`AGENTS.md` or `CLAUDE.md` at the repo root	Thread start
Nested instructions	`AGENTS.md` in any subdirectory	First time the agent touches a file in that directory’s subtree
Glob rules	`.capy/rules/.{md,mdc}`, `.cursor/rules/.{md,mdc}`	Thread start if `alwaysApply: true`, otherwise on first matching file touch

Root instructions

Every agent reads the repo root’s AGENTS.md, falling back to CLAUDE.md when no AGENTS.md exists. Per-agent instruction files (.capy/BUILD.md, .capy/CAPTAIN.md, .capy/REVIEW.md) are deprecated and no longer read; put agent guidance in AGENTS.md, nested files, or glob rules instead.

Nested AGENTS.md

An AGENTS.md anywhere below the repo root is discovered automatically. It isn’t loaded at thread start; it’s injected into context the first time the agent reads, edits, searches, or lists a file inside that directory’s subtree. A thread that never enters packages/api/ never pays the context cost of packages/api/AGENTS.md. Behavior to know:

Lazy, then sticky. Each nested file is injected at most once per thread, on first contact with its subtree.
Deeper wins. When instructions conflict, a more deeply nested AGENTS.md takes precedence over shallower ones (and nested files add to, not replace, the root file).
File tools only. Injection is triggered by file-level operations: reading, editing, searching, and listing files. Shell commands do not trigger nested injection, so a repo-wide grep from the terminal won’t pull in every nested file at once.
Plain markdown. The whole file is treated as instructions. Frontmatter is not parsed; if you need globs or alwaysApply, use a glob rule instead.

Discovery follows git: only tracked files are found, so anything gitignored never enters context. Root instructions and skill descriptions share one context budget; oversized content is truncated or shortened with a visible marker rather than silently dropped.

Glob rules

Capy reads Cursor-style rules from .capy/rules/ and .cursor/rules/ (.md or .mdc files). YAML frontmatter controls when each rule loads: a rule needs alwaysApply: true or at least one globs pattern to be injected:

---
description: SQL migration conventions
globs:
  - "**/*.sql"
alwaysApply: false
---

- Every migration must be reversible
- Never drop columns without an explicit approval comment

alwaysApply: true loads at thread start
globs injects the first time the agent touches a matching file
Rules are injected with their file path attached, and each rule is injected at most once per thread

Use .capy/rules/ for Capy-native rules; .cursor/rules/ is read natively so existing Cursor setups work unchanged.

Skills

For deep, on-demand workflows (deploy runbooks, codegen procedures, large reference material), use skills instead of instruction files. Skills advertise only their name and description until an agent decides to load one, so they cost almost nothing when unused. Instruction files answer “how should you always behave here?”; skills answer “how do I do this specific thing?”.

What goes where

The failure mode to avoid is one giant root file that every thread pays for. Match each piece of guidance to the narrowest mechanism that still reaches it:

Guidance	Put it in	Why
Stack summary, build/test/format commands, PR conventions, hard rules	Root `AGENTS.md`	Every thread needs it
Per-package architecture, domain rules, local commands	Nested `AGENTS.md` in that package	Only loaded when working there
File-type conventions that cut across directories (`*/.sql`, `*/.tsx`)	Glob rule	Directory-scoped files can’t express “all SQL files”
Multi-step workflows, long reference docs	Skill	Loaded on demand, keeps always-on context lean

Root AGENTS.md carries cross-cutting truths: what the project is, how to install/build/test/lint, commit and PR conventions, and non-negotiable rules (“always use pnpm”, “never commit generated files”). Keep it lean: a bloated root file taxes every request in every thread, and long instruction files dilute the agent’s attention on the rules that matter. Nested AGENTS.md carries what’s true only inside a subtree. In a monorepo, keep the top-level file general and add a specific AGENTS.md per major subproject: packages/api/AGENTS.md for API conventions, packages/web/AGENTS.md for frontend rules. This is the same layout Amp and other agents recommend, so one set of files serves every tool. Glob rules carry concerns that follow a file type rather than a directory: design-token rules for every .tsx file, migration rules for every .sql file. If the concern maps cleanly to one directory, prefer a nested AGENTS.md there instead.

Anti-patterns

Duplicating a rule in multiple files. State it once in the narrowest scope that covers it. Duplicates drift, and the agent has to reconcile conflicting copies.
Restating what the code already says. Don’t enumerate exports, list every directory, or paraphrase type signatures; the agent reads code. Document what it can’t infer: intent, invariants, and commands.
Prompt-sized essays. Ten sharp bullets outperform three pages of prose. “Use pnpm, not npm” beats “please make sure to use the correct package manager for this project”.
Secrets or credentials. Instruction files are committed to the repo and injected into model context. Never put tokens, passwords, or internal URLs that shouldn’t leak into them.
Per-file trivia. “This function retries three times because the upstream API flakes” belongs in a code comment next to the function, not in an instruction file.

Examples

A lean root AGENTS.md

# AGENTS.md

Acme is a TypeScript monorepo: `packages/api` (Fastify + Postgres), `packages/web` (React + Vite), `packages/shared` (types and utils).

## Commands

- Install: `pnpm install`
- Build: `pnpm build`
- Test: `pnpm test` (single package: `pnpm --filter @acme/api test`)
- Lint + format: `pnpm check`; run before finishing any task

## Rules

- Always use pnpm, never npm or yarn
- No `any` types; fix type errors instead of suppressing them
- New env vars must be added to `.env.example` and `packages/shared/src/env.ts`
- PR titles follow `type(scope): description` (e.g. `fix(api): handle null user`)

A nested packages/api/AGENTS.md

# API package

Fastify server with route handlers in `src/routes/`, business logic in `src/services/`, and data access in `src/db/`.

- Route handlers validate input with zod schemas from `src/schemas/` and stay thin; logic lives in services
- All queries go through the repository layer in `src/db/`; never import the client directly in a route or service
- Every table uses soft deletes (`deleted_at`); filter it in every query
- Integration tests live in `src/__tests__/` and run against the Docker Postgres from `pnpm db:test`

A glob rule

---
description: Design token rules for React components
globs:
  - "**/*.tsx"
---

- Use tokens from `packages/web/src/styles/tokens.css`, never raw hex colors or arbitrary Tailwind values
- Spacing comes from the `--space-*` scale; font sizes from `text-sm` through `text-2xl` only

Migrating from other tools

From Claude Code: nothing required; Capy reads root CLAUDE.md as a fallback. To standardize on AGENTS.md while keeping Claude Code working: mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
From Cursor: keep .cursor/rules/ where it is; Capy reads it natively, including globs and alwaysApply frontmatter
From other agents using AGENTS.md (Amp, Codex, Devin, …): nothing required; root and nested AGENTS.md files work as-is

Changes to instruction files apply to the next thread or task.

Get started

Agent

Workspace

Integrations

Account

Resources

How instructions are loaded

Root instructions

Nested AGENTS.md

Glob rules

Skills

What goes where

Anti-patterns

Examples

A lean root AGENTS.md

A nested packages/api/AGENTS.md

A glob rule

Migrating from other tools

​How instructions are loaded

​Root instructions

​Nested AGENTS.md

​Glob rules

​Skills

​What goes where

​Anti-patterns

​Examples

​A lean root AGENTS.md

​A nested packages/api/AGENTS.md

​A glob rule

​Migrating from other tools

How instructions are loaded

Root instructions

Nested AGENTS.md

Glob rules

Skills

What goes where

Anti-patterns

Examples

A lean root AGENTS.md

A nested packages/api/AGENTS.md

A glob rule

Migrating from other tools