skill-authoring

Skill metadata for semantic activation requires concise frontmatter with name and description fields. Use failure-mode language under 200 characters to ensure correct tool contracts and cross-CLI parity across Claude Code, Codex, and Gemini.

Progressive disclosure is a skill authoring structure where the main SKILL.md file contains roughly 80% of routine answers, while sub-files handle the long tail of edge cases to maintain listing visibility and correct tool contracts.

Skill invisibility usually stems from description-length budget overruns or missing failure-mode language. Auditing SKILL.md frontmatter constraints and aligning declared tools with body invocations resolves indexing issues and restores semantic activation.

Frontmatter validation requires no external dependencies. It enforces internal constraints by checking that the name and description fields exist, descriptions stay under 200 characters, and declared tools match body and sub-file invocations for cross-CLI parity.

Auditing a SKILL.md file involves checking description-length budgets, verifying failure-mode language, confirming tools-list accuracy against body invocations, and ensuring routine questions are answerable without expanding sub-files for proper progressive-disclosure coverage.

You should not overload SKILL.md when routine answers exceed the 80% threshold. Move edge-case documentation to sub-files to maintain listing visibility, preserve semantic activation, and ensure cross-CLI overlay structure remains portable.