Skill and Subagent Reference
Quick reference for Claude Code skill and subagent APIs. Always check official docs first - this may be outdated.
Skill Frontmatter Fields (January 2026)
---
name: skill-name # Required: kebab-case
description: "Triggers on: ..." # Required: include trigger keywords
allowed-tools: "Read Write Bash" # Restrict available tools
disable-model-invocation: false # true = manual /skill only
user-invocable: true # false = hide from slash completion
context: main # main | fork (subagent isolation)
agent: custom-agent # Custom system prompt agent
hooks:
preToolUse:
- command: "echo pre"
postToolUse:
- command: "echo post"
---
Subagent Options
| Field |
Values |
Purpose |
permissionMode |
default, acceptEdits, bypassPermissions |
Control autonomy |
skills |
[skill-names] |
Preload skills in subagent |
model |
sonnet, opus, haiku |
Override model |
Decision Framework: Main Context vs Fork
| Question |
If Yes → |
If No → |
| Needs current session state (tasks, conversation)? |
Main context |
Consider fork |
| Output verbose (>500 lines)? |
Consider fork |
Main context |
| Needs user interaction during execution? |
Main context |
Consider fork |
| One-shot research/analysis task? |
Fork |
Main context |
Skills Using Subagent Isolation
| Skill |
Method |
Why |
introspect |
Task agent (background) |
Session log analysis is verbose |
Session Commands Analysis
| Command |
Context |
Rationale |
/sync |
Main |
Must restore session state (tasks, context) |
/save |
Main |
Must access current tasks via TaskList |
/canvas |
Main |
Interactive TUI requires real-time feedback |
These MUST run in main context - subagent isolation would break their core functionality.
