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
This commit is contained in:
Claude
2025-12-11 10:39:03 +00:00
parent ace0a82778
commit 13530b1747
2 changed files with 80 additions and 1 deletions

View File

@@ -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