From 13530b174783aaf9669be0368fbe113e000f4c9d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 11 Dec 2025 10:39:03 +0000
Subject: [PATCH] docs: Add skills frontmatter field documentation

Document the `skills` frontmatter field added in v2.0.43 for declaring
skills to auto-load for subagents and commands. This helps ensure skills
persist across context compaction by explicitly declaring required skills.

- Add skills field to agent-development SKILL.md frontmatter fields section
- Add skills field to command-development frontmatter-reference.md
- Update examples, validation checklists, and best practices
---
 .../skills/agent-development/SKILL.md         | 31 ++++++++++++
 .../references/frontmatter-reference.md       | 50 ++++++++++++++++++-
 2 files changed, 80 insertions(+), 1 deletion(-)

diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md
index 36830932..e0b2e45f 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"]
+skills: skill-name-1, skill-name-2
 ---
 
 You are [agent role description]...
@@ -159,6 +160,35 @@ tools: ["Read", "Write", "Grep", "Bash"]
 - Testing: `["Read", "Bash", "Grep"]`
 - Full access: Omit field or use `["*"]`
 
+### skills (optional)
+
+Declare skills to auto-load when this agent is invoked.
+
+**Format:** Comma-separated list of skill names
+
+```yaml
+skills: database-migration, postgres-ops
+```
+
+**Purpose:** Ensures specific skills are always available to the agent, regardless of context matching. This is especially useful for:
+- Skills that should persist across context compaction
+- Specialized agents that always need certain domain knowledge
+- Ensuring consistent agent behavior with required skills
+
+**Example:**
+```yaml
+---
+name: db-admin
+description: Use this agent for database administration tasks...
+model: inherit
+color: cyan
+tools: ["Bash", "Read", "Write"]
+skills: database-migration, sql-optimization
+---
+```
+
+**Best practice:** Only declare skills essential to the agent's core function. Let context-triggered skills load naturally for optional capabilities.
+
 ## System Prompt Design
 
 The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.
@@ -355,6 +385,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"] |
+| skills | No | Comma-separated names | skill-a, skill-b |
 
 ### Best Practices
 
diff --git a/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md b/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md
index aa852947..5569807b 100644
--- a/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md
+++ b/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md
@@ -12,6 +12,7 @@ description: Brief description
 allowed-tools: Read, Write
 model: sonnet
 argument-hint: [arg1] [arg2]
+skills: skill-a, skill-b
 ---
 
 Command prompt content here...
@@ -321,6 +322,51 @@ disable-model-invocation: true
 - Document why in command comments
 - Consider if command should exist if always manual
 
+### skills
+
+**Type:** String (comma-separated list)
+**Required:** No
+**Default:** None
+
+**Purpose:** Declare skills to auto-load when this command executes. Ensures specific skills are always available regardless of context matching.
+
+**Examples:**
+```yaml
+skills: database-migration, sql-optimization
+```
+
+**When to use:**
+
+1. **Commands requiring domain knowledge:** Ensure relevant skills load
+   ```yaml
+   ---
+   description: Run database migration
+   skills: database-migration, postgres-ops
+   ---
+   ```
+
+2. **Skills that should persist across compaction:** Force-load skills that might otherwise be lost
+   ```yaml
+   ---
+   description: Complex multi-step workflow
+   skills: workflow-skill, validation-skill
+   ---
+   ```
+
+3. **Specialized commands:** Commands that always need specific expertise
+   ```yaml
+   ---
+   description: Generate API documentation
+   skills: api-documentation, openapi-spec
+   ---
+   ```
+
+**Best practices:**
+- Only declare skills essential to the command's function
+- Use skill names exactly as defined in SKILL.md frontmatter
+- Keep the list focused (2-4 skills max)
+- Let context-triggered skills load naturally for optional capabilities
+
 ## Complete Examples
 
 ### Minimal Command
@@ -451,6 +497,7 @@ Before committing command:
 - [ ] model is valid value if specified
 - [ ] argument-hint matches positional arguments
 - [ ] disable-model-invocation used appropriately
+- [ ] skills references valid skill names if specified
 
 ## Best Practices Summary
 
@@ -460,4 +507,5 @@ Before committing command:
 4. **Choose right model:** Use haiku for speed, opus for complexity
 5. **Manual-only sparingly:** Only use disable-model-invocation when necessary
 6. **Clear descriptions:** Make commands discoverable in `/help`
-7. **Test thoroughly:** Verify frontmatter works as expected
+7. **Declare essential skills:** Use skills field for domain knowledge that must persist
+8. **Test thoroughly:** Verify frontmatter works as expected