docs(skill-creator): Add comprehensive YAML frontmatter reference (#6)

Add documentation for all available YAML frontmatter fields, with special
emphasis on `context: fork` which is critical for skills that subagents
should be able to use via the Task tool.

Changes:
- Add YAML Frontmatter Reference section to SKILL.md with complete field table
- Document when to use `context: fork` for subagent-accessible skills
- Add invocation control comparison table
- Update init_skill.py template with commented optional frontmatter fields

This addresses a gap where skills created without `context: fork` could not
be used by subagents, limiting the skill's usefulness in multi-agent workflows.

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

skill-creator/SKILL.md

@@ -43,6 +43,78 @@ skill-name/
 
 **Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when...").
 
+##### YAML Frontmatter Reference
+
+All frontmatter fields except `description` are optional. Configure skill behavior using these fields between `---` markers:
+
+```yaml
+---
+name: my-skill
+description: What this skill does and when to use it. Use when...
+context: fork
+agent: Explore
+disable-model-invocation: true
+allowed-tools: Read, Grep, Bash(git *)
+---
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | No | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters). |
+| `description` | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. |
+| `context` | No | **Set to `fork` to run in a forked subagent context.** This is critical for skills that should be available to subagents spawned via the Task tool. Without `context: fork`, the skill runs inline in the main conversation. |
+| `agent` | No | Which subagent type to use when `context: fork` is set. Options: `Explore`, `Plan`, `general-purpose`, or custom agents from `.claude/agents/`. Default: `general-purpose`. |
+| `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with `/name`. Default: `false`. |
+| `user-invocable` | No | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`. |
+| `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. Example: `Read, Grep, Bash(git *)`. |
+| `model` | No | Model to use when this skill is active. |
+| `argument-hint` | No | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`. |
+| `hooks` | No | Hooks scoped to this skill's lifecycle. See Claude Code Hooks documentation for configuration format. |
+
+##### When to Use `context: fork`
+
+Use `context: fork` when the skill:
+- Performs multi-step autonomous tasks (research, analysis, code generation)
+- Should be available to subagents spawned via the Task tool
+- Needs isolated context that won't pollute the main conversation
+- Contains explicit task instructions (not just guidelines or reference content)
+
+**Example: Task-based skill with subagent execution:**
+```yaml
+---
+name: deep-research
+description: Research a topic thoroughly using multiple sources
+context: fork
+agent: Explore
+---
+
+Research $ARGUMENTS thoroughly:
+1. Find relevant files using Glob and Grep
+2. Read and analyze the code
+3. Summarize findings with specific file references
+```
+
+**Example: Reference skill that runs inline:**
+```yaml
+---
+name: api-conventions
+description: API design patterns for this codebase
+---
+
+When writing API endpoints:
+- Use RESTful naming conventions
+- Return consistent error formats
+```
+
+##### Invocation Control
+
+| Frontmatter | You can invoke | Claude can invoke | Subagents can use |
+|-------------|----------------|-------------------|-------------------|
+| (default) | Yes | Yes | No (runs inline) |
+| `context: fork` | Yes | Yes | Yes |
+| `disable-model-invocation: true` | Yes | No | No |
+| `context: fork` + `disable-model-invocation: true` | Yes | No | Yes (when explicitly delegated) |
+
 #### Bundled Resources (optional)
 
 ##### Scripts (`scripts/`)

skill-creator/scripts/init_skill.py

@@ -18,6 +18,13 @@ from pathlib import Path
 SKILL_TEMPLATE = """---
 name: {skill_name}
 description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
+# ─── OPTIONAL FIELDS (uncomment as needed) ───
+# context: fork                    # Run in subagent context. IMPORTANT: Required for skills that subagents should use via Task tool
+# agent: Explore                   # Subagent type when context: fork (Explore, Plan, general-purpose, or custom)
+# disable-model-invocation: true   # Only allow manual /skill-name invocation, prevent auto-triggering
+# user-invocable: false            # Hide from / menu (for background knowledge only)
+# allowed-tools: Read, Grep        # Tools allowed without permission prompts
+# argument-hint: [filename]        # Autocomplete hint for arguments
 ---
 
 # {skill_title}