From 0fc9f44de5643692d7e2a7950c122835c006b672 Mon Sep 17 00:00:00 2001 From: Steve Nims Date: Sun, 7 Dec 2025 20:48:19 -0500 Subject: [PATCH] docs(agent-development): improve visibility of tools vs allowed-tools disambiguation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add prominent callouts to clarify the difference between `tools` (agents) and `allowed-tools` (skills) in two key locations: 1. Overview section - early visibility for users scanning the document 2. tools field section - contextual help when configuring tool restrictions This addresses user confusion when switching between agent and skill development. Fixes #24 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- plugins/plugin-dev/skills/agent-development/SKILL.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md index 400e848..5bc7890 100644 --- a/plugins/plugin-dev/skills/agent-development/SKILL.md +++ b/plugins/plugin-dev/skills/agent-development/SKILL.md @@ -16,6 +16,8 @@ Agents are autonomous subprocesses that handle complex, multi-step tasks indepen - System prompt defines agent behavior - Model and color customization +> **⚠️ Field Name Difference:** Agents use `tools` to restrict tool access. Skills use `allowed-tools` for the same purpose. Don't confuse these when switching between component types. + ## When to Use Agents vs Commands vs Skills | Component | Best For | Triggering | Example Use Case | @@ -199,6 +201,8 @@ tools: ["Read", "Write", "Grep", "Bash"] - Testing: `["Read", "Bash", "Grep"]` - Full access: Omit field or use `["*"]` +> **Important:** Agents use `tools` while Skills use `allowed-tools`. The field names differ between component types. For skill tool restrictions, see the `skill-development` skill. + ## System Prompt Design The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.