Agent Skills

• Agent skills in this project are stored in .claude/skills/ directory
• Each skill is a folder with a SKILL.md file inside it
• The skill folder name must match the name field in the SKILL.md frontmatter
• The frontmatter requires name (lowercase alphanumeric with hyphens only, no start/end hyphens, no consecutive hyphens) and description (describes what the skill does and when to use it)
• The Markdown body after the frontmatter contains the skill instructions with no format restrictions
• Skills can have optional subdirectories: scripts/ for executable code, references/ for documentation, assets/ for templates and resources
• Keep the main SKILL.md body under 500 lines for efficiency; move detailed reference material to separate files in references/
• When referencing other files in a skill, use relative paths from the skill root (e.g., references/REFERENCE.md or scripts/extract.py)
• File references should be one level deep from SKILL.md to avoid deeply nested reference chains
• All skill improvements should be made by editing the SKILL.md file in place, since skills are Git-tracked files in the codebase
• When improving a skill based on work session learnings, edit the SKILL.md file to reflect new insights
• After updating a skill file, the next agent session will load the improved skill automatically
• Progressive disclosure keeps skills efficient: metadata loads at startup (~100 tokens), full instructions load on activation (<5000 tokens recommended), resources load on demand
• Test your skill improvements by thinking through: Does the description clearly indicate when to use it? Are the instructions clear and self-contained? Can the agent follow them without additional context?
• Document why you’re making a skill improvement in the Git commit message if the change needs explanation