skill-writing-best-practices_skill

Overview

This skill provides concise guidelines for writing and organizing AI agent skills, emphasizing structure, concrete examples, and clear rationale. It helps authors create scannable, testable, and maintainable skill files that other engineers can apply quickly. Use it when adding, converting, or reviewing skills to ensure consistent quality.

How this skill works

The skill inspects new or changed skill content and folder layout to verify a predictable structure, clear per-rule documents, and presence of concrete code examples and why-explanations. It flags missing examples, vague guidance, and inconsistent writing style, and recommends fixes to make rules actionable and scannable. It focuses on structure, content quality, and readable style rather than implementation language.

When to use it

• Creating a new skill from scratch
• Converting existing documentation into skill format
• Reviewing or improving an existing skill
• Extracting coding patterns from a codebase
• Validating skill files before merge

Best practices

• Organize skills into a clear directory with one main summary and separate detailed rule documents.
• Give each rule a short description, a ‘why’ section, and at least one concrete code example showing bad vs good.
• Explain why a rule matters (tests, clarity, flexibility), not just what to do.
• Write naturally and concisely; avoid AI-style phrasing and excessive formatting.
• Group related rules by impact or category so readers can scan and prioritize.
• Be honest: include situations where the pattern should not be used.

Example use cases

• Turning a style guide or README-like document into a set of actionable rules with examples.
• Auditing a collection of skills to ensure each rule includes code samples and rationale.
• Documenting coding conventions extracted from a legacy codebase with clear migration examples.
• Creating a new topic skill that other contributors will extend with consistent structure.
• Preparing a review checklist to run on changed skill files before merging.