How YAML Frontmatter Controls Skill Invocation in Claude Code and Qwen Code

YAML frontmatter in command markdown files supplies Claude Code and Qwen Code with declarative metadata that determines when and how skills register, surface in the UI, and persist across conversational sessions.

The ayghri/i-have-adhd repository demonstrates how a single skill definition can power multiple AI coding assistants through declarative configuration. By parsing the YAML frontmatter block at the top of command files, both runtimes register skills without executing the actual behavior logic until invocation occurs.

Anatomy of the YAML Frontmatter Block

The YAML frontmatter resides at the top of the command file located at .opencode/command/i-have-adhd.md. This block is delimited by triple dashes (---) and contains purely declarative metadata that the runtimes consume during initialization.

The Description Field

The description field provides a short natural-language summary that appears in the command palette of both Claude Code and Qwen Code. When users browse available skills, this text explains the skill's purpose and indicates how long it will remain active during the session.

The ApplyTo Selector

The optional applyTo field acts as a runtime selector. When set to "claude", the command registers exclusively for Claude Code sessions; when set to "qwen", it targets Qwen Code specifically. Omitting this field makes the command available to both runtimes by default.

How Claude Code Processes Frontmatter Metadata

When Claude Code initializes, it scans .opencode/command/i-have-adhd.md and parses the YAML frontmatter to extract registration parameters. If the applyTo field is present and set to claude, or if the field is absent, Claude Code registers the command as a Claude-specific skill.

Upon invocation—either through the /i-have-adhd command or automatic activation—the runtime loads the associated skill definition from skills/i-have-adhd/SKILL.md. Claude Code then applies the rule set defined in that file to every subsequent response until the user explicitly disables the skill. The description remains visible in the UI throughout the session to indicate the active state.

How Qwen Code Processes Frontmatter Metadata

Qwen Code performs an identical parsing sequence when loading extensions. The runtime reads the frontmatter from the same .opencode/command/i-have-adhd.md file and uses the description to populate its command palette. When applyTo is set to "qwen", the Qwen-compatible skill registers exclusively for Qwen Code sessions.

After registration, invoking the skill triggers Qwen Code to load skills/i-have-adhd/SKILL.md and inject its rules into each response for the duration of the session. This mechanism ensures that the same declarative configuration drives runtime-specific behavior without duplicating the command file.

The Relationship Between Frontmatter and Skill Execution

The YAML frontmatter does not contain executable code; it serves purely as a declaration mechanism. The actual behavior is defined in skills/i-have-adhd/SKILL.md, which both runtimes reference after parsing the frontmatter.

This separation allows the ayghri/i-have-adhd repository to maintain a single source of truth for command metadata while supporting platform-specific manifests—.claude-plugin/plugin.json for Claude Code and qwen-extension.json for Qwen Code—that point to the same underlying skill logic.

Cross-Platform Configuration Examples

Universal Frontmatter for Both Runtimes

The following configuration makes the skill available to both Claude Code and Qwen Code:

---
description: Shape output for a reader with ADHD for the rest of this session
---

This description appears in the command palettes of both runtimes, and the absence of applyTo permits universal registration.

Runtime-Specific Frontmatter

To restrict a skill to Claude Code only, add the applyTo field:

---
description: Shape output for a reader with ADHD for the rest of this session
applyTo: claude
---

Changing the value to qwen would make the command available exclusively to Qwen Code, while the corresponding qwen-extension.json manifest would reference the same underlying files.

Summary

• YAML frontmatter in .opencode/command/i-have-adhd.md provides the metadata required for runtime registration.
• The description field surfaces the skill in command palettes and indicates active status during sessions.
• The applyTo field controls runtime-specific availability, accepting "claude" or "qwen" values.
• Declaration and implementation remain separate: frontmatter registers the skill while skills/i-have-adhd/SKILL.md defines the actual behavior rules.
• Skills persist for the entire session once activated, applying to every subsequent response until disabled.

Frequently Asked Questions

What happens if the applyTo field is missing from the frontmatter?

When the applyTo field is omitted, both Claude Code and Qwen Code treat the command as universally available. The skill registers for both runtimes during their respective initialization sequences, provided their manifests (.claude-plugin/plugin.json and qwen-extension.json) reference the command file.

Can I use the same skill file for both Claude Code and Qwen Code simultaneously?

Yes. Both runtimes can point to the same skills/i-have-adhd/SKILL.md file. The YAML frontmatter in .opencode/command/i-have-adhd.md handles runtime-specific registration metadata, while the skill file contains the platform-agnostic behavior rules that shape AI responses.

Where is the actual skill logic stored if not in the frontmatter?

The actual behavior resides in skills/i-have-adhd/SKILL.md. The frontmatter only contains declarative metadata like description and applyTo. When a user invokes the skill, the runtime reads the frontmatter to verify eligibility, then loads SKILL.md to apply the rule set to subsequent responses.

How long does a skill remain active once invoked through the frontmatter?

The skill remains active for the duration of the current session. Both Claude Code and Qwen Code apply the rules from SKILL.md to every response until the user disables the skill or terminates the session. The description field in the frontmatter typically reminds users that the skill is session-persistent.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}