Merge branch 'main' into docs/issue-72-exit-conditions

agent-skills/SKILL.md

@@ -66,6 +66,7 @@ The `SKILL.md` file must contain YAML frontmatter followed by Markdown body cont
 | `compatibility` | No | Max 500 chars. Indicates environment requirements. |
 | `metadata` | No | Arbitrary key-value mapping. |
 | `allowed-tools` | No | Space-separated string of pre-approved tools. (Experimental) |
+| `confirmation` | No | Boolean (default: false). Signals destructive operations requiring explicit user confirmation. |
 
 #### `name` field rules
 - 1–64 characters

agent-skills/references/best-practices.md

@@ -186,6 +186,16 @@ Keep gotchas in `SKILL.md` where the agent reads them before encountering the si
   When an agent makes a mistake you have to correct, add the correction to the gotchas section. This is one of the most direct ways to improve a skill iteratively (see [Refine with real execution](#refine-with-real-execution)).
 </Tip>
 
+### Use-when sections
+
+Not every instruction in a skill applies to every task it handles. Mark conditional sections with a `**Applicability:**` line at the start of the section so the agent can skip what does not apply. Keep applicability conditions short and binary.
+
+```markdown
+## Database migration
+
+**Applicability:** Only when the task involves schema changes or data migration.
+```
+
 ### Templates for output format
 
 When you need the agent to produce output in a specific format, provide a template. This is more reliable than describing the format in prose, because agents pattern-match well against concrete structures. Short templates can live inline in `SKILL.md`; for longer templates, or templates only needed in certain cases, store them in `assets/` and reference them from `SKILL.md` so they only load when needed.

agent-skills/references/specification.md

@@ -33,6 +33,7 @@ The `SKILL.md` file must contain YAML frontmatter followed by Markdown content.
 | `compatibility` | No       | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). |
 | `metadata`      | No       | Arbitrary key-value mapping for additional metadata.                                                              |
 | `allowed-tools` | No       | Space-separated string of pre-approved tools the skill may use. (Experimental)                                    |
+| `confirmation` | No | Boolean (default: false). Signals destructive or state-changing operations requiring explicit user confirmation. |
 
 <Card>
   **Minimal example:**
@@ -196,6 +197,10 @@ The optional `allowed-tools` field:
   ```
 </Card>
 
+#### `confirmation` field
+
+The optional `confirmation` field must be a boolean. When `true`, the agent must obtain explicit user confirmation before carrying out destructive or state-changing operations directed by the skill. This is a safety signal, not a permissions system. Most skills should omit it.
+
 ### Body content
 
 The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.
@@ -205,6 +210,7 @@ Recommended sections:
 * Step-by-step instructions
 * Examples of inputs and outputs
 * Common edge cases
+* Applicability conditions for instructions that only apply to a subset of tasks
 
 Note that the agent will load this entire file once it's decided to activate a skill. Consider splitting longer `SKILL.md` content into referenced files.