marsai:writing-skills

To structure a Claude Skill, draft a SKILL.md file with YAML frontmatter containing name and description fields, followed by a concise three-section description body. Progressive disclosure loads only frontmatter first, then the body, and finally references or scripts as required.

The RED-GREEN-REFACTOR workflow for writing Skills is a test-driven development process that validates agent behavior. RED drafts the baseline Skill, GREEN verifies it passes structural and toxicity checks, and REFACTOR optimizes the content for ASO-friendly discovery and scope discipline.

To prevent rationalization and scope creep in AI documentation, apply built-in anti-rationalization tables and strict frontmatter constraints during generation. This enforces concise descriptions, trigger guidance, and deployment readiness checks to maintain consistent agent behavior.

Yes, you need to run baseline test validation for ad-hoc Skill drafts before deployment. The standardization process enforces test-validated Skills by verifying frontmatter constraints, description structure, and safety checks to ensure high-quality, consistent agent execution.

The best way to optimize Skill descriptions for discovery is to write ASO-friendly text within the YAML frontmatter. Include a concise description with trigger guidance, followed by a short Quick Start sentence, ensuring the content passes toxicity checks and frontmatter constraints.