docs: clarify YAML-first custom modes behavior

[Olusammytee]

Summary

• clarify that imported mode files are YAML (.yaml)
• tighten manual configuration guidance to treat JSON as legacy fallback
• add a note explaining why YAML and JSON files can coexist and why YAML should be edited first

Why

This reduces confusion around mode file formats and aligns docs with YAML-first behavior.

Migrated from Kilo-Org/kilocode#5988 due docs repo migration.

[Copilot]

Pull request overview

This pull request clarifies and emphasizes the YAML-first approach for custom mode configuration in Kilo Code documentation. The changes align the documentation with the actual behavior where YAML files are prioritized over JSON for mode configuration.

Changes:

• Added explicit .yaml file extension notation in import instructions for clarity
• Restructured manual configuration guidance to position custom_modes.yaml as primary and custom_modes.json as legacy fallback
• Added an informational callout explaining why both YAML and JSON files may coexist and the recommendation to edit YAML files first

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.