skill-developer

To create a Claude Code skill, you write a SKILL.md file with proper frontmatter, add a corresponding entry to skill-rules.json, and test activation using manual commands. This process ensures your skill triggers correctly and complies with structural best practices.

A valid SKILL.md file requires specific frontmatter fields to define its metadata, including naming conventions, trigger types, and skill rules. Adhering to this required structure ensures Claude Code can properly parse, index, and activate the skill during relevant workflows.

Skill triggers in Claude Code activate based on defined keywords, intent patterns, file paths, or content patterns. Hooks enforce specific behaviors, such as guardrails or domain rules, and include skip conditions to prevent unnecessary activation during unrelated coding tasks.

The 500-line rule is a best practice limit applied during skill development to maintain reliability and safety. It encourages using a progressive disclosure pattern with reference files, keeping the main SKILL.md concise while storing detailed logic in optional resources.

If your Claude Code skill is not activating, you should debug the trigger configuration and verify the skill-rules.json entry. Following the validation and troubleshooting steps ensures your frontmatter, hooks, and intent patterns are correctly recognized by the system.

Yes, progressive disclosure is a supported pattern for Claude Code skills that separates core logic from detailed references. By structuring optional resources effectively, you maintain a concise main file while providing depth when needed, ensuring safe and reliable skill execution.