Undocumented `use-when` frontmatter field in skills - is it supported?

Summary

The use-when field appears in skill SKILL.md frontmatter across multiple projects but is not listed in the official Claude Code documentation for skill frontmatter fields.

Observed Behavior

A mini spike was run to test whether use-when influences skill discovery:

Spike setup: Two identical skills with fictional pattern names (zorblax / quazzle) - one using use-when as a separate frontmatter field, the other packing trigger conditions into description.

Finding: The skill list in system reminders only surfaces description text. The use-when field content was not visible in the skill discovery list. Both skills appeared identically in the system reminder, showing only their description text (truncated at the same point).

This suggests use-when has no effect on skill auto-detection, since Claude never sees it during the "should I invoke this skill?" decision (it only appears in the 2% character budget as description).

Expected Behavior

If use-when is a supported field, it should be documented alongside the other frontmatter fields (description, allowed-tools, model, etc.) at https://code.claude.com/docs/en/skills.

If it's not supported, a note clarifying that trigger conditions should be packed into description (as shown in the patterns skill example with inline "Use when:" text) would prevent confusion.

Documented Frontmatter Fields

From the official docs, the valid SKILL.md frontmatter fields are:

• name
• description
• argument-hint
• disable-model-invocation
• user-invocable
• allowed-tools
• model
• context
• agent
• hooks

use-when is not in this list.

Reproduction

# Skill A - use-when as separate field
---
description: Knows about zorblax patterns for data transformation.
use-when: The user asks about zorblax patterns or zorblax transforms.
allowed-tools: Read
---

# Skill B - trigger conditions in description
---
description: >-
  Knows about quazzle patterns for stream processing.
  Use when: the user asks about quazzle patterns or quazzle streams.
allowed-tools: Read
---

Both appear identically in the system reminder skill list - only description text is shown.

Environment

• Claude Code CLI
• macOS Tahoe 26.2
• Tested 2026-02-22