skill-creator: Generated skills fail validation due to missing frontmatter property documentation

The skill-creator skill does not properly document or validate allowed YAML frontmatter properties, causing users to create skills that fail during importing in Claude app

Fix for the issue: https://github.com/anthropics/skills/pull/36

Problem

When users create skills using the skill-creator skill and add common frontmatter properties like version, author, or category, the Claude app fails when user try to add generated skils with these error:
"unexpected key in SKILL.md frontmatter: properties must be in ('name', 'description', 'license', 'allowed-tools', 'metadata')"

Root Cause

The skill-creator skill has three main issues:

1. Missing validation in quick_validate.py: The validation script doesn't check for unexpected frontmatter properties, allowing users
to create invalid skills that only fail during packaging.
2. Incomplete documentation in SKILL.md: The documentation doesn't clearly list which frontmatter properties are allowed vs. disallowed, leaving users to discover this through trial and error.
3. Template lacks guidance in init_skill.py: The generated SKILL.md template doesn't include examples of optional frontmatter fields or warnings about unsupported properties.

Steps to Reproduce

1. Use skill-creator to initialize a new skill:
scripts/init_skill.py my-test-skill --path /tmp
2. Add common (but unsupported) frontmatter properties to the generated SKILL.md:

name: my-test-skill
description: Test skill
version: 1.0.0
author: John Doe

3. Attempt to package the skill:
scripts/package_skill.py /tmp/my-test-skill
4. Observe validation failure with unclear error message.

Expected Behavior

- The quick_validate.py script should catch invalid frontmatter properties early with clear error messages
- The SKILL.md documentation should clearly list allowed properties (required: name, description; optional: license, allowed-tools, metadata)
- The init_skill.py template should include commented examples of optional fields and warn against unsupported properties

Actual Behavior

- Validation doesn't catch invalid properties until packaging
- Documentation doesn't specify allowed/disallowed properties
- Template provides no guidance on optional frontmatter fields
- Error messages don't clearly indicate which properties are allowed

Impact

- User Experience: Confusing error messages that require debugging the validation code to understand
- Time Wasted: Users create skills with invalid frontmatter that only fail at packaging time
- Discoverability: No clear way to learn about optional frontmatter fields like allowed-tools or metadata

Proposed Solution

I've created a pull request that addresses all three issues:

1. Enhanced validation: Added frontmatter property validation to quick_validate.py that:
- Checks for allowed properties: name, description, license, allowed-tools, metadata
- Rejects unexpected properties with clear error messages listing both the invalid properties and allowed ones
- Properly handles nested YAML (e.g., keys under metadata)
- Validates description length (max 1024 characters per spec)
2. Improved documentation: Updated SKILL.md to:
- Clearly list required fields (name, description)
- Clearly list optional fields (license, allowed-tools, metadata)
- Document field constraints (hyphen-case naming, character limits)
- Explicitly warn against unsupported properties like version
3. Better template: Updated init_skill.py template to:
- Include commented examples of all optional frontmatter fields
- Show proper YAML structure for allowed-tools and metadata
- Note the 1024 character limit for descriptions

Environment

- Repository: anthropics/skills
- Skill: skill-creator
- Affected files:
- skill-creator/scripts/quick_validate.py
- skill-creator/SKILL.md
- skill-creator/scripts/init_skill.py

Additional Context

The allowed frontmatter properties are documented in the https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview, but the skill-creator skill doesn't enforce or document these constraints, leading to user confusion.