Improving Skills — Audit & Optimization Guide

Structured workflow for auditing and improving agent skills, instruction files (AGENTS.md, CLAUDE.md, GEMINI.md), and cross-platform compatibility.

Quick audit (5 minutes)

1. Read the skill's SKILL.md and list all files in the directory
2. Check frontmatter against the specification (Step 2 below, including the skills-ref validate run)
3. Evaluate description quality (trigger coverage, third person, specificity)
4. Scan content for anti-patterns (see anti-patterns.md)
5. Generate a prioritized improvement report (Step 5 template)

Full audit workflow

Step 1: Inventory the skill

Read the complete skill directory structure and all files.