skill-development

To structure a Claude Code skill for auto-discovery, create a valid skill directory with a required SKILL.md entry point and optional supporting folders like scripts/, references/, and assets/ to organize deterministic scripts and on-demand documentation separately.

Progressive disclosure in skill development is a context loading model that loads YAML metadata first, the full SKILL.md on trigger, and bundled resources on demand to keep context tight and scalable across large skill structures.

Writing reliable SKILL.md frontmatter requires including a valid name and a third-person description containing concrete trigger phrases, ensuring the skill can be correctly auto-discovered and activated by the Claude Code environment.

Existing markdown documentation must be reorganized into a valid skill unit structure to work with Claude Code, separating the SKILL.md entry point from references and adding required frontmatter with specific trigger phrases for proper activation.

SKILL.md body instructions should follow an imperative writing style with specific, actionable directives rather than descriptive text, reducing broken activations and ensuring deterministic execution behavior within the Claude Code environment.

Claude Code skills fail to activate on trigger phrases when the SKILL.md frontmatter lacks a third-person description with concrete trigger keywords, or when the directory structure incorrectly bundles references into the main file, inflating context size.