skill-authoring

Create a discoverable Claude Skill by structuring YAML frontmatter with name, description, and optional tools fields, then writing clear trigger-based descriptions in SKILL.md. Use progressive disclosure—keep SKILL.md concise and place detailed patterns in reference.md—to improve discovery and usability.

Organize Skill documentation using progressive disclosure: frontmatter in SKILL.md with essential metadata, concise task description, and quick start; move detailed patterns, testing strategies, and examples to reference.md. This structure balances discoverability with comprehensive guidance.

Claude Skill YAML frontmatter must include name and description fields; tools are optional. Descriptions should be trigger-based and written in third person to support discovery. Enforce these constraints consistently across new and updated skills.

Validate your Skill by verifying YAML frontmatter loads correctly, testing that it's reusable, and confirming it appears in discovery tooling. Use example-driven testing to ensure the skill works as documented and follows established best-practice patterns.

Third-person descriptions improve Skill discoverability by matching search behavior and maintaining consistency across the Skill ecosystem. This pattern, combined with structured content like tables and quick references, makes skills easier to find and understand.

Yes, apply best-practice patterns to existing skills by refactoring YAML frontmatter, rewriting descriptions for clarity and discoverability, reorganizing content for progressive disclosure, and adding testing validation. This ensures maintainability and consistent discovery.