From b39ce9cb65ac45d221ed3e5a3cbe8c4989f47d4d Mon Sep 17 00:00:00 2001 From: Matt Bruce Date: Wed, 11 Feb 2026 09:58:59 -0600 Subject: [PATCH] docs: explain agents.md vs instructions --- docs/ai/overview.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/ai/overview.md b/docs/ai/overview.md index 7456e72..ab9ea7b 100644 --- a/docs/ai/overview.md +++ b/docs/ai/overview.md @@ -60,6 +60,11 @@ Where they live: Instructions are always-on defaults. Agents and skills are optional and only used when you explicitly invoke them. +## Agents.md vs Instructions +Agents.md is a human-readable contributor guide for how to work in this repo (request format, plan-first habits, and sync expectations). It does not apply automatically. + +Instructions files are machine-readable rules that auto-apply when you edit matching files. They are enforced by the assistant without you having to reference them. + ## Agents vs Skills (Where They Live) Agents are full personas or modes (for example, Task Researcher) that control how the assistant behaves end-to-end. Skills are focused, reusable workflows (for example, webapp-testing) that the assistant can load for a specific task.