From 52e3e14a072d7de4d27b81d18495681af5f44b36 Mon Sep 17 00:00:00 2001 From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Date: Fri, 13 Mar 2026 22:15:29 -0700 Subject: [PATCH] docs(agents): add fully-qualified namespace directive to AGENTS.md Prevents future agent resolution failures by requiring skills to use compound-engineering:: instead of short names. Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index e328758..024bb0d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,6 +48,16 @@ Add a new provider when at least one of these is true: Avoid adding a provider if the target spec is unstable or undocumented. +## Agent References in Skills + +When referencing agents from within skill SKILL.md files (e.g., via the `Agent` or `Task` tool), always use the **fully-qualified namespace**: `compound-engineering::`. Never use the short agent name alone. + +Example: +- `compound-engineering:research:learnings-researcher` (correct) +- `learnings-researcher` (wrong - will fail to resolve at runtime) + +This prevents resolution failures when the plugin is installed alongside other plugins that may define agents with the same short name. + ## Repository Docs Convention - **Plans** live in `docs/plans/` and track implementation progress.