From eb83c2177c2dad8439fa47e864bd3041d5777bc5 Mon Sep 17 00:00:00 2001 From: Matt Bruce Date: Wed, 11 Feb 2026 10:01:38 -0600 Subject: [PATCH] docs: clarify instructions agents skills --- docs/ai/cross-platform.md | 11 +++++++++++ docs/ai/index.md | 2 +- docs/ai/skills.md | 5 +++++ 3 files changed, 17 insertions(+), 1 deletion(-) diff --git a/docs/ai/cross-platform.md b/docs/ai/cross-platform.md index c7a2c89..eaccacd 100644 --- a/docs/ai/cross-platform.md +++ b/docs/ai/cross-platform.md @@ -1,5 +1,12 @@ # Cross-Platform AI Usage +## Instructions (Always-On Rules) +Instructions are repo-scoped rules that auto-apply based on file patterns. They are always on and do not need to be invoked. + +Where they live: +- Repo instructions directory (for example, [instructions/](../../instructions/)) +- Editor or org-level instruction files when configured by your team + ## Agents.md ### What It Is Agents define a structured workflow so tasks are broken into clear steps, with explicit inputs and outputs. @@ -23,6 +30,10 @@ Verification: No tests needed - Use agents for multi-step tasks like refactors, doc audits, or migrations. - Use chat for quick questions or one-off explanations. +## Agents vs Skills (Quick Compare) +- Agents are full modes/personas that control behavior end-to-end. They can be stored in a repo or a user-level folder. +- Skills are focused workflows you load for specific tasks. They are typically installed globally via the approved skills directory. + ## Chat Modes In Copilot Ask: Quick Q and A or summaries. Edit: Targeted file edits with constraints. diff --git a/docs/ai/index.md b/docs/ai/index.md index f81ce05..9f44704 100644 --- a/docs/ai/index.md +++ b/docs/ai/index.md @@ -29,7 +29,7 @@ If you will edit these docs, start with the "Key Repo Files" section in the over - [Android Setup](android.md) ## Usage Guides -- [Cross-Platform AI Usage](cross-platform.md) - Agents, prompting patterns, MCP overview, and workflow tips +- [Cross-Platform AI Usage](cross-platform.md) - Agents, instructions, prompting patterns, MCP overview, and workflow tips - [Skills Library](skills.md) - [Usage and Token Budgeting](usage-tokens.md) - [Troubleshooting and FAQ](troubleshooting.md) diff --git a/docs/ai/skills.md b/docs/ai/skills.md index 76d9d0f..317385e 100644 --- a/docs/ai/skills.md +++ b/docs/ai/skills.md @@ -1,5 +1,10 @@ # Skills Library +## Skills vs Agents vs Instructions +- Skills are reusable workflows you load for specific tasks. +- Agents are full modes/personas that control behavior end-to-end. +- Instructions are always-on repo rules that auto-apply by file pattern. + ## What Skills Are Skills are reusable instructions and workflows that guide the assistant through specialized tasks.