From 416b2c53c503ae22d92d82e60f58d868f9ee4ced Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 12 Dec 2025 20:06:00 +0000
Subject: [PATCH] docs: add permissionMode field to agent development docs

Document the permissionMode agent frontmatter field (added in v2.0.43)
with kebab-case values for consistency:
- default: inherit from parent conversation
- ask: always prompt for permission
- accept-edits: auto-accept file edits

Note backwards compatibility with camelCase 'acceptEdits' while
establishing kebab-case as the preferred format to match CLI flags.
---
 .../skills/agent-development/SKILL.md         | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md
index 36830932..79ace20f 100644
--- a/plugins/plugin-dev/skills/agent-development/SKILL.md
+++ b/plugins/plugin-dev/skills/agent-development/SKILL.md
@@ -42,6 +42,7 @@ assistant: "[How assistant should respond and use this agent]"
 model: inherit
 color: blue
 tools: ["Read", "Write", "Grep"]
+permissionMode: default
 ---
 
 You are [agent role description]...
@@ -159,6 +160,41 @@ tools: ["Read", "Write", "Grep", "Bash"]
 - Testing: `["Read", "Bash", "Grep"]`
 - Full access: Omit field or use `["*"]`
 
+### permissionMode (optional)
+
+Control how permission prompts are handled for the agent.
+
+**Format:** String
+
+**Options:**
+- `default` - Inherit permission mode from parent conversation (default behavior)
+- `ask` - Always prompt for permission before tool use
+- `accept-edits` - Auto-accept file edits without prompting
+
+```yaml
+permissionMode: accept-edits
+```
+
+**Default:** If omitted, inherits from parent conversation settings
+
+**Backwards compatibility:** `acceptEdits` is also accepted but `accept-edits` (kebab-case) is preferred for consistency with CLI flags.
+
+**Use cases:**
+- Agents performing many file operations: Use `accept-edits`
+- Security-sensitive agents: Use `ask` to ensure oversight
+- General purpose: Omit field to inherit conversation settings
+
+**Example:**
+```yaml
+---
+name: code-generator
+description: Use this agent when...
+model: inherit
+color: green
+permissionMode: accept-edits
+---
+```
+
 ## System Prompt Design
 
 The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.
@@ -355,6 +391,7 @@ Output: [What to provide]
 | model | Yes | inherit/sonnet/opus/haiku | inherit |
 | color | Yes | Color name | blue |
 | tools | No | Array of tool names | ["Read", "Grep"] |
+| permissionMode | No | default/ask/accept-edits | accept-edits |
 
 ### Best Practices