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

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