# Best Practices for Creating Commands A quick guide to writing effective commands in the `.cursor/commands` directory, based on what actually works. ## Structure Your Command Right **Make it crystal clear what you're doing** - Start with a title that says exactly what the command does - Explain why someone would use it in the first paragraph - Number every step so people can track progress **Use dependencies to show the flow** - Mark steps as "DEPENDS ON STEP 1" so people know the order matters - Group related steps into phases (like your `process-session` does) - Use checkboxes (✅) to mark completed steps **Highlight the important stuff** - Use "CRITICAL" or "MANDATORY" for steps that can't be skipped - Add "⚠️ EASY TO MISS" warnings for things people always forget - Give specific examples of what to do and what to avoid ## Prevent Common Mistakes **Include a "Common Mistakes" section** - List the things people mess up most often - Explain why each mistake is bad - Show the right way to do it **Add validation checklists** - Give people a way to double-check their work - Include final validation steps before completion - Make it obvious when something's done right **Be specific about the details** - Use exact file paths and naming conventions - Show examples of correct vs incorrect output - Explain what happens if you skip a step ## Make It Actually Work **Create supporting scripts when needed** - If something's complex, write a script (like `seealso.js` or `checkSimilarNames.js`) - Make scripts reusable across different commands - Include proper error handling and logging **Handle the file system properly** - Use absolute paths when possible - Account for template processing and automatic updates - Think about the order of operations **Test with real data** - Try your command with actual files - Check that the output makes sense - Make sure it handles edge cases ## The Essentials Every good command needs: - ✅ Clear purpose and numbered steps - ✅ Dependencies marked between steps - ✅ Critical warnings and common mistakes - ✅ Validation checklists - ✅ Supporting scripts for complex stuff - ✅ Real examples and specific instructions Keep it simple, test it thoroughly, and make it obvious when something's wrong. Your `process-session` command is a great example of all these principles in action.