From 2ce0266454f9678710408036c90873fef27121b0 Mon Sep 17 00:00:00 2001 From: Costantino Marcello Date: Thu, 29 Jan 2026 12:15:36 +0000 Subject: [PATCH] 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 --- skill-creator/SKILL.md | 72 +++++++++++++++++++++++++++++ skill-creator/scripts/init_skill.py | 7 +++ 2 files changed, 79 insertions(+) diff --git a/skill-creator/SKILL.md b/skill-creator/SKILL.md index ec98001..2910240 100644 --- a/skill-creator/SKILL.md +++ b/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/`) diff --git a/skill-creator/scripts/init_skill.py b/skill-creator/scripts/init_skill.py index 329ad4e..b51dde7 100755 --- a/skill-creator/scripts/init_skill.py +++ b/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}