spacehub

surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

docs: Add skills frontmatter field documentationBrowse files
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
Claude authored on Dec 11, 2025 parent ace0a82 · commit 13530b174783
2 changed files+80 -1compared with ace0a82
Mplugins/plugin-dev/skills/agent-development/SKILL.md
Mplugins/plugin-dev/skills/command-development/references/frontmatter-reference.md
Mplugins/plugin-dev/skills/agent-development/SKILL.md+31 -0
@@ -42,6 +42,7 @@
4242 model: inherit
4343 color: blue
4444 tools: ["Read", "Write", "Grep"]
45+skills: skill-name-1, skill-name-2
4546 ---
4647
4748 You are [agent role description]...
@@ -159,6 +160,35 @@
159160 - Testing: `["Read", "Bash", "Grep"]`
160161 - Full access: Omit field or use `["*"]`
161162
163+### skills (optional)
164+
165+Declare skills to auto-load when this agent is invoked.
166+
167+**Format:** Comma-separated list of skill names
168+
169+```yaml
170+skills: database-migration, postgres-ops
171+```
172+
173+**Purpose:** Ensures specific skills are always available to the agent, regardless of context matching. This is especially useful for:
174+- Skills that should persist across context compaction
175+- Specialized agents that always need certain domain knowledge
176+- Ensuring consistent agent behavior with required skills
177+
178+**Example:**
179+```yaml
180+---
181+name: db-admin
182+description: Use this agent for database administration tasks...
183+model: inherit
184+color: cyan
185+tools: ["Bash", "Read", "Write"]
186+skills: database-migration, sql-optimization
187+---
188+```
189+
190+**Best practice:** Only declare skills essential to the agent's core function. Let context-triggered skills load naturally for optional capabilities.
191+
162192 ## System Prompt Design
163193
164194 The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.
@@ -355,6 +385,7 @@
355385 | model | Yes | inherit/sonnet/opus/haiku | inherit |
356386 | color | Yes | Color name | blue |
357387 | tools | No | Array of tool names | ["Read", "Grep"] |
388+| skills | No | Comma-separated names | skill-a, skill-b |
358389
359390 ### Best Practices
360391
Mplugins/plugin-dev/skills/command-development/references/frontmatter-reference.md+49 -1
@@ -12,6 +12,7 @@
1212 allowed-tools: Read, Write
1313 model: sonnet
1414 argument-hint: [arg1] [arg2]
15+skills: skill-a, skill-b
1516 ---
1617
1718 Command prompt content here...
@@ -321,6 +322,51 @@
321322 - Document why in command comments
322323 - Consider if command should exist if always manual
323324
325+### skills
326+
327+**Type:** String (comma-separated list)
328+**Required:** No
329+**Default:** None
330+
331+**Purpose:** Declare skills to auto-load when this command executes. Ensures specific skills are always available regardless of context matching.
332+
333+**Examples:**
334+```yaml
335+skills: database-migration, sql-optimization
336+```
337+
338+**When to use:**
339+
340+1. **Commands requiring domain knowledge:** Ensure relevant skills load
341+ ```yaml
342+ ---
343+ description: Run database migration
344+ skills: database-migration, postgres-ops
345+ ---
346+ ```
347+
348+2. **Skills that should persist across compaction:** Force-load skills that might otherwise be lost
349+ ```yaml
350+ ---
351+ description: Complex multi-step workflow
352+ skills: workflow-skill, validation-skill
353+ ---
354+ ```
355+
356+3. **Specialized commands:** Commands that always need specific expertise
357+ ```yaml
358+ ---
359+ description: Generate API documentation
360+ skills: api-documentation, openapi-spec
361+ ---
362+ ```
363+
364+**Best practices:**
365+- Only declare skills essential to the command's function
366+- Use skill names exactly as defined in SKILL.md frontmatter
367+- Keep the list focused (2-4 skills max)
368+- Let context-triggered skills load naturally for optional capabilities
369+
324370 ## Complete Examples
325371
326372 ### Minimal Command
@@ -451,6 +497,7 @@
451497 - [ ] model is valid value if specified
452498 - [ ] argument-hint matches positional arguments
453499 - [ ] disable-model-invocation used appropriately
500+- [ ] skills references valid skill names if specified
454501
455502 ## Best Practices Summary
456503
@@ -460,4 +507,5 @@
460507 4. **Choose right model:** Use haiku for speed, opus for complexity
461508 5. **Manual-only sparingly:** Only use disable-model-invocation when necessary
462509 6. **Clear descriptions:** Make commands discoverable in `/help`
463-7. **Test thoroughly:** Verify frontmatter works as expected
510+7. **Declare essential skills:** Use skills field for domain knowledge that must persist
511+8. **Test thoroughly:** Verify frontmatter works as expected