[DOCS] Custom Skills and Claude Code plugin Skills silently use different frontmatter schemas

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://support.claude.com/en/articles/12512198-how-to-create-custom-skills https://code.claude.com/docs/en/skills

Section/Topic

Skill frontmatter fields / argument-hint

Current Documentation

Skills docs describe frontmatter fields like argument-hint, disable-model-invocation,
and user-invocable as part of the Skills spec, without noting these are Claude Code-only
extensions on top of the portable Agent Skills spec (agentskills.io).

What's Wrong or Missing?

Custom skills uploaded via claude.ai/Team, the Skills API, or packaged with
scripts/package_skill.py are validated against a stricter schema that only allows:
name, description, license, compatibility, metadata, allowed-tools. Adding argument-hint
to one of these fails packaging with:
"Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are:
allowed-tools, compatibility, description, license, metadata, name"

Meanwhile, skills distributed as Claude Code plugins (via a marketplace) support
argument-hint and render it as an input-box placeholder — including inside the
Claude Desktop chat surface, not just the Code tab. Nothing in the docs states
these are two different schemas, or which distribution path gives you which fields.

Suggested Improvement

Add a comparison table to the Skills documentation showing which frontmatter fields
are supported by: (1) the portable custom-skill spec (claude.ai/Team upload, Skills API),
vs (2) Claude Code plugin skills. Note that fields outside the portable spec fail
validation at packaging time rather than being silently ignored.

Impact

Medium - Makes feature difficult to understand

Additional Context

Related: anthropics/claude-code#46626 (argument-hint not shown for plugin skills in some cases),
#43401 (feature request to add argument-hint to base Skills spec)