writing-skills

Writing a SKILL.md file requires YAML frontmatter with valid name and description fields to ensure discovery. You structure the document with concise progressive disclosure so agents can parse instructions without hitting context limits.

Skill documentation should use concise progressive disclosure, valid YAML frontmatter, and tight trigger organization. Structuring this way improves discovery, reduces agent misinterpretation, and ensures deployment readiness before release.

Pressure-test skill documentation against baseline failures by checking agent compliance under realistic constraints. This verification catches common rationalizations and structural gaps that cause agents to drift from intended behavior during execution.

Refactoring existing SKILL.md files involves tightening triggers, reorganizing sections, and applying progressive disclosure. You preserve the core logic while improving readability and agent compliance without a full rewrite.

Agents ignore instructions when skill documentation lacks concise progressive disclosure or has weak trigger alignment. Pressure-testing against baseline failures reveals where agents rationalize skipping steps or misinterpreting vague directives.

YAML frontmatter with valid name and description fields is required for skill deployment. These metadata fields drive discovery and ensure agents can correctly identify and invoke the skill within workflow routing.