SKILL.md custom frontmatter fields are stripped before showing to model

Resolved 💬 3 comments Opened Dec 3, 2025 by bukzor Closed Dec 7, 2025

Summary

SKILL.md files support custom frontmatter fields beyond the load-bearing name: and description: fields, but these custom fields are stripped before being injected into the model's context.

Current behavior

Given this SKILL.md:

---
name: subtask
description: "Load when:\n\n1. user gives a terse command..."
setup: |
    All projects that depend on this skill should have as `CLAUDE.md` frontmatter:

    ```yaml
    depends:
        - skills/subtask
    ```
---

# Subtask Management

The model only sees:

# Subtask Management

The name: and description: fields are consumed by Claude Code (for the Skill tool), but the setup: field is discarded along with the rest of the frontmatter.

Expected behavior

Custom frontmatter fields should be passed through to the model's context. The model needs to see these instructions (e.g., setup: tells the model what frontmatter to add to project CLAUDE.md files when adopting the skill).

Related issue

This is similar to #13003 (CLAUDE.md frontmatter stripping), but SKILL.md has the additional constraint that name: and description: are load-bearing fields that Claude Code must parse.

Workaround

Add a second frontmatter block with the workaround comment:

---
name: subtask
description: "Load when..."
---
--- # workaround: anthropics/claude-code#13005
setup: |
    All projects that depend on this skill...
---

This preserves the load-bearing fields while allowing custom fields through to the model.

Suggested fix

In the Skill tool's content injection path:

  1. Parse and consume name: and description: as needed
  2. Pass through all other frontmatter fields to the model (either as raw frontmatter or re-serialized)

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗