skill-writer

Optimizing Claude Skills enforces trigger-only descriptions and progressive disclosure to reduce context bloat. It reworks SKILL.md files to follow the “Use when…” rule and moves reference-heavy material into separate directories for maintainable, token-efficient loading.

Structuring a SKILL.md file for progressive disclosure involves keeping the main instructions lightweight and moving duplicated or oversized content into a references directory. This layout enforces naming consistency and ensures only necessary context loads during activation.

Validating YAML frontmatter and lint rules for Claude Skills checks name-to-directory matching and metadata weight. It guides you through structural constraints to ensure your SKILL.md passes lint-style validation and satisfies activation requirements.

Claude Skills fail to activate inconsistently when descriptions contain workflow summaries instead of trigger conditions. Reworking the metadata to follow strict “Use when…” phrasing improves skill discovery accuracy and resolves unreliable activation.

You can split oversized Claude Skill content into separate reference files to achieve scalable maintainability. Moving reference-heavy material out of the main SKILL.md file applies token-efficient progressive disclosure and reduces context usage.

Choosing a specific Claude Skill type is needed when aligning scope and naming conventions for your project. Selecting the right category—such as reference, pattern, migration, or discipline—ensures consistent structure and reliable activation behavior.